Skip to content

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.

6.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    profileRecorder.ts — a shipped game recording its own frames.
 */
import type { App, Plugin } from './app';
import { Renderer } from '../render/renderer';
import { engineApi } from '../ecs/bridge/engineApi';
import { Audio } from '../audio/Audio';
import {
    PROFILE_CAPTURE_VERSION,
    type CaptureSource,
    type CapturedFrame,
    type ProfileCapture,
} from './profileCapture';
import type { ScopeCost } from './frameProfile';

export interface ProfileRecorderOptions {
    /** Use already enabled timings without changing their instrumentation switches. */
    instrumentation?: 'enable' | 'existing';
    /** Frames kept before the oldest is dropped. 1800 is ~30s at 60Hz. */
    maxFrames?: number;
    /** The budget a reader judges the capture against. Defaults to 60Hz. */
    budgetMs?: number;
    /** Device, build, scene — whatever makes a capture identifiable later. */
    source?: CaptureSource;
}

const DEFAULT_MAX_FRAMES = 1800;

/** Chrome only; 0 where the runtime does not expose its heap. */
/** What the app's audio holds, when it has any: decoded bytes, and what streaming kept out of memory. */
function audioMemory(app: App): { audioBytes?: number; audioStreamedCount?: number; audioStreamedSavedBytes?: number } {
    if (!app.hasResource(Audio)) return {};
    const stats = app.getResource(Audio).getBufferStats();
    return { audioBytes: stats.bufferBytes, audioStreamedCount: stats.streamedCount, audioStreamedSavedBytes: stats.streamedSavedBytes };
}

function jsHeapBytes(): number {
    if (typeof performance === 'undefined') return 0;
    return (performance as Performance & { memory?: { usedJSHeapSize: number } }).memory?.usedJSHeapSize ?? 0;
}

function parseScopes(json: string | undefined): Record<string, number> {
    if (!json) return {};
    try {
        return JSON.parse(json) as Record<string, number>;
    } catch {
        return {};
    }
}

function nativeScopesOf(json: string | undefined): ScopeCost[] {
    const raw = parseScopes(json);
    const out: ScopeCost[] = [];
    for (const name in raw) out.push({ name, ms: raw[name], system: '', remainder: 'work' });
    return out;
}

/**
 * Records frames into a capture the game can hand anywhere. Measures nothing of
 * its own, so a capture cannot disagree with the profiler panel; and chooses no
 * destination — `take()` returns an object, the engine opens no socket.
 */
export class ProfileRecorder {
    private readonly app_: App;
    private readonly options_: ProfileRecorderOptions;
    private readonly frames_: CapturedFrame[] = [];
    private recording_ = false;
    private detach_: (() => void) | null = null;
    private seq_ = 0;

    constructor(app: App, options: ProfileRecorderOptions = {}) {
        this.app_ = app;
        this.options_ = options;
    }

    get recording(): boolean {
        return this.recording_;
    }

    get frameCount(): number {
        return this.frames_.length;
    }

    /**
     * Begin recording, turning on the instrumentation it reads — both sides of
     * it, since the C++ scopes are behind their own switch and a capture missing
     * them looks like an engine that costs nothing rather than one not measured.
     */
    start(): void {
        if (this.recording_) return;
        this.frames_.length = 0;
        this.seq_ = 0;
        if (this.options_.instrumentation !== 'existing') {
            this.app_.enableStats();
            engineApi(this.app_)?.engine_setCpuProfiling?.(true);
        }
        this.recording_ = true;
        this.detach_ = this.app_.onFrameEnd((dtMs) => this.capture_(dtMs));
    }

    /** Stop recording and put the engine's own profiling back down. */
    stop(): void {
        if (!this.recording_) return;
        this.recording_ = false;
        this.detach_?.();
        this.detach_ = null;
        if (this.options_.instrumentation !== 'existing') engineApi(this.app_)?.engine_setCpuProfiling?.(false);
    }

    /** Throw away what has been recorded, keeping the recorder running. */
    clear(): void {
        this.frames_.length = 0;
    }

    /**
     * The capture so far. Recording may continue; the frames are copied out, so
     * the returned document does not change under a reader.
     */
    take(): ProfileCapture {
        return {
            version: PROFILE_CAPTURE_VERSION,
            generatedAt: new Date().toISOString(),
            source: this.options_.source ?? {},
            budgetMs: this.options_.budgetMs ?? 1000 / 60,
            frames: this.frames_.slice(),
        };
    }

    private capture_(dtMs: number): void {
        const costs = this.app_.getFrameCosts();
        if (!costs) return;
        const m = engineApi(this.app_);
        const render = Renderer.getStats();
        const frame: CapturedFrame = {
            id: this.seq_++,
            dtMs,
            systems: costs.systems,
            scopes: costs.scopes,
            nativeScopes: nativeScopesOf(m?.engine_getCpuScopes?.()),
            gpuMs: m?.renderer_getGpuTimeMs?.() ?? -1,
            counters: parseScopes(m?.engine_getCounters?.()),
            drawCalls: render.drawCalls,
            triangles: render.triangles,
            entities: this.app_.getEntityCount(),
            memory: {
                wasmBytes: this.app_.wasmModule?.HEAPU8?.byteLength ?? 0,
                jsHeapBytes: jsHeapBytes(),
                vramBytes: m?.renderer_getEstimatedGpuBytes?.() ?? 0,
                ...audioMemory(this.app_),
            },
        };
        this.frames_.push(frame);
        const cap = this.options_.maxFrames ?? DEFAULT_MAX_FRAMES;
        if (this.frames_.length > cap) this.frames_.shift();
    }
}

/**
 * Installs a {@link ProfileRecorder} and hands it to the game. Recording is NOT
 * started: a shipped build pays for the instrumentation only from the moment
 * something asks it to.
 */
export class ProfileRecorderPlugin implements Plugin {
    readonly name = 'profileRecorder';
    readonly profileDomain = 'diagnostics';
    private recorder_: ProfileRecorder | null = null;

    constructor(
        private readonly options_: ProfileRecorderOptions = {},
        private readonly onReady_?: (recorder: ProfileRecorder) => void,
    ) {}

    /** The recorder, once the plugin has been built into an App. */
    get recorder(): ProfileRecorder | null {
        return this.recorder_;
    }

    build(app: App): void {
        this.recorder_ = new ProfileRecorder(app, this.options_);
        this.onReady_?.(this.recorder_);
    }

    cleanup(): void {
        this.recorder_?.stop();
        this.recorder_ = null;
    }
}