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.

8.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    report.ts
 * @brief   What residency did, as numbers something outside the frame can check.
 *
 * @details A picture cannot answer this. "The far cell is not drawn" and "the far
 *          cell does not exist" look identical from a camera, and the difference
 *          between them is the whole feature — so what is published is the count
 *          of things that ARE, per cell, beside what the cook said the cell holds.
 *
 *          Read-only, and residency-owned facts only: how many bodies physics
 *          still has is physics' answer, and a residency report that reached for
 *          it would be the second author this design exists to avoid.
 */

import type { App } from '../app/app';
import { SceneManager } from '../scene/sceneManager';
import { WorldStreaming, type CellDelivery } from './WorldStreamer';
import type { RenderReadinessStamp } from '../render/renderReadiness';
import { stableEntityId } from './identity';
import { manifestPlane } from './cells';
import { renderableComponents } from '../ecs/component';

/** @experimental */
export interface WorldResidencyReport {
    /** False when this build has no cooked world; every other field is empty. */
    streamed: boolean;
    cellCount: number;
    /**
     * Where the cells ARE, in manifest order — the ground each name stands for.
     *
     * Every other list here is names, and a name cannot be drawn. A reader that
     * had to find the coordinates elsewhere would be reading a second copy of
     * the partition, which agrees with this one only until one of them moves.
     */
    cells: Array<{ name: string; x: number; z: number }>;
    /** Edge of one grid square, world units — what the coordinates above scale by. */
    cellSize: number;
    /** The plane the cells lie on: a cell's z is world z on 'xz' (the ground) and world y on 'xy' (a 2D world's screen). */
    plane: 'xz' | 'xy';
    sourceCount: number;
    desiredCells: string[];
    /** Cells any source is close enough to speculate about. */
    prefetchCells: string[];
    residentCells: string[];
    /** Ready, owning assets, and holding nothing the world can see. */
    preparedCells: string[];
    /** Of those, the ones holding a render-program claim. A prepared cell with
     *  none was readied by a host that has no renderer to ready. */
    preparedWithRenderClaim: string[];
    /** Each of those claims, and how often publication found one stale. Absent
     *  from the map = that cell holds none. */
    renderClaims: Record<string, RenderReadinessStamp & { restamps: number }>;
    loadingCells: string[];
    unloadingCells: string[];
    loadCount: number;
    unloadCount: number;
    prepareCount: number;
    cancelCount: number;
    /** Of those preparations, the ones begun before anything asked for the cell. */
    prefetchRequests: number;
    /** Acquisitions given back by discarding readiness — not by unloading. */
    cancelledRefs: number;
    /** What demand FOUND, counted the instant it arrived. See `WorldStreamerStatus`. */
    prefetchHits: number;
    prefetchMisses: number;
    lastDemandToResidentMs: number;
    /** Live entities each resident cell owns. Absent from the map = not resident. */
    cellEntityCounts: Record<string, number>;
    /** Of those, how many draw anything. */
    cellRenderCounts: Record<string, number>;
    /** Acquisitions each resident cell still owes. Zero after it unloads. */
    assetRefsByCell: Record<string, number>;
    /** What the cook put in each cell — the number a live count is checked against. */
    authoredCellEntityCounts: Record<string, number>;
    /**
     * Each resident cell's authored rows and the handle each one currently has.
     * The row survives a reload and the handle does not, which is the difference
     * between an identity and a way to reach something that exists.
     */
    cellRows: Record<string, Array<{ id: number; entity: number }>>;
    /** Live entities the persistent world owns; residency never touches these. */
    persistentEntities: number;
    /** Their handles. Unchanged for the life of the world — that is the claim. */
    persistentHandles: number[];
    /**
     * Per cell: where its last delivery spent its time, and whether the ask for
     * it found readiness waiting. The phases run between frames, which is why no
     * frame profiler holds them and why a total is not a hitch.
     */
    delivery: Record<string, CellDelivery>;
}

