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
feat(diagnostics): a resource census — how many of X are alive right now
esengineb35c74767668
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex b8ce93acd..ee8549c7f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1445 stable · 17 beta · 1 deprecated+Symbols: 1462 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -627,6 +627,7 @@ getMaterialRefs: (path: string) => number[]getTextureRefCount: (path: string) => numbergetTextureRefs: (path: string) => number[]getTotalRefCount: () => { textures: number; fonts: number; materials: number; }+getTotalRefRows: () => numberremoveAllRefsForEntity: (entity: number) => voidremoveFontRef: (path: string, entity: number) => voidremoveMaterialRef: (path: string, entity: number) => void@@ -673,6 +674,7 @@ get: (key: string) => T | undefinedgetOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>has: (key: string) => booleaninvalidate: (key: string) => boolean+sizes: () => { cached: number; pending: number; failed: number; }values: () => IterableIterator<T>static new <T>(dispose_?: ((value: T) => void) | undefined): AsyncCache<T>static prototype: AsyncCache<any>@@ -1505,6 +1507,82 @@ x: numbery: number```+## Census — interface+```+atMs: number+entries: ReadonlyMap<string, CensusEntry>+failedProbes: readonly string[]+```++## CensusContext — interface+```+app: App | undefined+module: ESEngineModule | null | undefined+world: World | undefined+```++## CensusDelta — interface+```+after: number+before: number+delta: number+key: string+tier: CensusTier+unit: "count" | "bytes"+```++## CensusEntry — interface+```+key: string+tier: CensusTier+unit: "count" | "bytes"+value: number+```++## CensusProbe — interface+```+id: string+read: (ctx: CensusContext) => readonly CensusEntry[] | undefined+```++## CensusReport — interface+```+cycles: number+failedProbes: readonly string[]+judgedFrom: number+leaks: readonly CensusVerdict[]+projectCycles: number+verdicts: readonly CensusVerdict[]+```++## CensusSeriesOptions — interface+```+boundedSlopeTolerance: number | undefined+projectCycles: number | undefined+trendByteBudgetPerCycle: number | undefined+warmupCycles: number | undefined+```++## CensusTier — type+```+'conserved' | 'bounded' | 'trend' | 'info'+```++## CensusVerdict — interface+```+confidentSlopePerCycle: number+first: number+key: string+last: number+leaking: boolean+projected: number+reason: string | undefined+risingFraction: number+slopePerCycle: number+tier: CensusTier+unit: "count" | "bytes"+```+## ChainCollider — const```ComponentDef<ChainColliderData>@@ -2473,6 +2551,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+es_getMallocBytes: (() => number) | undefinedesshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }geometry_create: () => numbergeometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void@@ -2566,6 +2645,7 @@ renderer_getCapturedFrameSize: () => numberrenderer_getCulled: () => numberrenderer_getDrawCalls: () => numberrenderer_getGpuTimeMs: (() => number) | undefined+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => numberrenderer_getPreviewHeight: () => numberrenderer_getPreviewPtr: () => number@@ -4903,6 +4983,7 @@ _physics_enableWheelJointMotor: (entityId: number, enable: number) => void_physics_enableWheelJointSpring: (entityId: number, enable: number) => void_physics_getAngularVelocity: (entityId: number) => number_physics_getBodyCenterOfMass: (entityId: number) => number+_physics_getBodyCount: () => number_physics_getBodyInertia: (entityId: number) => number_physics_getBodyMass: (entityId: number) => number_physics_getCollisionEnterBuffer: () => number@@ -4919,6 +5000,7 @@ _physics_getHitEventBuffer: () => number_physics_getHitEventCount: () => number_physics_getInterpolatedCount: () => number_physics_getInterpolatedTransforms: (alpha: number) => number+_physics_getJointCount: () => number_physics_getLinearVelocity: (entityId: number) => number_physics_getMoveCharacterBuffer: () => number_physics_getOverlapBuffer: () => number@@ -4933,6 +5015,8 @@ _physics_getSensorEnterCount: () => number_physics_getSensorExitBuffer: () => number_physics_getSensorExitCount: () => number_physics_getShapeCastBuffer: () => number+_physics_getShapeCount: () => number+_physics_getTrackingRows: () => number_physics_getWheelJointMotorTorque: (entityId: number) => number_physics_hasBody: (entityId: number) => number_physics_hasJoint: (entityId: number) => number@@ -8503,6 +8587,7 @@ getCppRegistry: () => CppRegistry | nullgetEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]getQueryCacheStats: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]+getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }getWasmModule: () => ESEngineModule | nullgetWorldTick: () => numbergetWorldVersion: () => number@@ -8647,6 +8732,11 @@ TransformDataAiRegistry<AiContext>```+## analyzeCensusSeries — function+```+(samples: readonly Census[], opts?: CensusSeriesOptions): CensusReport+```+## anchorPresetFields — function```(preset: AnchorPreset): AnchorFields@@ -8862,6 +8952,11 @@ BtPlugin(manifest: AddressableManifest): Catalog | undefined```+## censusProbeIds — function+```+(): string[]+```+## clearAllCaches — function```(): void@@ -8947,6 +9042,11 @@ BtPlugin(entities: readonly ExtractEntity[]): ExternalEntityRef[]```+## collectGarbage — function+```+(): boolean+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]@@ -9237,6 +9337,11 @@ DiagnosticsPlugin(source: PrefabData, instance: readonly ProcessedEntity[], options?: DiffOptions): { overrides: PrefabOverride[]; untracked: ProcessedEntity[]; orphanedSourceIds: PrefabEntityId[]; }```+## diffCensus — function+```+(before: Census, after: Census): CensusDelta[]+```+## disconnect — function @beta```(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph@@ -9437,6 +9542,16 @@ FocusPlugin(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined```+## formatCensusDiff — function+```+(before: Census, after: Census, all?: boolean): string+```++## formatCensusReport — function+```+(report: CensusReport): string+```+## fsmEdges — function```(def: FsmDefinition): FsmEdge[]@@ -10302,6 +10417,11 @@ PrefabsPlugin(key: string, def: BtDefinition): BtDefinition```+## registerCensusProbe — function+```+(probe: CensusProbe): () => void+```+## registerComponent — function```(name: string, def: AnyComponentDef): void@@ -10817,6 +10937,11 @@ StatsPlugin(world: World, tokens: ThemeTokens): void```+## takeCensus — function+```+(ctx?: CensusContext): Census+```+## textInputPlugin — const```TextInputPlugindiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 568a843c6..b3077bbd0 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1464 stable · 22 beta · 1 deprecated+Symbols: 1481 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -627,6 +627,7 @@ getMaterialRefs: (path: string) => number[]getTextureRefCount: (path: string) => numbergetTextureRefs: (path: string) => number[]getTotalRefCount: () => { textures: number; fonts: number; materials: number; }+getTotalRefRows: () => numberremoveAllRefsForEntity: (entity: number) => voidremoveFontRef: (path: string, entity: number) => voidremoveMaterialRef: (path: string, entity: number) => void@@ -673,6 +674,7 @@ get: (key: string) => T | undefinedgetOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>has: (key: string) => booleaninvalidate: (key: string) => boolean+sizes: () => { cached: number; pending: number; failed: number; }values: () => IterableIterator<T>static new <T>(dispose_?: ((value: T) => void) | undefined): AsyncCache<T>static prototype: AsyncCache<any>@@ -1505,6 +1507,82 @@ x: numbery: number```+## Census — interface+```+atMs: number+entries: ReadonlyMap<string, CensusEntry>+failedProbes: readonly string[]+```++## CensusContext — interface+```+app: App | undefined+module: ESEngineModule | null | undefined+world: World | undefined+```++## CensusDelta — interface+```+after: number+before: number+delta: number+key: string+tier: CensusTier+unit: "count" | "bytes"+```++## CensusEntry — interface+```+key: string+tier: CensusTier+unit: "count" | "bytes"+value: number+```++## CensusProbe — interface+```+id: string+read: (ctx: CensusContext) => readonly CensusEntry[] | undefined+```++## CensusReport — interface+```+cycles: number+failedProbes: readonly string[]+judgedFrom: number+leaks: readonly CensusVerdict[]+projectCycles: number+verdicts: readonly CensusVerdict[]+```++## CensusSeriesOptions — interface+```+boundedSlopeTolerance: number | undefined+projectCycles: number | undefined+trendByteBudgetPerCycle: number | undefined+warmupCycles: number | undefined+```++## CensusTier — type+```+'conserved' | 'bounded' | 'trend' | 'info'+```++## CensusVerdict — interface+```+confidentSlopePerCycle: number+first: number+key: string+last: number+leaking: boolean+projected: number+reason: string | undefined+risingFraction: number+slopePerCycle: number+tier: CensusTier+unit: "count" | "bytes"+```+## ChainCollider — const```ComponentDef<ChainColliderData>@@ -2481,6 +2559,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+es_getMallocBytes: (() => number) | undefinedesshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }geometry_create: () => numbergeometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void@@ -2574,6 +2653,7 @@ renderer_getCapturedFrameSize: () => numberrenderer_getCulled: () => numberrenderer_getDrawCalls: () => numberrenderer_getGpuTimeMs: (() => number) | undefined+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => numberrenderer_getPreviewHeight: () => numberrenderer_getPreviewPtr: () => number@@ -5063,6 +5143,7 @@ _physics_enableWheelJointMotor: (entityId: number, enable: number) => void_physics_enableWheelJointSpring: (entityId: number, enable: number) => void_physics_getAngularVelocity: (entityId: number) => number_physics_getBodyCenterOfMass: (entityId: number) => number+_physics_getBodyCount: () => number_physics_getBodyInertia: (entityId: number) => number_physics_getBodyMass: (entityId: number) => number_physics_getCollisionEnterBuffer: () => number@@ -5079,6 +5160,7 @@ _physics_getHitEventBuffer: () => number_physics_getHitEventCount: () => number_physics_getInterpolatedCount: () => number_physics_getInterpolatedTransforms: (alpha: number) => number+_physics_getJointCount: () => number_physics_getLinearVelocity: (entityId: number) => number_physics_getMoveCharacterBuffer: () => number_physics_getOverlapBuffer: () => number@@ -5093,6 +5175,8 @@ _physics_getSensorEnterCount: () => number_physics_getSensorExitBuffer: () => number_physics_getSensorExitCount: () => number_physics_getShapeCastBuffer: () => number+_physics_getShapeCount: () => number+_physics_getTrackingRows: () => number_physics_getWheelJointMotorTorque: (entityId: number) => number_physics_hasBody: (entityId: number) => number_physics_hasJoint: (entityId: number) => number@@ -8673,6 +8757,7 @@ getCppRegistry: () => CppRegistry | nullgetEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]getQueryCacheStats: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]+getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }getWasmModule: () => ESEngineModule | nullgetWorldTick: () => numbergetWorldVersion: () => number@@ -8817,6 +8902,11 @@ TransformDataAiRegistry<AiContext>```+## analyzeCensusSeries — function+```+(samples: readonly Census[], opts?: CensusSeriesOptions): CensusReport+```+## anchorPresetFields — function```(preset: AnchorPreset): AnchorFields@@ -9047,6 +9137,11 @@ BtPlugin(manifest: AddressableManifest): Catalog | undefined```+## censusProbeIds — function+```+(): string[]+```+## clearAllCaches — function```(): void@@ -9132,6 +9227,11 @@ BtPlugin(entities: readonly ExtractEntity[]): ExternalEntityRef[]```+## collectGarbage — function+```+(): boolean+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]@@ -9447,6 +9547,11 @@ DiagnosticsPlugin(source: PrefabData, instance: readonly ProcessedEntity[], options?: DiffOptions): { overrides: PrefabOverride[]; untracked: ProcessedEntity[]; orphanedSourceIds: PrefabEntityId[]; }```+## diffCensus — function+```+(before: Census, after: Census): CensusDelta[]+```+## disconnect — function @beta```(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph@@ -9647,6 +9752,16 @@ FocusPlugin(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined```+## formatCensusDiff — function+```+(before: Census, after: Census, all?: boolean): string+```++## formatCensusReport — function+```+(report: CensusReport): string+```+## fsmEdges — function```(def: FsmDefinition): FsmEdge[]@@ -10522,6 +10637,11 @@ PrefabsPlugin(key: string, def: BtDefinition): BtDefinition```+## registerCensusProbe — function+```+(probe: CensusProbe): () => void+```+## registerComponent — function```(name: string, def: AnyComponentDef): void@@ -11037,6 +11157,11 @@ StatsPlugin(world: World, tokens: ThemeTokens): void```+## takeCensus — function+```+(ctx?: CensusContext): Census+```+## textInputPlugin — const```TextInputPlugindiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d0dbcef5f..6e3c42969 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1444 stable · 19 beta · 1 deprecated+Symbols: 1461 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -622,6 +622,7 @@ getMaterialRefs: (path: string) => number[]getTextureRefCount: (path: string) => numbergetTextureRefs: (path: string) => number[]getTotalRefCount: () => { textures: number; fonts: number; materials: number; }+getTotalRefRows: () => numberremoveAllRefsForEntity: (entity: number) => voidremoveFontRef: (path: string, entity: number) => voidremoveMaterialRef: (path: string, entity: number) => void@@ -668,6 +669,7 @@ get: (key: string) => T | undefinedgetOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>has: (key: string) => booleaninvalidate: (key: string) => boolean+sizes: () => { cached: number; pending: number; failed: number; }values: () => IterableIterator<T>static new <T>(dispose_?: ((value: T) => void) | undefined): AsyncCache<T>static prototype: AsyncCache<any>@@ -1500,6 +1502,82 @@ x: numbery: number```+## Census — interface+```+atMs: number+entries: ReadonlyMap<string, CensusEntry>+failedProbes: readonly string[]+```++## CensusContext — interface+```+app: App | undefined+module: ESEngineModule | null | undefined+world: World | undefined+```++## CensusDelta — interface+```+after: number+before: number+delta: number+key: string+tier: CensusTier+unit: "count" | "bytes"+```++## CensusEntry — interface+```+key: string+tier: CensusTier+unit: "count" | "bytes"+value: number+```++## CensusProbe — interface+```+id: string+read: (ctx: CensusContext) => readonly CensusEntry[] | undefined+```++## CensusReport — interface+```+cycles: number+failedProbes: readonly string[]+judgedFrom: number+leaks: readonly CensusVerdict[]+projectCycles: number+verdicts: readonly CensusVerdict[]+```++## CensusSeriesOptions — interface+```+boundedSlopeTolerance: number | undefined+projectCycles: number | undefined+trendByteBudgetPerCycle: number | undefined+warmupCycles: number | undefined+```++## CensusTier — type+```+'conserved' | 'bounded' | 'trend' | 'info'+```++## CensusVerdict — interface+```+confidentSlopePerCycle: number+first: number+key: string+last: number+leaking: boolean+projected: number+reason: string | undefined+risingFraction: number+slopePerCycle: number+tier: CensusTier+unit: "count" | "bytes"+```+## ChainCollider — const```ComponentDef<ChainColliderData>@@ -2468,6 +2546,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+es_getMallocBytes: (() => number) | undefinedesshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }geometry_create: () => numbergeometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void@@ -2561,6 +2640,7 @@ renderer_getCapturedFrameSize: () => numberrenderer_getCulled: () => numberrenderer_getDrawCalls: () => numberrenderer_getGpuTimeMs: (() => number) | undefined+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => numberrenderer_getPreviewHeight: () => numberrenderer_getPreviewPtr: () => number@@ -4898,6 +4978,7 @@ _physics_enableWheelJointMotor: (entityId: number, enable: number) => void_physics_enableWheelJointSpring: (entityId: number, enable: number) => void_physics_getAngularVelocity: (entityId: number) => number_physics_getBodyCenterOfMass: (entityId: number) => number+_physics_getBodyCount: () => number_physics_getBodyInertia: (entityId: number) => number_physics_getBodyMass: (entityId: number) => number_physics_getCollisionEnterBuffer: () => number@@ -4914,6 +4995,7 @@ _physics_getHitEventBuffer: () => number_physics_getHitEventCount: () => number_physics_getInterpolatedCount: () => number_physics_getInterpolatedTransforms: (alpha: number) => number+_physics_getJointCount: () => number_physics_getLinearVelocity: (entityId: number) => number_physics_getMoveCharacterBuffer: () => number_physics_getOverlapBuffer: () => number@@ -4928,6 +5010,8 @@ _physics_getSensorEnterCount: () => number_physics_getSensorExitBuffer: () => number_physics_getSensorExitCount: () => number_physics_getShapeCastBuffer: () => number+_physics_getShapeCount: () => number+_physics_getTrackingRows: () => number_physics_getWheelJointMotorTorque: (entityId: number) => number_physics_hasBody: (entityId: number) => number_physics_hasJoint: (entityId: number) => number@@ -8498,6 +8582,7 @@ getCppRegistry: () => CppRegistry | nullgetEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]getQueryCacheStats: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]+getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }getWasmModule: () => ESEngineModule | nullgetWorldTick: () => numbergetWorldVersion: () => number@@ -8642,6 +8727,11 @@ TransformDataAiRegistry<AiContext>```+## analyzeCensusSeries — function+```+(samples: readonly Census[], opts?: CensusSeriesOptions): CensusReport+```+## anchorPresetFields — function```(preset: AnchorPreset): AnchorFields@@ -8857,6 +8947,11 @@ BtPlugin(manifest: AddressableManifest): Catalog | undefined```+## censusProbeIds — function+```+(): string[]+```+## clearAllCaches — function```(): void@@ -8942,6 +9037,11 @@ BtPlugin(entities: readonly ExtractEntity[]): ExternalEntityRef[]```+## collectGarbage — function+```+(): boolean+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]@@ -9232,6 +9332,11 @@ DiagnosticsPlugin(source: PrefabData, instance: readonly ProcessedEntity[], options?: DiffOptions): { overrides: PrefabOverride[]; untracked: ProcessedEntity[]; orphanedSourceIds: PrefabEntityId[]; }```+## diffCensus — function+```+(before: Census, after: Census): CensusDelta[]+```+## disconnect — function @beta```(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph@@ -9432,6 +9537,16 @@ FocusPlugin(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined```+## formatCensusDiff — function+```+(before: Census, after: Census, all?: boolean): string+```++## formatCensusReport — function+```+(report: CensusReport): string+```+## fsmEdges — function```(def: FsmDefinition): FsmEdge[]@@ -10307,6 +10422,11 @@ PrefabsPlugin(key: string, def: BtDefinition): BtDefinition```+## registerCensusProbe — function+```+(probe: CensusProbe): () => void+```+## registerComponent — function```(name: string, def: AnyComponentDef): void@@ -10822,6 +10942,11 @@ StatsPlugin(world: World, tokens: ThemeTokens): void```+## takeCensus — function+```+(ctx?: CensusContext): Census+```+## textInputPlugin — const```TextInputPlugindiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex a4576d531..3066c93f7 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1465 stable · 17 beta · 1 deprecated+Symbols: 1482 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -622,6 +622,7 @@ getMaterialRefs: (path: string) => number[]getTextureRefCount: (path: string) => numbergetTextureRefs: (path: string) => number[]getTotalRefCount: () => { textures: number; fonts: number; materials: number; }+getTotalRefRows: () => numberremoveAllRefsForEntity: (entity: number) => voidremoveFontRef: (path: string, entity: number) => voidremoveMaterialRef: (path: string, entity: number) => void@@ -668,6 +669,7 @@ get: (key: string) => T | undefinedgetOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>has: (key: string) => booleaninvalidate: (key: string) => boolean+sizes: () => { cached: number; pending: number; failed: number; }values: () => IterableIterator<T>static new <T>(dispose_?: ((value: T) => void) | undefined): AsyncCache<T>static prototype: AsyncCache<any>@@ -1500,6 +1502,82 @@ x: numbery: number```+## Census — interface+```+atMs: number+entries: ReadonlyMap<string, CensusEntry>+failedProbes: readonly string[]+```++## CensusContext — interface+```+app: App | undefined+module: ESEngineModule | null | undefined+world: World | undefined+```++## CensusDelta — interface+```+after: number+before: number+delta: number+key: string+tier: CensusTier+unit: "count" | "bytes"+```++## CensusEntry — interface+```+key: string+tier: CensusTier+unit: "count" | "bytes"+value: number+```++## CensusProbe — interface+```+id: string+read: (ctx: CensusContext) => readonly CensusEntry[] | undefined+```++## CensusReport — interface+```+cycles: number+failedProbes: readonly string[]+judgedFrom: number+leaks: readonly CensusVerdict[]+projectCycles: number+verdicts: readonly CensusVerdict[]+```++## CensusSeriesOptions — interface+```+boundedSlopeTolerance: number | undefined+projectCycles: number | undefined+trendByteBudgetPerCycle: number | undefined+warmupCycles: number | undefined+```++## CensusTier — type+```+'conserved' | 'bounded' | 'trend' | 'info'+```++## CensusVerdict — interface+```+confidentSlopePerCycle: number+first: number+key: string+last: number+leaking: boolean+projected: number+reason: string | undefined+risingFraction: number+slopePerCycle: number+tier: CensusTier+unit: "count" | "bytes"+```+## ChainCollider — const```ComponentDef<ChainColliderData>@@ -2468,6 +2546,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+es_getMallocBytes: (() => number) | undefinedesshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }geometry_create: () => numbergeometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void@@ -2561,6 +2640,7 @@ renderer_getCapturedFrameSize: () => numberrenderer_getCulled: () => numberrenderer_getDrawCalls: () => numberrenderer_getGpuTimeMs: (() => number) | undefined+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => numberrenderer_getPreviewHeight: () => numberrenderer_getPreviewPtr: () => number@@ -5143,6 +5223,7 @@ _physics_enableWheelJointMotor: (entityId: number, enable: number) => void_physics_enableWheelJointSpring: (entityId: number, enable: number) => void_physics_getAngularVelocity: (entityId: number) => number_physics_getBodyCenterOfMass: (entityId: number) => number+_physics_getBodyCount: () => number_physics_getBodyInertia: (entityId: number) => number_physics_getBodyMass: (entityId: number) => number_physics_getCollisionEnterBuffer: () => number@@ -5159,6 +5240,7 @@ _physics_getHitEventBuffer: () => number_physics_getHitEventCount: () => number_physics_getInterpolatedCount: () => number_physics_getInterpolatedTransforms: (alpha: number) => number+_physics_getJointCount: () => number_physics_getLinearVelocity: (entityId: number) => number_physics_getMoveCharacterBuffer: () => number_physics_getOverlapBuffer: () => number@@ -5173,6 +5255,8 @@ _physics_getSensorEnterCount: () => number_physics_getSensorExitBuffer: () => number_physics_getSensorExitCount: () => number_physics_getShapeCastBuffer: () => number+_physics_getShapeCount: () => number+_physics_getTrackingRows: () => number_physics_getWheelJointMotorTorque: (entityId: number) => number_physics_hasBody: (entityId: number) => number_physics_hasJoint: (entityId: number) => number@@ -8743,6 +8827,7 @@ getCppRegistry: () => CppRegistry | nullgetEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]getQueryCacheStats: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]+getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }getWasmModule: () => ESEngineModule | nullgetWorldTick: () => numbergetWorldVersion: () => number@@ -8887,6 +8972,11 @@ TransformDataAiRegistry<AiContext>```+## analyzeCensusSeries — function+```+(samples: readonly Census[], opts?: CensusSeriesOptions): CensusReport+```+## anchorPresetFields — function```(preset: AnchorPreset): AnchorFields@@ -9102,6 +9192,11 @@ BtPlugin(manifest: AddressableManifest): Catalog | undefined```+## censusProbeIds — function+```+(): string[]+```+## clearAllCaches — function```(): void@@ -9187,6 +9282,11 @@ BtPlugin(entities: readonly ExtractEntity[]): ExternalEntityRef[]```+## collectGarbage — function+```+(): boolean+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]@@ -9482,6 +9582,11 @@ DiagnosticsPlugin(source: PrefabData, instance: readonly ProcessedEntity[], options?: DiffOptions): { overrides: PrefabOverride[]; untracked: ProcessedEntity[]; orphanedSourceIds: PrefabEntityId[]; }```+## diffCensus — function+```+(before: Census, after: Census): CensusDelta[]+```+## disconnect — function @beta```(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph@@ -9682,6 +9787,16 @@ FocusPlugin(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined```+## formatCensusDiff — function+```+(before: Census, after: Census, all?: boolean): string+```++## formatCensusReport — function+```+(report: CensusReport): string+```+## fsmEdges — function```(def: FsmDefinition): FsmEdge[]@@ -10557,6 +10672,11 @@ PrefabsPlugin(key: string, def: BtDefinition): BtDefinition```+## registerCensusProbe — function+```+(probe: CensusProbe): () => void+```+## registerComponent — function```(name: string, def: AnyComponentDef): void@@ -11072,6 +11192,11 @@ StatsPlugin(world: World, tokens: ThemeTokens): void```+## takeCensus — function+```+(ctx?: CensusContext): Census+```+## textInputPlugin — const```TextInputPlugindiff --git a/sdk/etc/physics.api.md b/sdk/etc/physics.api.mdindex a8bfddba3..e26e24d1e 100644--- a/sdk/etc/physics.api.md+++ b/sdk/etc/physics.api.md@@ -441,6 +441,7 @@ _physics_enableWheelJointMotor: (entityId: number, enable: number) => void_physics_enableWheelJointSpring: (entityId: number, enable: number) => void_physics_getAngularVelocity: (entityId: number) => number_physics_getBodyCenterOfMass: (entityId: number) => number+_physics_getBodyCount: () => number_physics_getBodyInertia: (entityId: number) => number_physics_getBodyMass: (entityId: number) => number_physics_getCollisionEnterBuffer: () => number@@ -457,6 +458,7 @@ _physics_getHitEventBuffer: () => number_physics_getHitEventCount: () => number_physics_getInterpolatedCount: () => number_physics_getInterpolatedTransforms: (alpha: number) => number+_physics_getJointCount: () => number_physics_getLinearVelocity: (entityId: number) => number_physics_getMoveCharacterBuffer: () => number_physics_getOverlapBuffer: () => number@@ -471,6 +473,8 @@ _physics_getSensorEnterCount: () => number_physics_getSensorExitBuffer: () => number_physics_getSensorExitCount: () => number_physics_getShapeCastBuffer: () => number+_physics_getShapeCount: () => number+_physics_getTrackingRows: () => number_physics_getWheelJointMotorTorque: (entityId: number) => number_physics_hasBody: (entityId: number) => number_physics_hasJoint: (entityId: number) => numberdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 9ac9f7b27..87c960580 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -1,7 +1,7 @@# API surface — esengine/wasm<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 5 stable · 0 beta · 0 deprecated+Symbols: 6 stable · 0 beta · 0 deprecated## CppEngineContext — interface```@@ -214,6 +214,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+es_getMallocBytes: (() => number) | undefinedesshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }geometry_create: () => numbergeometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void@@ -307,6 +308,7 @@ renderer_getCapturedFrameSize: () => numberrenderer_getCulled: () => numberrenderer_getDrawCalls: () => numberrenderer_getGpuTimeMs: (() => number) | undefined+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => numberrenderer_getPreviewHeight: () => numberrenderer_getPreviewPtr: () => number@@ -398,3 +400,14 @@ unlink: (path: string) => voidwriteFile: (path: string, data: string | Uint8Array) => void```+## GfxLiveObjects — interface+```+buffers: number+layouts: number+pipelines: number+programs: number+readbacks: number+renderTargets: number+textures: number+```+diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex ff7f991aa..7024457bd 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1455 stable · 17 beta · 1 deprecated+Symbols: 1472 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -622,6 +622,7 @@ getMaterialRefs: (path: string) => number[]getTextureRefCount: (path: string) => numbergetTextureRefs: (path: string) => number[]getTotalRefCount: () => { textures: number; fonts: number; materials: number; }+getTotalRefRows: () => numberremoveAllRefsForEntity: (entity: number) => voidremoveFontRef: (path: string, entity: number) => voidremoveMaterialRef: (path: string, entity: number) => void@@ -668,6 +669,7 @@ get: (key: string) => T | undefinedgetOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>has: (key: string) => booleaninvalidate: (key: string) => boolean+sizes: () => { cached: number; pending: number; failed: number; }values: () => IterableIterator<T>static new <T>(dispose_?: ((value: T) => void) | undefined): AsyncCache<T>static prototype: AsyncCache<any>@@ -1500,6 +1502,82 @@ x: numbery: number```+## Census — interface+```+atMs: number+entries: ReadonlyMap<string, CensusEntry>+failedProbes: readonly string[]+```++## CensusContext — interface+```+app: App | undefined+module: ESEngineModule | null | undefined+world: World | undefined+```++## CensusDelta — interface+```+after: number+before: number+delta: number+key: string+tier: CensusTier+unit: "count" | "bytes"+```++## CensusEntry — interface+```+key: string+tier: CensusTier+unit: "count" | "bytes"+value: number+```++## CensusProbe — interface+```+id: string+read: (ctx: CensusContext) => readonly CensusEntry[] | undefined+```++## CensusReport — interface+```+cycles: number+failedProbes: readonly string[]+judgedFrom: number+leaks: readonly CensusVerdict[]+projectCycles: number+verdicts: readonly CensusVerdict[]+```++## CensusSeriesOptions — interface+```+boundedSlopeTolerance: number | undefined+projectCycles: number | undefined+trendByteBudgetPerCycle: number | undefined+warmupCycles: number | undefined+```++## CensusTier — type+```+'conserved' | 'bounded' | 'trend' | 'info'+```++## CensusVerdict — interface+```+confidentSlopePerCycle: number+first: number+key: string+last: number+leaking: boolean+projected: number+reason: string | undefined+risingFraction: number+slopePerCycle: number+tier: CensusTier+unit: "count" | "bytes"+```+## ChainCollider — const```ComponentDef<ChainColliderData>@@ -2468,6 +2546,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+es_getMallocBytes: (() => number) | undefinedesshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }geometry_create: () => numbergeometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void@@ -2561,6 +2640,7 @@ renderer_getCapturedFrameSize: () => numberrenderer_getCulled: () => numberrenderer_getDrawCalls: () => numberrenderer_getGpuTimeMs: (() => number) | undefined+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => numberrenderer_getPreviewHeight: () => numberrenderer_getPreviewPtr: () => number@@ -4905,6 +4985,7 @@ _physics_enableWheelJointMotor: (entityId: number, enable: number) => void_physics_enableWheelJointSpring: (entityId: number, enable: number) => void_physics_getAngularVelocity: (entityId: number) => number_physics_getBodyCenterOfMass: (entityId: number) => number+_physics_getBodyCount: () => number_physics_getBodyInertia: (entityId: number) => number_physics_getBodyMass: (entityId: number) => number_physics_getCollisionEnterBuffer: () => number@@ -4921,6 +5002,7 @@ _physics_getHitEventBuffer: () => number_physics_getHitEventCount: () => number_physics_getInterpolatedCount: () => number_physics_getInterpolatedTransforms: (alpha: number) => number+_physics_getJointCount: () => number_physics_getLinearVelocity: (entityId: number) => number_physics_getMoveCharacterBuffer: () => number_physics_getOverlapBuffer: () => number@@ -4935,6 +5017,8 @@ _physics_getSensorEnterCount: () => number_physics_getSensorExitBuffer: () => number_physics_getSensorExitCount: () => number_physics_getShapeCastBuffer: () => number+_physics_getShapeCount: () => number+_physics_getTrackingRows: () => number_physics_getWheelJointMotorTorque: (entityId: number) => number_physics_hasBody: (entityId: number) => number_physics_hasJoint: (entityId: number) => number@@ -8525,6 +8609,7 @@ getCppRegistry: () => CppRegistry | nullgetEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]getQueryCacheStats: () => QueryCacheStatsgetRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]+getStorageSizes: () => { entities: number; indexSlots: number; spawnCallbacks: number; despawnCallbacks: number; names: ReturnType<NameIndex["sizes"]>; scripts: ReturnType<ScriptStorage["sizes"]>; changes: ReturnType<ChangeTracker["sizes"]>; queryCacheEntries: number; }getWasmModule: () => ESEngineModule | nullgetWorldTick: () => numbergetWorldVersion: () => number@@ -8669,6 +8754,11 @@ TransformDataAiRegistry<AiContext>```+## analyzeCensusSeries — function+```+(samples: readonly Census[], opts?: CensusSeriesOptions): CensusReport+```+## anchorPresetFields — function```(preset: AnchorPreset): AnchorFields@@ -8884,6 +8974,11 @@ BtPlugin(manifest: AddressableManifest): Catalog | undefined```+## censusProbeIds — function+```+(): string[]+```+## clearAllCaches — function```(): void@@ -8969,6 +9064,11 @@ BtPlugin(entities: readonly ExtractEntity[]): ExternalEntityRef[]```+## collectGarbage — function+```+(): boolean+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]@@ -9259,6 +9359,11 @@ DiagnosticsPlugin(source: PrefabData, instance: readonly ProcessedEntity[], options?: DiffOptions): { overrides: PrefabOverride[]; untracked: ProcessedEntity[]; orphanedSourceIds: PrefabEntityId[]; }```+## diffCensus — function+```+(before: Census, after: Census): CensusDelta[]+```+## disconnect — function @beta```(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph@@ -9459,6 +9564,16 @@ FocusPlugin(params: Readonly<Record<string, AiParamValue>> | undefined, defs: readonly AiParamDef[], separator?: string): string | undefined```+## formatCensusDiff — function+```+(before: Census, after: Census, all?: boolean): string+```++## formatCensusReport — function+```+(report: CensusReport): string+```+## fsmEdges — function```(def: FsmDefinition): FsmEdge[]@@ -10329,6 +10444,11 @@ PrefabsPlugin(key: string, def: BtDefinition): BtDefinition```+## registerCensusProbe — function+```+(probe: CensusProbe): () => void+```+## registerComponent — function```(name: string, def: AnyComponentDef): void@@ -10844,6 +10964,11 @@ StatsPlugin(world: World, tokens: ThemeTokens): void```+## takeCensus — function+```+(ctx?: CensusContext): Census+```+## textInputPlugin — const```TextInputPlugindiff --git a/sdk/src/asset/AssetRefCounter.ts b/sdk/src/asset/AssetRefCounter.tsindex e7d908083..c5d404fb9 100644--- a/sdk/src/asset/AssetRefCounter.ts+++ b/sdk/src/asset/AssetRefCounter.ts@@ -56,6 +56,12 @@ class RefMap {get size(): number { return this.refs_.size; }+ get rows(): number {+ let n = 0;+ for (const refs of this.refs_.values()) n += refs.size;+ return n;+ }+clear(): void { this.refs_.clear(); }}@@ -101,4 +107,15 @@ export class AssetRefCounter {materials: this.materials_.size,};}++ /**+ * Total (asset, entity) pairs held, across every kind — the number a+ * spawn/despawn round trip must conserve.+ *+ * {@link getTotalRefCount} counts distinct PATHS, which understates a leak:+ * ten thousand entities that never released one texture read as a single ref.+ */+ getTotalRefRows(): number {+ return this.textures_.rows + this.fonts_.rows + this.materials_.rows;+ }}diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 7ef6f8d04..ad46514fb 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -1332,6 +1332,45 @@ export class Assets {};}+ /**+ * @internal Live entry counts for the resource census.+ *+ * Cache sizes are not expected to return to baseline — that is what a cache+ * is for. `refCounts` and `handlePaths` are: every load handing one out has a+ * release taking it back. `pendingLoads` should be zero at rest.+ */+ sizes(): {+ textureCached: number;+ pendingLoads: number;+ refCounts: number;+ genericCaches: number;+ genericCached: number;+ handlePaths: number;+ invalidateListeners: number;+ registryEntries: number;+ trackedRefRows: number;+ } {+ const tex = this.textureCache_.sizes();+ let genericCached = 0;+ let pending = tex.pending;+ for (const cache of this.genericCache_.values()) {+ const s = cache.sizes();+ genericCached += s.cached;+ pending += s.pending;+ }+ return {+ textureCached: tex.cached,+ pendingLoads: pending,+ refCounts: this.textureRefCounts_.size + this.genericRefCounts_.size,+ genericCaches: this.genericCache_.size,+ genericCached,+ handlePaths: this.handleToPath_.size,+ invalidateListeners: this.invalidateListeners_.size,+ registryEntries: this.assetRegistry_?.size ?? 0,+ trackedRefRows: this.refCounter_?.getTotalRefRows() ?? 0,+ };+ }+releaseAll(): void {const rm = requireResourceManager();for (const info of this.textureCache_.values()) {diff --git a/sdk/src/asset/AsyncCache.ts b/sdk/src/asset/AsyncCache.tsindex 56bc3b030..e35f00bee 100644--- a/sdk/src/asset/AsyncCache.ts+++ b/sdk/src/asset/AsyncCache.ts@@ -175,4 +175,15 @@ export class AsyncCache<T> {values(): IterableIterator<T> {return this.cache_.values();}++ /**+ * @internal Entry counts for the resource census.+ *+ * `pending` is the one to watch: it should be empty at rest, so a non-zero+ * value between cycles means a load never settled — and a load that never+ * settles holds its callbacks, its buffers and whatever closed over them.+ */+ sizes(): { cached: number; pending: number; failed: number } {+ return { cached: this.cache_.size, pending: this.pending_.size, failed: this.failed_.size };+ }}diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 1b9438aaa..c4bed5b94 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -156,6 +156,18 @@ export {type DiagnosticsOptions, type DiagnosticsPluginOptions, type DiagnosticsSink,} from './diagnostics';+// =============================================================================+// Resource census — how many of X are alive right now+// =============================================================================++/** @beta Pre-1.0: the counter set is expected to grow as probes are added. */+export {+ takeCensus, registerCensusProbe, censusProbeIds, collectGarbage,+ diffCensus, analyzeCensusSeries, formatCensusDiff, formatCensusReport,+ type Census, type CensusEntry, type CensusTier, type CensusContext, type CensusProbe,+ type CensusDelta, type CensusSeriesOptions, type CensusVerdict, type CensusReport,+} from './diagnostics';+// =============================================================================// GL Debug// =============================================================================diff --git a/sdk/src/diagnostics/census.ts b/sdk/src/diagnostics/census.tsnew file mode 100644index 000000000..05928b51c--- /dev/null+++ b/sdk/src/diagnostics/census.ts@@ -0,0 +1,417 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file census.ts+ * @brief How many of X are alive right now — one snapshot, for every X the+ * engine is capable of leaking.+ *+ * @details The engine could not answer that question. Entity count it had;+ * everything else a long session accumulates — GL objects, listeners,+ * physics bodies, cache entries, both heaps — was reachable only by+ * reading a private field of whichever class happened to own it, if at+ * all. So the failure that actually ends an editor session ("Play/Stop+ * forty times and it starts to crawl") had no instrument pointed at it,+ * and every leak we ever fixed was found by someone noticing.+ *+ * This is that instrument. Subsystems register probes; a census reads+ * them all into one flat set of named counters that a churn test can+ * take before and after, and a human can read.+ *+ * THE TIER IS THE DESIGN. The obvious assertion — every counter returns+ * to its baseline — is wrong often enough to be useless, and a soak test+ * that cries wolf gets deleted within the month. A texture cache holding+ * refCount==0 entries for revival is doing its job; a transient buffer+ * pool that grew to its high-water mark and stayed there is doing its+ * job; a JS heap is not under anyone's control at all. Only some+ * counters obey a conservation law, so only those are asserted as one:+ *+ * conserved — spawn/destroy is a round trip. Must be IDENTICAL across+ * cycles. Entities, bodies, listeners, live GL objects.+ * bounded — may plateau above baseline, must not grow per cycle.+ * Pools and caches. Judged on slope, never on value.+ * trend — noisy and allocator-dependent. Heaps. Judged on slope+ * against a stated per-cycle budget.+ * info — recorded to explain a failure, never asserted.+ *+ * Slope rather than value is also what makes the test cheap: a leak is a+ * positive slope from cycle one, so fifty cycles prove what ten thousand+ * would, and the projection in the report says what those ten thousand+ * would have cost.+ */+import type { Census, CensusEntry, CensusTier, CensusContext, CensusProbe } from './censusTypes';+import { readProbes, registeredProbeIds } from './censusRegistry';+import { installBuiltinCensusProbes } from './censusProbes';++export type { Census, CensusEntry, CensusTier, CensusContext, CensusProbe };++let installed = false;++/**+ * Install the engine's probes, once, from inside the exported entry points.+ *+ * Anywhere else and the bundler removes them: non-entry modules are marked+ * side-effect free, so a bare import or top-level call registers nothing in+ * dist. That shipped once — see docs/REARCH_RELIABILITY_SOAK.md.+ */+function ensureBuiltins(): void {+ if (installed) return;+ installed = true;+ installBuiltinCensusProbes();+}++export { registerCensusProbe, counter } from './censusRegistry';++/** Registered probe ids, for diagnosing a census that came back thinner than expected. */+export function censusProbeIds(): string[] {+ ensureBuiltins();+ return registeredProbeIds();+}++/** Read every registered probe into one snapshot. */+export function takeCensus(ctx: CensusContext = {}): Census {+ ensureBuiltins();+ return readProbes(ctx);+}++/**+ * Settle the JS heap before a census, if the host allows it. True when a+ * collection ran; without one the heap only climbs between samples, so the heap+ * counters downgrade themselves to `info`. Node needs `--expose-gc`.+ */+export function collectGarbage(): boolean {+ const gc = (globalThis as { gc?: () => void }).gc;+ if (typeof gc !== 'function') return false;+ gc();+ return true;+}++// =============================================================================+// Diff — two snapshots+// =============================================================================++export interface CensusDelta {+ readonly key: string;+ readonly tier: CensusTier;+ readonly unit: CensusEntry['unit'];+ readonly before: number;+ readonly after: number;+ readonly delta: number;+}++/**+ * What moved between two snapshots. A counter present on only one side is+ * reported with the missing half as 0: a probe that appeared or vanished+ * mid-run is a real difference, not a reason to skip the row.+ */+export function diffCensus(before: Census, after: Census): CensusDelta[] {+ const keys = new Set([...before.entries.keys(), ...after.entries.keys()]);+ const out: CensusDelta[] = [];+ for (const key of [...keys].sort()) {+ const a = before.entries.get(key);+ const b = after.entries.get(key);+ const spec = b ?? a!;+ const from = a?.value ?? 0;+ const to = b?.value ?? 0;+ out.push({ key, tier: spec.tier, unit: spec.unit, before: from, after: to, delta: to - from });+ }+ return out;+}++// =============================================================================+// Series analysis — the judge+// =============================================================================++export interface CensusSeriesOptions {+ /**+ * Cycles to discard before judging. A first pass legitimately allocates for+ * good — lazy component registration, a shader compiled on first use, a pool+ * reaching working size — and judging that would fail every run.+ * Defaults to the larger of 3 and a fifth of the samples.+ */+ warmupCycles?: number;+ /**+ * Cycle count the projection reports against — "at this rate, N cycles costs+ * this much". Does not affect the verdict.+ */+ projectCycles?: number;+ /** Per-cycle growth a `bounded` counter may show before it reads as a leak. */+ boundedSlopeTolerance?: number;+ /**+ * Per-cycle byte growth a `trend` counter (a heap) may show.+ *+ * The default is a DETECTION FLOOR, not a taste — below ~16 KB the number+ * is V8 sizing its heap, not the engine keeping anything (measurements in+ * docs/REARCH_RELIABILITY_SOAK.md). Exact counters do the fine-grained job.+ */+ trendByteBudgetPerCycle?: number;+}++export interface CensusVerdict {+ readonly key: string;+ readonly tier: CensusTier;+ readonly unit: CensusEntry['unit'];+ readonly leaking: boolean;+ /** Least-squares growth per cycle over the judged samples. */+ readonly slopePerCycle: number;+ /**+ * The growth the samples actually support — the slope pulled back by twice+ * its standard error. This, not the point estimate, is what is judged.+ */+ readonly confidentSlopePerCycle: number;+ /**+ * Share of cycles on which the counter rose. Near 1 is a leak; near 0 with a+ * positive slope is a pool that stepped once and the fit read as a ramp.+ */+ readonly risingFraction: number;+ readonly first: number;+ readonly last: number;+ /** confidentSlopePerCycle × projectCycles — what this costs over a session. */+ readonly projected: number;+ /** Populated when `leaking`; the sentence a failure should print. */+ readonly reason?: string;+}++export interface CensusReport {+ readonly cycles: number;+ readonly judgedFrom: number;+ readonly projectCycles: number;+ readonly verdicts: readonly CensusVerdict[];+ readonly leaks: readonly CensusVerdict[];+ readonly failedProbes: readonly string[];+}++const DEFAULT_PROJECT_CYCLES = 10_000;++/**+ * Judged samples a fitted verdict needs. Below this the standard error is not+ * estimable and the slope comes back with full confidence attached to almost+ * nothing — a five-cycle run would report a leak from two points. Conserved+ * counters are exempt: they are integers under a contract, not a fit.+ */+const MIN_FITTED_SAMPLES = 8;++/**+ * Cycle-to-cycle rises a fitted counter needs before it reads as a leak.+ *+ * A LINE FITS A STAIRCASE: one 4 KB page allocated mid-run clears the confidence+ * gate as +120 B/cycle. A leak rises again and again; a pool rises once. Cost: a+ * counter stepping rarer than one cycle in four needs a longer run.+ */+const MIN_RISING_FRACTION = 0.25;++/** Fraction of cycle-to-cycle transitions on which `ys` increased. */+function risingFraction(ys: readonly number[]): number {+ if (ys.length < 2) return 0;+ let rising = 0;+ for (let i = 1; i < ys.length; i++) if (ys[i] > ys[i - 1]) rising++;+ return rising / (ys.length - 1);+}++/**+ * Confidence multiplier on the slope's standard error — roughly one-sided 95%.+ *+ * The point estimate alone is not evidence: judging a raw fitted slope makes the+ * verdict depend on where sampling stopped — one clean step measured here passed+ * at 30 cycles and failed at 40.+ */+const CONFIDENCE_K = 2;++interface Fit {+ /** Least-squares growth per cycle. */+ slope: number;+ /** Standard error of that slope; 0 when the points are collinear. */+ stderr: number;+ /** Lower bound of the confidence interval — the slope we can actually claim. */+ lower: number;+}++/** Least-squares fit of `ys` against its own index, with the slope's uncertainty. */+function fit(ys: readonly number[]): Fit {+ const n = ys.length;+ if (n < 2) return { slope: 0, stderr: 0, lower: 0 };+ const meanX = (n - 1) / 2;+ let meanY = 0;+ for (const y of ys) meanY += y;+ meanY /= n;+ let sxy = 0;+ let sxx = 0;+ for (let i = 0; i < n; i++) {+ const dx = i - meanX;+ sxy += dx * (ys[i] - meanY);+ sxx += dx * dx;+ }+ if (sxx === 0) return { slope: 0, stderr: 0, lower: 0 };+ const slope = sxy / sxx;+ const intercept = meanY - slope * meanX;++ let sse = 0;+ for (let i = 0; i < n; i++) {+ const residual = ys[i] - (intercept + slope * i);+ sse += residual * residual;+ }+ const stderr = n > 2 ? Math.sqrt(sse / (n - 2) / sxx) : 0;+ // Toward zero from both directions: a negative slope's claim is its upper bound.+ const lower = slope >= 0+ ? Math.max(0, slope - CONFIDENCE_K * stderr)+ : Math.min(0, slope + CONFIDENCE_K * stderr);+ return { slope, stderr, lower };+}++/**+ * Judge a run: one census per cycle, in order. Tiers share the fitted slope,+ * differing only in how much of one they may have.+ *+ * Conserved counters are also checked for VARIANCE: one that spiked and came+ * back means a cycle cleans up late, which the slope alone reads as steady.+ */+export function analyzeCensusSeries(samples: readonly Census[], opts: CensusSeriesOptions = {}): CensusReport {+ const projectCycles = opts.projectCycles ?? DEFAULT_PROJECT_CYCLES;+ const boundedTol = opts.boundedSlopeTolerance ?? 0;+ const byteBudget = opts.trendByteBudgetPerCycle ?? 64 * 1024;+ const warmup = Math.min(+ opts.warmupCycles ?? Math.max(3, Math.floor(samples.length / 5)),+ Math.max(0, samples.length - 2),+ );+ const judged = samples.slice(warmup);++ const keys = new Set<string>();+ for (const s of samples) for (const k of s.entries.keys()) keys.add(k);++ const verdicts: CensusVerdict[] = [];+ for (const key of [...keys].sort()) {+ const spec = judged.find((s) => s.entries.has(key))?.entries.get(key)+ ?? samples.find((s) => s.entries.has(key))!.entries.get(key)!;+ const ys = judged.map((s) => s.entries.get(key)?.value ?? 0);+ const { slope: m, lower } = fit(ys);+ const first = ys[0] ?? 0;+ const last = ys[ys.length - 1] ?? 0;+ const projected = lower * projectCycles;++ let leaking = false;+ let reason: string | undefined;+ let rising = 0;+ if (spec.tier === 'conserved') {+ // Integers with a hard contract: no fit, no tolerance, no argument.+ const min = Math.min(...ys);+ const max = Math.max(...ys);+ if (max !== min) {+ leaking = true;+ reason = last !== first+ ? `conserved counter moved ${fmt(first, spec.unit)} → ${fmt(last, spec.unit)} over ${ys.length} cycles `+ + `(${signed(m, spec.unit)}/cycle; ${signed(m * projectCycles, spec.unit)} over ${projectCycles})`+ : `conserved counter is not stable within the run: ranged ${fmt(min, spec.unit)}…${fmt(max, spec.unit)} `+ + 'while starting and ending equal — a cycle is cleaning up late, and a longer session overlaps two of them';+ }+ } else {+ const budget = spec.tier === 'bounded' ? boundedTol+ : spec.unit === 'bytes' ? byteBudget : boundedTol;+ rising = risingFraction(ys);+ if (spec.tier !== 'info'+ && ys.length >= MIN_FITTED_SAMPLES+ && lower > budget+ && rising >= MIN_RISING_FRACTION) {+ leaking = true;+ const what = spec.tier === 'bounded'+ ? 'bounded counter grows where a pool would plateau'+ : 'grows beyond its budget';+ reason = `${what}: ${signed(m, spec.unit)}/cycle, at least ${signed(lower, spec.unit)}/cycle `+ + `after uncertainty (budget ${fmt(budget, spec.unit)}/cycle), `+ + `rising on ${Math.round(rising * 100)}% of cycles — `+ + `${signed(projected, spec.unit)} over ${projectCycles} cycles`;+ }+ }++ verdicts.push({+ key, tier: spec.tier, unit: spec.unit, leaking, risingFraction: rising,+ slopePerCycle: m, confidentSlopePerCycle: lower, first, last, projected, reason,+ });+ }++ const failedProbes = [...new Set(samples.flatMap((s) => s.failedProbes))];+ return {+ cycles: samples.length,+ judgedFrom: warmup,+ projectCycles,+ verdicts,+ leaks: verdicts.filter((v) => v.leaking),+ failedProbes,+ };+}++// =============================================================================+// Formatting+// =============================================================================++const MB = 1024 * 1024;++function fmt(value: number, unit: CensusEntry['unit']): string {+ if (unit !== 'bytes') {+ return Number.isInteger(value) ? String(value) : value.toFixed(3);+ }+ const abs = Math.abs(value);+ if (abs >= MB) return `${(value / MB).toFixed(2)} MB`;+ if (abs >= 1024) return `${(value / 1024).toFixed(2)} KB`;+ return `${value.toFixed(0)} B`;+}++function signed(value: number, unit: CensusEntry['unit']): string {+ return (value >= 0 ? '+' : '') + fmt(value, unit);+}++/** Two snapshots, as a table. Rows that did not move are omitted unless `all`. */+export function formatCensusDiff(before: Census, after: Census, all = false): string {+ const rows = diffCensus(before, after).filter((d) => all || d.delta !== 0);+ if (rows.length === 0) return 'census: nothing moved';+ const width = Math.max(...rows.map((r) => r.key.length));+ return rows+ .map((r) => ` ${r.key.padEnd(width)} ${fmt(r.before, r.unit)} → ${fmt(r.after, r.unit)} (${signed(r.delta, r.unit)}) [${r.tier}]`)+ .join('\n');+}++/**+ * A run, as the failure message it should print.+ *+ * Leaks lead; the rest follows as context, because the counter that did NOT move+ * is half the diagnosis — entities conserved while GL textures climb says the+ * scene tore down and the renderer did not.+ */+export function formatCensusReport(report: CensusReport): string {+ const lines: string[] = [];+ const judgedCount = report.cycles - report.judgedFrom;+ lines.push(+ `census: ${report.cycles} cycles, judged from cycle ${report.judgedFrom}, ` ++ `projections over ${report.projectCycles}`,+ );+ if (judgedCount < MIN_FITTED_SAMPLES) {+ lines.push(+ ` only ${judgedCount} judged cycles — conserved counters still hold, ` ++ `but nothing fitted (pools, caches, heaps) was judged. Run at least ${MIN_FITTED_SAMPLES + 3}.`,+ );+ }+ if (report.failedProbes.length > 0) {+ lines.push(' probes that stopped answering (counters MISSING, not zero):');+ for (const f of report.failedProbes) lines.push(` ! ${f}`);+ }+ if (report.leaks.length === 0) {+ lines.push(' no counter drifted beyond its tier');+ } else {+ lines.push(` ${report.leaks.length} leaking:`);+ for (const v of report.leaks) lines.push(` ✗ ${v.key} — ${v.reason}`);+ }+ const steady = report.verdicts.filter((v) => !v.leaking);+ if (steady.length > 0) {+ const width = Math.max(...steady.map((v) => v.key.length));+ lines.push(' steady:');+ for (const v of steady) {+ // Both numbers: the raw slope says what was measured, the confident+ // one says how much of it the samples support. A wide gap between+ // them is the signal to run more cycles, not to trust either.+ const claim = v.tier === 'conserved' ? '' : ` ≥${signed(v.confidentSlopePerCycle, v.unit)}`;+ lines.push(+ ` ${v.key.padEnd(width)} ${fmt(v.last, v.unit)} ` ++ `(${signed(v.slopePerCycle, v.unit)}/cycle${claim}) [${v.tier}]`,+ );+ }+ }+ return lines.join('\n');+}diff --git a/sdk/src/diagnostics/censusProbes.ts b/sdk/src/diagnostics/censusProbes.tsnew file mode 100644index 000000000..39d397679--- /dev/null+++ b/sdk/src/diagnostics/censusProbes.ts@@ -0,0 +1,248 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file censusProbes.ts+ * @brief The engine's own census probes — one place that knows which of the+ * engine's counters obey a conservation law and which are caches.+ *+ * @details Installed by a CALL, never by a bare side-effect import. The first+ * version registered at module load and a bundler removed the module+ * whole: `takeCensus` shipped in dist with zero probes, answering every+ * question with an empty snapshot — an instrument that cannot fail+ * because it cannot measure. Nothing here runs until a census is taken.+ *+ * Every probe returns `undefined` rather than zeros when its subsystem+ * is absent. The distinction matters more than it looks: a census that+ * reported `render.gl.textures = 0` because the renderer was not up+ * would show a texture leak as a clean fall to zero, which is the exact+ * shape of the bug it exists to catch.+ */+import { registerCensusProbe, counter } from './censusRegistry';+import type { CensusContext, CensusEntry, CensusTier } from './censusTypes';+import { liveEmitterHandlers } from '../ecs/emitter';+import { liveDomListeners } from '../util/listeners';+import { getResourceManager } from '../wasm/resourceManager';+import type { World } from '../ecs/world';+import type { ESEngineModule } from '../wasm';++function worldOf(ctx: CensusContext): World | undefined {+ return ctx.world ?? ctx.app?.world;+}++function moduleOf(ctx: CensusContext): ESEngineModule | null {+ return ctx.module ?? ctx.app?.wasmModule ?? null;+}++/**+ * Subsystems are reached by resource NAME, not by importing their tokens.+ * Importing them would put every plugin the census can see into the import graph+ * of the census itself — a game that only wants an entity count would pull in+ * Box2D — and would make this module a cycle for anything registering a probe.+ */+function resource<T>(ctx: CensusContext, name: string): T | undefined {+ return ctx.app?.getResourceByName(name) as T | undefined;+}++/**+ * Register the engine's own probes. Idempotent (probes are keyed by id), so a+ * second call replaces rather than doubles.+ */+export function installBuiltinCensusProbes(): void {+ // =============================================================================+ // ECS+ // =============================================================================++ registerCensusProbe({+ id: 'ecs',+ read(ctx) {+ const world = worldOf(ctx);+ if (!world) return undefined;+ const s = world.getStorageSizes();+ return [+ counter('ecs.entities', s.entities, 'conserved'),+ counter('ecs.scriptRows', s.scripts.rows, 'conserved'),+ counter('ecs.scriptEntities', s.scripts.entities, 'conserved'),+ counter('ecs.names', s.names.entities, 'conserved'),+ counter('ecs.spawnCallbacks', s.spawnCallbacks, 'conserved'),+ counter('ecs.despawnCallbacks', s.despawnCallbacks, 'conserved'),+ counter('ecs.changeRows.added', s.changes.addedRows, 'conserved'),+ counter('ecs.changeRows.changed', s.changes.changedRows, 'conserved'),+ // Drained by cleanRemovedBuffer, not by despawn — so it is legitimately+ // non-zero mid-frame and must still not climb from cycle to cycle.+ counter('ecs.changeRows.removed', s.changes.removedRows, 'bounded'),+ counter('ecs.nameKeys', s.names.names, 'bounded'),+ counter('ecs.scriptStorages', s.scripts.storages, 'bounded'),+ counter('ecs.trackedComponents', s.changes.tracked, 'bounded'),+ counter('ecs.queryCacheEntries', s.queryCacheEntries, 'bounded'),+ counter('ecs.indexSlots', s.indexSlots, 'bounded'),+ ];+ },+ });++ // =============================================================================+ // Subscriptions+ // =============================================================================++ registerCensusProbe({+ id: 'events',+ read() {+ return [+ counter('events.emitterHandlers', liveEmitterHandlers(), 'conserved'),+ counter('events.domListeners', liveDomListeners(), 'conserved'),+ ];+ },+ });++ // =============================================================================+ // Renderer — GPU objects and the resource manager's view of them+ // =============================================================================++ registerCensusProbe({+ id: 'render',+ read(ctx) {+ const module = moduleOf(ctx);+ if (!module) return undefined;+ const out: CensusEntry[] = [];++ const live = module.renderer_getLiveObjects?.();+ if (live) {+ out.push(+ counter('render.gl.buffers', live.buffers, 'conserved'),+ counter('render.gl.textures', live.textures, 'conserved'),+ counter('render.gl.programs', live.programs, 'conserved'),+ counter('render.gl.renderTargets', live.renderTargets, 'conserved'),+ // A readback is a request awaiting collection; at rest there are none.+ counter('render.gl.readbacks', live.readbacks, 'conserved'),+ counter('render.gl.layouts', live.layouts, 'bounded'),+ counter('render.gl.pipelines', live.pipelines, 'bounded'),+ );+ }++ const stats = getResourceManager()?.getResourceStats();+ if (stats) {+ out.push(+ counter('render.rm.textures', stats.textureCount, 'bounded'),+ counter('render.rm.shaders', stats.shaderCount, 'bounded'),+ counter('render.rm.vertexBuffers', stats.vertexBufferCount, 'bounded'),+ counter('render.rm.indexBuffers', stats.indexBufferCount, 'bounded'),+ counter('render.rm.textureBytes', stats.textureBytes, 'bounded', 'bytes'),+ counter('render.rm.evictable', stats.textureEvictableCount, 'info'),+ );+ }++ return out.length > 0 ? out : undefined;+ },+ });++ // =============================================================================+ // Assets+ // =============================================================================++ type AssetSizes = ReturnType<import('../asset/Assets').Assets['sizes']>;++ registerCensusProbe({+ id: 'asset',+ read(ctx) {+ const assets = resource<{ sizes?: () => AssetSizes }>(ctx, 'Assets');+ if (!assets?.sizes) return undefined;+ const s = assets.sizes();+ return [+ counter('asset.refCounts', s.refCounts, 'conserved'),+ counter('asset.handlePaths', s.handlePaths, 'conserved'),+ counter('asset.trackedRefRows', s.trackedRefRows, 'conserved'),+ counter('asset.invalidateListeners', s.invalidateListeners, 'conserved'),+ // Zero at rest. A load still pending between cycles is holding its+ // promise, its callbacks and everything they closed over.+ counter('asset.pendingLoads', s.pendingLoads, 'conserved'),+ counter('asset.textureCached', s.textureCached, 'bounded'),+ counter('asset.genericCached', s.genericCached, 'bounded'),+ counter('asset.genericCaches', s.genericCaches, 'bounded'),+ counter('asset.registryEntries', s.registryEntries, 'info'),+ ];+ },+ });++ // =============================================================================+ // Physics — only present once the side module is loaded+ // =============================================================================++ interface PhysicsCensusModule {+ _physics_getBodyCount?(): number;+ _physics_getShapeCount?(): number;+ _physics_getJointCount?(): number;+ _physics_getTrackingRows?(): number;+ _physics_getDynamicBodyCount?(): number;+ }++ registerCensusProbe({+ id: 'physics',+ read(ctx) {+ const m = resource<{ module: PhysicsCensusModule | null }>(ctx, 'PhysicsRuntime')?.module;+ // Absent until the side module resolves, and absent forever in a game+ // with no physics — both are "no counters", never "no bodies".+ if (!m?._physics_getBodyCount) return undefined;+ return [+ counter('physics.bodies', m._physics_getBodyCount(), 'conserved'),+ counter('physics.shapes', m._physics_getShapeCount?.() ?? 0, 'conserved'),+ counter('physics.joints', m._physics_getJointCount?.() ?? 0, 'conserved'),+ counter('physics.trackingRows', m._physics_getTrackingRows?.() ?? 0, 'conserved'),+ counter('physics.dynamicBodies', m._physics_getDynamicBodyCount?.() ?? 0, 'info'),+ ];+ },+ });++ // =============================================================================+ // Heaps+ // =============================================================================++ interface ChromiumMemory {+ usedJSHeapSize: number;+ totalJSHeapSize: number;+ }++ registerCensusProbe({+ id: 'heap',+ read(ctx) {+ const out: CensusEntry[] = [];++ // Judged only where a collection can be forced first (see collectGarbage),+ // and even then loosely — on a clean workload this wanders without scaling+ // with the work done. The exact C++ signal below is what catches a leak.+ const jsTier: CensusTier = typeof (globalThis as { gc?: unknown }).gc === 'function' ? 'trend' : 'info';++ // Chromium only, and behind a flag in some builds. Node answers through+ // process.memoryUsage instead; neither exists everywhere, hence the pair.+ const mem = (performance as unknown as { memory?: ChromiumMemory }).memory;+ if (mem && typeof mem.usedJSHeapSize === 'number') {+ out.push(counter('js.heapUsed', mem.usedJSHeapSize, jsTier, 'bytes'));+ } else {+ const proc = (globalThis as { process?: { memoryUsage?: () => { heapUsed: number; external: number } } }).process;+ const usage = proc?.memoryUsage?.();+ if (usage) {+ out.push(+ counter('js.heapUsed', usage.heapUsed, jsTier, 'bytes'),+ counter('js.external', usage.external, jsTier, 'bytes'),+ );+ }+ }++ const module = moduleOf(ctx);+ const heap = (module as { HEAPU8?: Uint8Array } | null)?.HEAPU8;+ if (heap) {+ // RESERVED, not used: emscripten's heap only ever grows, so this rises+ // in steps and never falls. It is `bounded` because a step that keeps+ // repeating is the leak — the plateau itself is normal.+ out.push(counter('wasm.heapReserved', heap.length, 'bounded', 'bytes'));+ }+ const mallocBytes = module?.es_getMallocBytes?.();+ if (typeof mallocBytes === 'number') {+ // Exact, and it falls when memory is returned — so unlike either heap+ // number this needs no statistics and no allowance. Bounded rather+ // than conserved only because allocator free-lists legitimately settle.+ out.push(counter('wasm.mallocBytes', mallocBytes, 'bounded', 'bytes'));+ }++ return out.length > 0 ? out : undefined;+ },+ });+}diff --git a/sdk/src/diagnostics/censusRegistry.ts b/sdk/src/diagnostics/censusRegistry.tsnew file mode 100644index 000000000..51b986cbe--- /dev/null+++ b/sdk/src/diagnostics/censusRegistry.ts@@ -0,0 +1,67 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file censusRegistry.ts+ * @brief Where probes are kept, apart from both the probes and the judge.+ *+ * @details Split out so `census.ts` can depend on the engine's own probes (it+ * installs them before the first snapshot) while those probes depend+ * only on this — no cycle. The bundler's tree-shaking makes the+ * alternative unsafe: with every module but an entry marked+ * side-effect free, registrations reached by a bare import or a+ * top-level call are dropped from dist, and takeCensus ships blind.+ */+import type { Census, CensusEntry, CensusProbe, CensusContext, CensusTier } from './censusTypes';++const probes = new Map<string, CensusProbe>();++/**+ * Register a source of counters. Keyed by `probe.id`, so a plugin installed+ * twice replaces its probe rather than double-counting through it.+ */+export function registerCensusProbe(probe: CensusProbe): () => void {+ probes.set(probe.id, probe);+ return () => {+ if (probes.get(probe.id) === probe) probes.delete(probe.id);+ };+}++/** Registered probe ids, for diagnosing a census that came back thinner than expected. */+export function registeredProbeIds(): string[] {+ return [...probes.keys()].sort();+}++/**+ * Read every registered probe into one snapshot.+ *+ * A probe that throws is RECORDED as failed, not allowed to abort the census:+ * the other twenty counters still answer, and "this probe stopped" is itself a+ * finding — silently missing counters is how a leak hides.+ */+export function readProbes(ctx: CensusContext): Census {+ const entries = new Map<string, CensusEntry>();+ const failed: string[] = [];++ for (const probe of probes.values()) {+ let read: readonly CensusEntry[] | undefined;+ try {+ read = probe.read(ctx);+ } catch (e) {+ failed.push(`${probe.id}: ${e instanceof Error ? e.message : String(e)}`);+ continue;+ }+ if (!read) continue;+ for (const entry of read) entries.set(entry.key, entry);+ }++ return {+ atMs: typeof performance !== 'undefined' ? performance.now() : 0,+ entries,+ failedProbes: failed,+ };+}++/** Build one counter. Sugar so a probe body reads as a list of facts. */+export function counter(key: string, value: number, tier: CensusTier, unit: CensusEntry['unit'] = 'count'): CensusEntry {+ return { key, value, tier, unit };+}diff --git a/sdk/src/diagnostics/censusTypes.ts b/sdk/src/diagnostics/censusTypes.tsnew file mode 100644index 000000000..c7b581d31--- /dev/null+++ b/sdk/src/diagnostics/censusTypes.ts@@ -0,0 +1,55 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file censusTypes.ts+ * @brief The census vocabulary, apart from the registry that collects it.+ *+ * @details A probe lives in the subsystem it measures — the ECS one in ecs/, the+ * renderer's next to the renderer — and each needs these types to+ * declare itself. Were they in census.ts, every subsystem would take a+ * value import of the registry to get a type, and the registry imports+ * nothing on purpose so that anything can register with it.+ */+import type { App } from '../app/app';+import type { World } from '../ecs/world';+import type { ESEngineModule } from '../wasm';++/**+ * How a counter is allowed to behave over a long run. See census.ts for why the+ * distinction is the whole design and not bookkeeping.+ */+export type CensusTier = 'conserved' | 'bounded' | 'trend' | 'info';++export interface CensusEntry {+ /** Dotted namespace: `ecs.entities`, `render.gl.textures`, `physics.bodies`. */+ readonly key: string;+ readonly value: number;+ readonly tier: CensusTier;+ readonly unit: 'count' | 'bytes';+}++/**+ * What a probe is given to read. Every field is optional and a probe must cope+ * with any of them missing: a census is taken from a bare World in a unit test,+ * from a full App in the editor, and from a running game where the wasm module+ * is reachable but the App is behind a realm boundary.+ */+export interface CensusContext {+ readonly app?: App;+ readonly world?: World;+ readonly module?: ESEngineModule | null;+}++export interface CensusProbe {+ /** Stable identity; registering the same id twice replaces rather than duplicates. */+ readonly id: string;+ /** `undefined` when this probe cannot measure anything in the given context. */+ read(ctx: CensusContext): readonly CensusEntry[] | undefined;+}++export interface Census {+ readonly atMs: number;+ readonly entries: ReadonlyMap<string, CensusEntry>;+ /** Probes that threw. Their counters are ABSENT from `entries`, not zero. */+ readonly failedProbes: readonly string[];+}diff --git a/sdk/src/diagnostics/index.ts b/sdk/src/diagnostics/index.tsindex fb9aa6780..36eb97ce8 100644--- a/sdk/src/diagnostics/index.ts+++ b/sdk/src/diagnostics/index.ts@@ -12,3 +12,12 @@ export {fingerprint, messageOf, stackOf,type DiagnosticEvent, type DiagnosticKind, type DiagnosticReport,} from './events';+export {+ takeCensus, registerCensusProbe, censusProbeIds, counter, collectGarbage,+ diffCensus, analyzeCensusSeries, formatCensusDiff, formatCensusReport,+ type CensusDelta, type CensusSeriesOptions, type CensusVerdict, type CensusReport,+} from './census';+export {+ type Census, type CensusEntry, type CensusTier,+ type CensusContext, type CensusProbe,+} from './censusTypes';diff --git a/sdk/src/ecs/ChangeTracker.ts b/sdk/src/ecs/ChangeTracker.tsindex 8f2618308..3a9ac2c63 100644--- a/sdk/src/ecs/ChangeTracker.ts+++ b/sdk/src/ecs/ChangeTracker.ts@@ -125,4 +125,27 @@ export class ChangeTracker {// padding and justification laying the node out for the rest of the run.this.componentLastChangedTick_.set(componentId, this.worldTick_);}++ /**+ * @internal Live map sizes for the resource census.+ *+ * `removedRows` is the one that can run away: it is drained only by+ * {@link cleanRemovedBuffer}, so a tracked component whose consumer stops+ * calling that accumulates a row per despawn for the life of the world.+ */+ sizes(): { tracked: number; addedRows: number; changedRows: number; removedRows: number } {+ const rowsIn = (maps: Map<symbol, Map<Entity, number>>): number => {+ let n = 0;+ for (const m of maps.values()) n += m.size;+ return n;+ };+ let removedRows = 0;+ for (const buffer of this.componentRemovedBuffer_.values()) removedRows += buffer.length;+ return {+ tracked: this.trackedComponents_.size,+ addedRows: rowsIn(this.componentAddedTicks_),+ changedRows: rowsIn(this.componentChangedTicks_),+ removedRows,+ };+ }}diff --git a/sdk/src/ecs/NameIndex.ts b/sdk/src/ecs/NameIndex.tsindex 218750ff3..45d1bcf91 100644--- a/sdk/src/ecs/NameIndex.ts+++ b/sdk/src/ecs/NameIndex.ts@@ -45,6 +45,11 @@ export class NameIndex {return last;}+ /** @internal Live map sizes for the resource census. */+ sizes(): { names: number; entities: number } {+ return { names: this.nameToEntities_.size, entities: this.entityToName_.size };+ }+private unlink_(name: string, entity: Entity): void {const set = this.nameToEntities_.get(name);if (!set) return;diff --git a/sdk/src/ecs/ScriptStorage.ts b/sdk/src/ecs/ScriptStorage.tsindex 961ea80c9..f85fec41a 100644--- a/sdk/src/ecs/ScriptStorage.ts+++ b/sdk/src/ecs/ScriptStorage.ts@@ -125,4 +125,17 @@ export class ScriptStorage {this.entityComponents_.delete(entity);return removed;}++ /**+ * @internal Live map sizes for the resource census.+ *+ * `storages` counts component types ever stored and never shrinks by design+ * (an emptied storage is kept for reuse), so the census tracks it as bounded+ * while `rows` and `entities` are the conserved pair.+ */+ sizes(): { storages: number; rows: number; entities: number } {+ let rows = 0;+ for (const storage of this.tsStorage_.values()) rows += storage.size;+ return { storages: this.tsStorage_.size, rows, entities: this.entityComponents_.size };+ }}diff --git a/sdk/src/ecs/emitter.ts b/sdk/src/ecs/emitter.tsindex f852fb832..4c6f3a5b5 100644--- a/sdk/src/ecs/emitter.ts+++ b/sdk/src/ecs/emitter.ts@@ -8,6 +8,19 @@type AnyHandler = (...args: unknown[]) => void;+let liveHandlers = 0;++/**+ * Handlers subscribed through every Emitter in this realm, right now.+ *+ * A forgotten unsubscribe is invisible per-instance — one extra handler looks+ * like nothing — and shows only as a total that never comes back down. The+ * census treats it as conserved: a Play/Stop round trip must end where it began.+ */+export function liveEmitterHandlers(): number {+ return liveHandlers;+}+export class Emitter<E extends Record<keyof E, unknown[]>> {private handlers_ = new Map<keyof E, Set<AnyHandler>>();@@ -17,9 +30,17 @@ export class Emitter<E extends Record<keyof E, unknown[]>> {set = new Set();this.handlers_.set(event, set);}- set.add(handler as AnyHandler);+ if (!set.has(handler as AnyHandler)) {+ set.add(handler as AnyHandler);+ liveHandlers++;+ }return () => {- set.delete(handler as AnyHandler);+ // Delete reports whether it removed anything, so an unsubscribe called+ // twice — or after clear() — cannot drive the live count negative.+ if (set.delete(handler as AnyHandler)) {+ liveHandlers--;+ if (set.size === 0) this.handlers_.delete(event);+ }};}@@ -31,6 +52,14 @@ export class Emitter<E extends Record<keyof E, unknown[]>> {}clear(): void {+ for (const set of this.handlers_.values()) liveHandlers -= set.size;this.handlers_.clear();}++ /** Handlers held by this emitter across all its events. */+ get size(): number {+ let n = 0;+ for (const set of this.handlers_.values()) n += set.size;+ return n;+ }}diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.tsindex 429b9be2a..8ac3db129 100644--- a/sdk/src/ecs/world.ts+++ b/sdk/src/ecs/world.ts@@ -326,6 +326,35 @@ export class World {return this.entities_.size;}+ /**+ * @internal Live sizes of every map the world keeps, for the resource census.+ *+ * `indexSlots` never shrinks by design — it is keyed by entity INDEX, which+ * the registry recycles, so it settles at the session's peak. One that keeps+ * climbing means indices are not being reused, which entityCount() cannot show.+ */+ getStorageSizes(): {+ entities: number;+ indexSlots: number;+ spawnCallbacks: number;+ despawnCallbacks: number;+ names: ReturnType<NameIndex['sizes']>;+ scripts: ReturnType<ScriptStorage['sizes']>;+ changes: ReturnType<ChangeTracker['sizes']>;+ queryCacheEntries: number;+ } {+ return {+ entities: this.entities_.size,+ indexSlots: this.indexGeneration_.size,+ spawnCallbacks: this.spawnCallbacks_.length,+ despawnCallbacks: this.despawnCallbacks_.length,+ names: this.names_.sizes(),+ scripts: this.scripts_.sizes(),+ changes: this.changes_.sizes(),+ queryCacheEntries: this.queries_.getStats().size,+ };+ }+getWorldVersion(): number {return this.queries_.structuralVersion;}diff --git a/sdk/src/physics/PhysicsModuleLoader.ts b/sdk/src/physics/PhysicsModuleLoader.tsindex a677dbc4b..b6c57205f 100644--- a/sdk/src/physics/PhysicsModuleLoader.ts+++ b/sdk/src/physics/PhysicsModuleLoader.ts@@ -51,6 +51,10 @@ export interface PhysicsWasmModule {_physics_setBodyTransform(entityId: number, x: number, y: number, angle: number): void;_physics_setBodyTargetTransform(entityId: number, x: number, y: number, angle: number, dt: number): void;_physics_getDynamicBodyCount(): number;+ _physics_getBodyCount(): number;+ _physics_getShapeCount(): number;+ _physics_getJointCount(): number;+ _physics_getTrackingRows(): number;_physics_getDynamicBodyTransforms(): number;/**diff --git a/sdk/src/util/listeners.ts b/sdk/src/util/listeners.tsnew file mode 100644index 000000000..cccef2bbf--- /dev/null+++ b/sdk/src/util/listeners.ts@@ -0,0 +1,52 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file listeners.ts+ * @brief Host event listeners, counted — because nothing else can count them.+ *+ * @details `addEventListener` is write-only: having called it, there is no way+ * to ask a target what is attached to it. So a plugin that subscribes+ * to `resize` on install and forgets to detach on cleanup leaks one+ * listener per Play/Stop, every one of them still firing, and no+ * instrument in the engine or the browser will say so. It shows up as+ * "the editor got slow after lunch".+ *+ * Subscribing through {@link addTrackedListener} makes the total+ * readable, which is all the resource census needs: the count is+ * conserved across a Play/Stop round trip, so drift IS the bug report.+ * The disposer it returns is idempotent, so a cleanup path that runs+ * twice cannot push the count below what is really attached.+ */++type Target = {+ addEventListener(type: string, handler: (ev: never) => void, options?: unknown): void;+ removeEventListener(type: string, handler: (ev: never) => void, options?: unknown): void;+};++let live = 0;++/** Host listeners attached through {@link addTrackedListener} and not yet removed. */+export function liveDomListeners(): number {+ return live;+}++/**+ * `target.addEventListener`, plus the bookkeeping. Returns the detach — call it+ * instead of `removeEventListener` so the count stays honest.+ */+export function addTrackedListener<E>(+ target: Target,+ type: string,+ handler: (ev: E) => void,+ options?: AddEventListenerOptions | boolean,+): () => void {+ target.addEventListener(type, handler as (ev: never) => void, options);+ live++;+ let detached = false;+ return () => {+ if (detached) return;+ detached = true;+ live--;+ target.removeEventListener(type, handler as (ev: never) => void, options);+ };+}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 7455d94cd..6850c123f 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -93,6 +93,21 @@ export interface CppResourceManager {measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number };}+/**+ * GPU objects the graphics device is holding, as {@link ESEngineModule.renderer_getLiveObjects}+ * reports them. The C++ side documents which of these obey a conservation law+ * and which are caches (renderer/rhi/GfxDevice.hpp).+ */+export interface GfxLiveObjects {+ buffers: number;+ textures: number;+ programs: number;+ layouts: number;+ pipelines: number;+ renderTargets: number;+ readbacks: number;+}+// =============================================================================// WASM Module Interface// =============================================================================@@ -346,7 +361,19 @@ export interface ESEngineModule {renderer_releaseTarget(handle: number): void;renderer_getTargetTexture(handle: number): number;renderer_getTargetDepthTexture(handle: number): number;+ /**+ * Bytes malloc has handed out and not got back — the exact C++ leak signal+ * for the resource census. Optional: older engine builds do not carry it.+ */+ es_getMallocBytes?(): number;renderer_getDrawCalls(): number;+ /**+ * GPU objects the device has created and not destroyed, for the resource+ * census. Null when no device is initialized — a census must record those+ * counters as ABSENT, since zero would read as "everything was freed".+ * Optional: older engine builds do not carry it.+ */+ renderer_getLiveObjects?(): GfxLiveObjects | null;renderer_getTriangles(): number;renderer_getSprites(): number;renderer_getText(): number;