A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file profileCapture.ts — recorded frames as a portable document.
*/
import type { QualityReport } from '../render/quality';
import {
buildFrameProfile,
meanFrameProfile,
isNativeProfileCounter,
type FrameProfile,
type ScopeCost,
type SystemCost,
} from './frameProfile';
/** Bumped when a reader can no longer make sense of an older file. */
export const PROFILE_CAPTURE_VERSION = 1;
/** Where a capture came from. Every field optional: a bare App knows none of it. */
export interface CaptureSource {
/** 'edit' / 'play' in the editor; a shipped build names its platform. */
realm?: string;
engineVersion?: string;
platform?: string;
gpu?: string;
/** Free-form: device model, build id, the scene under test. */
label?: string;
}
/**
* One frame, in the terms the profile model reads. Deliberately the same
* vocabulary a live frame is measured in, so a capture needs no translation
* and no reader can drift from what the panel shows.
*/
export interface CapturedFrame {
quality?: QualityReport;
id: number;
dtMs: number;
systems: SystemCost[];
scopes: ScopeCost[];
/** Scopes measured inside wasm. */
nativeScopes?: ScopeCost[];
/** -1 when no GPU timer answered. */
gpuMs?: number;
counters?: Record<string, number>;
drawCalls?: number;
triangles?: number;
entities?: number;
memory?: {
wasmBytes?: number; jsHeapBytes?: number; vramBytes?: number;
/** Decoded audio resident, the clips streamed instead, and the PCM that saved (estimate). */
audioBytes?: number; audioStreamedCount?: number; audioStreamedSavedBytes?: number;
};
/** Editor-only. Absent from anything a shipped game records. */
editor?: {
ms: number;
phases: Record<string, number>;
/** Brackets INSIDE a phase above, already counted by it. Optional: a
* capture written before they existed simply has none. */
parts?: Record<string, number>;
};
}
export interface ProfileCapture {
version: number;
generatedAt: string;
source: CaptureSource;
/** The frame budget the capture was judged against (ms). */
budgetMs: number;
frames: CapturedFrame[];
/** Main-thread long tasks, for correlating a spike the frames cannot explain. */
longTasks?: Array<{ startMs: number; ms: number; name: string }>;
}
/** What a set of frames came to. The one summary every reader shows. */
export interface CaptureSummary {
frames: number;
budgetMs: number;
fps: number;
p50: number;
p95: number;
p99: number;
/** Frames over the budget by half again — a visible stutter. */
longFrames: number;
worstFrameMs: number;
worstFrameId: number | null;
/** The window's cost, per frame. */
mean: FrameProfile;
drawCalls: number;
triangles: number;
entities: number;
/** Named counters, averaged per frame. */
counters: Record<string, number>;
}
/** p-th percentile (0..100) of an unsorted sample; 0 for an empty set. */
export function percentile(values: readonly number[], p: number): number {
if (values.length === 0) return 0;
const s = [...values].sort((a, b) => a - b);
const i = Math.min(s.length - 1, Math.max(0, Math.round((p / 100) * (s.length - 1))));
return s[i];
}
/** Fold one captured frame into its cost tree. */
export function frameProfileOf(frame: CapturedFrame): FrameProfile {
return buildFrameProfile({
frameMs: frame.dtMs,
systems: frame.systems,
scopes: frame.scopes,
nativeScopes: frame.nativeScopes,
gpuMs: frame.gpuMs,
});
}
function meanOf(frames: readonly CapturedFrame[], pick: (f: CapturedFrame) => number): number {
if (frames.length === 0) return 0;
let total = 0;
for (const f of frames) total += pick(f);
return total / frames.length;
}
/**
* Summarize frames the way every reader wants them: the live window an agent
* asks for, an imported file, and a report a shipped build hands back all go
* through here, so none of them can compute a different fps from the same frames.
*/
export function summarizeFrames(frames: readonly CapturedFrame[], budgetMs = 1000 / 60): CaptureSummary {
const dts = frames.map((f) => f.dtMs);
const p50 = percentile(dts, 50);
let worst: CapturedFrame | null = null;
for (const f of frames) if (!worst || f.dtMs > worst.dtMs) worst = f;
const counters: Record<string, number> = {};
for (const f of frames) {
const quantities = { ...f.counters };
for (const scope of f.nativeScopes ?? []) {
if (isNativeProfileCounter(scope.name) && quantities[scope.name] === undefined) {
quantities[scope.name] = scope.ms;
}
}
for (const k in quantities) counters[k] = (counters[k] ?? 0) + quantities[k];
}
if (frames.length > 0) for (const k in counters) counters[k] /= frames.length;
return {
frames: frames.length,
budgetMs,
fps: p50 > 0 ? Math.round(1000 / p50) : 0,
p50,
p95: percentile(dts, 95),
p99: percentile(dts, 99),
longFrames: dts.filter((d) => d >= budgetMs * 1.5).length,
worstFrameMs: worst ? worst.dtMs : 0,
worstFrameId: worst ? worst.id : null,
mean: meanFrameProfile(frames.map(frameProfileOf)),
drawCalls: meanOf(frames, (f) => f.drawCalls ?? 0),
triangles: meanOf(frames, (f) => f.triangles ?? 0),
entities: meanOf(frames, (f) => f.entities ?? 0),
counters,
};
}
export function summarizeCapture(capture: ProfileCapture): CaptureSummary {
return summarizeFrames(capture.frames, capture.budgetMs);
}
/**
* Read a capture from JSON, or say what is wrong with it. Returns a refusal
* rather than throwing so a UI can show the reason: a file picked by hand is
* the one input guaranteed to sometimes be the wrong file.
*/
export function parseProfileCapture(text: string): { capture: ProfileCapture } | { error: string } {
let raw: unknown;
try {
raw = JSON.parse(text);
} catch (e) {
return { error: `not JSON: ${e instanceof Error ? e.message : String(e)}` };
}
if (typeof raw !== 'object' || raw === null) return { error: 'not a capture (expected an object)' };
const c = raw as Partial<ProfileCapture>;
if (typeof c.version !== 'number') return { error: 'not a capture (no version)' };
if (c.version > PROFILE_CAPTURE_VERSION) {
return { error: `capture version ${c.version} is newer than this editor reads (${PROFILE_CAPTURE_VERSION})` };
}
if (!Array.isArray(c.frames)) return { error: 'not a capture (no frames)' };
for (const f of c.frames) {
if (typeof f?.dtMs !== 'number' || !Array.isArray(f?.systems) || !Array.isArray(f?.scopes)) {
return { error: 'frames are not in the capture format (need dtMs, systems, scopes)' };
}
}
return {
capture: {
version: c.version,
generatedAt: typeof c.generatedAt === 'string' ? c.generatedAt : '',
source: (c.source ?? {}) as CaptureSource,
budgetMs: typeof c.budgetMs === 'number' && c.budgetMs > 0 ? c.budgetMs : 1000 / 60,
frames: c.frames,
longTasks: Array.isArray(c.longTasks) ? c.longTasks : undefined,
},
};
}