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.

11.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    frameProfile.ts — the per-frame cost model every profiler view reads.
 */
import type { QueryCost } from '../ecs/query';

export type { QueryCost };

/** Systems a project registered, as opposed to any engine plugin's. */
export const DOMAIN_SCRIPTS = 'scripts';

/** Systems registered outside both a plugin build and the project bundle. */
export const DOMAIN_UNATTRIBUTED = 'unattributed';

/** No display refreshes slower than this, so a longer block is not a present. */
export const MAX_PRESENT_WAIT_MS = 50;

/** The label of the row holding render time that no scope measured and no present explains. */
export const UNTIMED_SCOPE_LABEL = 'untimed';

/** Time under a scope that none of its children claimed. */
export type ScopeRemainder = 'work' | 'wait';

export interface SystemCost {
    readonly name: string;
    readonly ms: number;
    readonly domain: string;
    /** Absent when the system ran no query, or when accounting was off. */
    readonly query?: QueryCost;
}

export interface ScopeCost {
    readonly name: string;
    readonly ms: number;
    /** The system this ran inside; '' when it ran outside every system. */
    readonly system: string;
    readonly remainder: ScopeRemainder;
    /** The scope this ran inside. Its time is part of that scope's, not beside it. */
    readonly parent?: string;
}

export interface FrameProfileInput {
    readonly frameMs: number;
    readonly systems: readonly SystemCost[];
    readonly scopes: readonly ScopeCost[];
    /** Scopes measured inside wasm. Adopted by the wait scope of their domain. */
    readonly nativeScopes?: readonly ScopeCost[];
    readonly gpuMs?: number;
}

export type ProfileNodeKind = 'domain' | 'system' | 'scope' | 'rest';

export interface ProfileNode {
    readonly id: string;
    readonly label: string;
    readonly ms: number;
    readonly kind: ProfileNodeKind;
    readonly children: readonly ProfileNode[];
    /** On a system node that ran a query — why its time is what it is. */
    readonly query?: QueryCost;
}

/**
 * `frameMs === cpuMs + waitMs + idleMs`, and every node's ms equals the sum of
 * its children. `gpuMs` is a parallel track and is in none of those sums.
 */
export interface FrameProfile {
    readonly frameMs: number;
    readonly cpuMs: number;
    readonly waitMs: number;
    readonly idleMs: number;
    readonly gpuMs: number;
    readonly domains: readonly ProfileNode[];
}

/** Below this a row is noise, and a `rest` row for it would be rounding dust. */
const EPS_MS = 0.05;

/**
 * Average a window of frames into one profile, per frame. A node is divided by
 * the whole window, not by the frames it appeared in: dividing by its own
 * appearances would report an every-fourth-frame system four times too dear.
 * Obeys the same sums a single frame does.
 */
export function meanFrameProfile(profiles: readonly FrameProfile[]): FrameProfile {
    if (profiles.length === 0) {
        return { frameMs: 0, cpuMs: 0, waitMs: 0, idleMs: 0, gpuMs: -1, domains: [] };
    }
    const n = profiles.length;
    const withGpu = profiles.filter((p) => p.gpuMs >= 0);
    return {
        frameMs: profiles.reduce((a, p) => a + p.frameMs, 0) / n,
        cpuMs: profiles.reduce((a, p) => a + p.cpuMs, 0) / n,
        waitMs: profiles.reduce((a, p) => a + p.waitMs, 0) / n,
        idleMs: profiles.reduce((a, p) => a + p.idleMs, 0) / n,
        gpuMs: withGpu.length > 0 ? withGpu.reduce((a, p) => a + p.gpuMs, 0) / withGpu.length : -1,
        domains: meanNodes(profiles.map((p) => p.domains), n),
    };
}

function meanNodes(perFrame: ReadonlyArray<readonly ProfileNode[]>, frames: number): ProfileNode[] {
    const acc = new Map<string, { node: ProfileNode; ms: number; kids: ProfileNode[][]; query: QueryCost | null }>();
    for (const nodes of perFrame) {
        for (const node of nodes) {
            const prev = acc.get(node.id);
            if (prev) {
                prev.ms += node.ms;
                prev.kids.push([...node.children]);
                if (node.query) {
                    prev.query = prev.query
                        ? {
                            calls: prev.query.calls + node.query.calls,
                            scanned: prev.query.scanned + node.query.scanned,
                            filtered: prev.query.filtered + node.query.filtered,
                        }
                        : { ...node.query };
                }
            } else {
                acc.set(node.id, {
                    node,
                    ms: node.ms,
                    kids: [[...node.children]],
                    query: node.query ? { ...node.query } : null,
                });
            }
        }
    }
    const out: ProfileNode[] = [];
    for (const e of acc.values()) {
        out.push({
            id: e.node.id,
            label: e.node.label,
            ms: e.ms / frames,
            kind: e.node.kind,
            children: meanNodes(e.kids, frames),
            ...(e.query
                ? {
                    query: {
                        calls: e.query.calls / frames,
                        scanned: e.query.scanned / frames,
                        filtered: e.query.filtered / frames,
                    },
                }
                : {}),
        });
    }
    out.sort(byMsDesc);
    return out;
}

/** The part of a dotted scope name that names its domain. */
export function scopeDomain(name: string): string {
    const dot = name.indexOf('.');
    return dot > 0 ? name.slice(0, dot) : name;
}