const EMPTY: WorldResidencyReport = {
    streamed: false, cellCount: 0, cells: [], cellSize: 0, plane: 'xz', sourceCount: 0,
    desiredCells: [], prefetchCells: [], residentCells: [], preparedCells: [],
    preparedWithRenderClaim: [], renderClaims: {},
    loadingCells: [], unloadingCells: [],
    loadCount: 0, unloadCount: 0, prepareCount: 0, cancelCount: 0,
    prefetchRequests: 0, cancelledRefs: 0,
    prefetchHits: 0, prefetchMisses: 0, lastDemandToResidentMs: 0,
    cellEntityCounts: {}, cellRenderCounts: {}, assetRefsByCell: {},
    authoredCellEntityCounts: {}, cellRows: {},
    persistentEntities: 0, persistentHandles: [], delivery: {},
};

/**
 * Residency as it stands this instant.
 *
 * @experimental
 */
export function worldResidencyReport(app: App): WorldResidencyReport {
    if (!app.hasResource(WorldStreaming) || !app.hasResource(SceneManager)) return { ...EMPTY };
    const streamer = app.getResource(WorldStreaming);
    const manifest = streamer.manifest;
    if (manifest === null) return { ...EMPTY };
    const scenes = app.getResource(SceneManager);
    const status = streamer.status();

    const cellEntityCounts: Record<string, number> = {};
    const cellRenderCounts: Record<string, number> = {};
    const assetRefsByCell: Record<string, number> = {};
    const authoredCellEntityCounts: Record<string, number> = {};
    const cellRows: Record<string, Array<{ id: number; entity: number }>> = {};
    const drawing = renderableComponents();
    for (const cell of manifest.cells) {
        authoredCellEntityCounts[cell.name] = cell.entityCount;
        const context = scenes.getScene(cell.name);
        // A cell nothing brought in has no row at all, which is the difference
        // between "not here" and "here and empty" that a zero would hide.
        if (context === null) continue;
        let drawn = 0;
        const rows: Array<{ id: number; entity: number }> = [];
        for (const entity of context.entities) {
            if (drawing.some((component) => app.world.has(entity, component))) drawn++;
            const authored = stableEntityId(app, entity);
            if (authored !== undefined) rows.push({ id: authored, entity });
        }
        cellEntityCounts[cell.name] = context.entities.size;
        cellRenderCounts[cell.name] = drawn;
        cellRows[cell.name] = rows.sort((a, b) => a.id - b.id);
        assetRefsByCell[cell.name] = scenes.assetScopeFor(cell.name)?.size ?? 0;
    }

    const persistent = [...(scenes.getScene(manifest.scene)?.entities ?? [])].sort((a, b) => a - b);
    return {
        streamed: true,
        cellCount: status.cellCount,
        cells: manifest.cells.map((cell) => ({ name: cell.name, x: cell.x, z: cell.z })),
        cellSize: manifest.cellSize,
        plane: manifestPlane(manifest),
        sourceCount: status.sourceCount,
        desiredCells: status.desiredCells,
        prefetchCells: status.prefetchCells,
        residentCells: status.residentCells,
        preparedCells: status.preparedCells,
        preparedWithRenderClaim:
            status.preparedCells.filter((c) => streamer.renderReadinessOf(c) !== null),
        renderClaims: Object.fromEntries(
            [...status.preparedCells, ...status.residentCells]
                .map((c) => [c, streamer.renderReadinessOf(c)])
                .filter((row): row is [string, RenderReadinessStamp] => row[1] !== null)
                .map(([c, stamp]) => [c, { ...stamp, restamps: streamer.restampsOf(c) }])),
        loadingCells: status.loadingCells,
        unloadingCells: status.unloadingCells,
        loadCount: status.loadCount,
        unloadCount: status.unloadCount,
        prepareCount: status.prepareCount,
        cancelCount: status.cancelCount,
        prefetchRequests: status.prefetchRequests,
        cancelledRefs: status.cancelledRefs,
        prefetchHits: status.prefetchHits,
        prefetchMisses: status.prefetchMisses,
        lastDemandToResidentMs: status.lastDemandToResidentMs,
        cellEntityCounts, cellRenderCounts, assetRefsByCell, authoredCellEntityCounts,
        cellRows,
        persistentEntities: persistent.length,
        persistentHandles: persistent,
        delivery: streamer.delivery(),
    };
}