function sumMs(nodes: readonly ProfileNode[]): number {
    let total = 0;
    for (const n of nodes) total += n.ms;
    return total;
}

function byMsDesc(a: ProfileNode, b: ProfileNode): number {
    return b.ms - a.ms;
}

/** The native mesh collector also publishes work counts in its scope packet.
 * These are quantities, including in existing captures, never milliseconds. */
export function isNativeProfileCounter(name: string): boolean {
    return /^render\.collect\.mesh\.(scene|depth|motion|other)\.(walks|visits)$/.test(name);
}

/**
 * Fold one frame's flat measurements into the tree the profiler renders.
 *
 * Pure, so the live editor view, an imported capture and the agent all derive
 * the same numbers from the same rule rather than each rounding their own way.
 */
export function buildFrameProfile(input: FrameProfileInput): FrameProfile {
    const nativeByDomain = new Map<string, ScopeCost[]>();
    for (const n of input.nativeScopes ?? []) {
        if (isNativeProfileCounter(n.name)) continue;
        const d = scopeDomain(n.name);
        const list = nativeByDomain.get(d);
        if (list) list.push(n); else nativeByDomain.set(d, [n]);
    }

    const named = new Set(input.scopes.map((s) => s.name));
    const nestedByParent = new Map<string, ScopeCost[]>();
    const scopesBySystem = new Map<string, ScopeCost[]>();
    for (const s of input.scopes) {
        const nested = s.parent !== undefined && named.has(s.parent);
        const groups = nested ? nestedByParent : scopesBySystem;
        const key = nested ? s.parent! : s.system;
        const list = groups.get(key);
        if (list) list.push(s); else groups.set(key, [s]);
    }
    const nestedNodes = (parent: string, parentId: string): ProfileNode[] =>
        (nestedByParent.get(parent) ?? []).map((s) => {
            const id = `${parentId}/${s.name}`;
            const children = nestedNodes(s.name, id);
            const left = s.ms - sumMs(children);
            if (children.length > 0 && left >= EPS_MS) children.push({ id: `${id}/~`, label: 'rest', ms: left, kind: 'rest', children: [] });
            children.sort(byMsDesc);
            return { id, label: s.name, ms: s.ms, kind: 'scope', children };
        });

    let waitTotal = 0;
    const domains = new Map<string, ProfileNode[]>();

    for (const sys of input.systems) {
        const children: ProfileNode[] = [];
        let systemWait = 0;

        for (const scope of scopesBySystem.get(sys.name) ?? []) {
            const adopted = scope.remainder === 'wait'
                ? (nativeByDomain.get(scopeDomain(scope.name)) ?? [])
                : [];
            const grandChildren = [...adopted.map((n): ProfileNode => ({
                id: `${sys.name}/${scope.name}/${n.name}`,
                label: n.name,
                ms: n.ms,
                kind: 'scope',
                children: [],
            })), ...nestedNodes(scope.name, `${sys.name}/${scope.name}`)];
            const unclaimed = Math.max(0, scope.ms - sumMs(grandChildren));
            const waited = scope.remainder === 'wait' ? Math.min(unclaimed, MAX_PRESENT_WAIT_MS) : 0;
            const untimed = scope.remainder === 'wait' ? unclaimed - waited : 0;
            systemWait += waited;
            if (untimed >= EPS_MS) {
                grandChildren.push({
                    id: `${sys.name}/${scope.name}/~untimed`,
                    label: UNTIMED_SCOPE_LABEL,
                    ms: untimed,
                    kind: 'rest',
                    children: [],
                });
            } else if (scope.remainder !== 'wait' && unclaimed >= EPS_MS && grandChildren.length > 0) {
                grandChildren.push({
                    id: `${sys.name}/${scope.name}/~`,
                    label: 'rest',
                    ms: unclaimed,
                    kind: 'rest',
                    children: [],
                });
            }
            grandChildren.sort(byMsDesc);
            const scopeWork = scope.ms - waited;
            children.push({
                id: `${sys.name}/${scope.name}`,
                label: scope.name,
                ms: scopeWork,
                kind: 'scope',
                children: grandChildren,
            });
        }

        const work = Math.max(0, sys.ms - systemWait);
        const rest = Math.max(0, work - sumMs(children));
        if (children.length > 0 && rest >= EPS_MS) {
            children.push({ id: `${sys.name}/~`, label: 'rest', ms: rest, kind: 'rest', children: [] });
        }
        children.sort(byMsDesc);

        waitTotal += systemWait;
        const node: ProfileNode = {
            id: sys.name,
            label: sys.name,
            ms: work,
            kind: 'system',
            children,
            ...(sys.query ? { query: sys.query } : {}),
        };
        const list = domains.get(sys.domain);
        if (list) list.push(node); else domains.set(sys.domain, [node]);
    }

    const domainNodes: ProfileNode[] = [];
    for (const [domain, systems] of domains) {
        systems.sort(byMsDesc);
        domainNodes.push({
            id: domain,
            label: domain,
            ms: sumMs(systems),
            kind: 'domain',
            children: systems,
        });
    }
    domainNodes.sort(byMsDesc);

    const cpuMs = sumMs(domainNodes);
    const frameMs = Math.max(input.frameMs, cpuMs + waitTotal);
    return {
        frameMs,
        cpuMs,
        waitMs: waitTotal,
        idleMs: Math.max(0, frameMs - cpuMs - waitTotal),
        gpuMs: input.gpuMs ?? -1,
        domains: domainNodes,
    };
}