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.

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.md
index 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) => number
getTextureRefs: (path: string) => number[]
getTotalRefCount: () => { textures: number; fonts: number; materials: number; }
+getTotalRefRows: () => number
removeAllRefsForEntity: (entity: number) => void
removeFontRef: (path: string, entity: number) => void
removeMaterialRef: (path: string, entity: number) => void
@@ -673,6 +674,7 @@ get: (key: string) => T | undefined
getOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>
has: (key: string) => boolean
invalidate: (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: number
y: 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) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+es_getMallocBytes: (() => number) | undefined
esshader_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: () => number
geometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void
@@ -2566,6 +2645,7 @@ renderer_getCapturedFrameSize: () => number
renderer_getCulled: () => number
renderer_getDrawCalls: () => number
renderer_getGpuTimeMs: (() => number) | undefined
+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
renderer_getPreviewHeight: () => number
renderer_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 | null
getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (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 | null
getWorldTick: () => number
getWorldVersion: () => number
@@ -8647,6 +8732,11 @@ TransformData
AiRegistry<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
```
TextInputPlugin
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => number
getTextureRefs: (path: string) => number[]
getTotalRefCount: () => { textures: number; fonts: number; materials: number; }
+getTotalRefRows: () => number
removeAllRefsForEntity: (entity: number) => void
removeFontRef: (path: string, entity: number) => void
removeMaterialRef: (path: string, entity: number) => void
@@ -673,6 +674,7 @@ get: (key: string) => T | undefined
getOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>
has: (key: string) => boolean
invalidate: (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: number
y: 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) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+es_getMallocBytes: (() => number) | undefined
esshader_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: () => number
geometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void
@@ -2574,6 +2653,7 @@ renderer_getCapturedFrameSize: () => number
renderer_getCulled: () => number
renderer_getDrawCalls: () => number
renderer_getGpuTimeMs: (() => number) | undefined
+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
renderer_getPreviewHeight: () => number
renderer_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 | null
getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (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 | null
getWorldTick: () => number
getWorldVersion: () => number
@@ -8817,6 +8902,11 @@ TransformData
AiRegistry<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
```
TextInputPlugin
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => number
getTextureRefs: (path: string) => number[]
getTotalRefCount: () => { textures: number; fonts: number; materials: number; }
+getTotalRefRows: () => number
removeAllRefsForEntity: (entity: number) => void
removeFontRef: (path: string, entity: number) => void
removeMaterialRef: (path: string, entity: number) => void
@@ -668,6 +669,7 @@ get: (key: string) => T | undefined
getOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>
has: (key: string) => boolean
invalidate: (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: number
y: 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) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+es_getMallocBytes: (() => number) | undefined
esshader_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: () => number
geometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void
@@ -2561,6 +2640,7 @@ renderer_getCapturedFrameSize: () => number
renderer_getCulled: () => number
renderer_getDrawCalls: () => number
renderer_getGpuTimeMs: (() => number) | undefined
+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
renderer_getPreviewHeight: () => number
renderer_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 | null
getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (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 | null
getWorldTick: () => number
getWorldVersion: () => number
@@ -8642,6 +8727,11 @@ TransformData
AiRegistry<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
```
TextInputPlugin
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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) => number
getTextureRefs: (path: string) => number[]
getTotalRefCount: () => { textures: number; fonts: number; materials: number; }
+getTotalRefRows: () => number
removeAllRefsForEntity: (entity: number) => void
removeFontRef: (path: string, entity: number) => void
removeMaterialRef: (path: string, entity: number) => void
@@ -668,6 +669,7 @@ get: (key: string) => T | undefined
getOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>
has: (key: string) => boolean
invalidate: (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: number
y: 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) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+es_getMallocBytes: (() => number) | undefined
esshader_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: () => number
geometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void
@@ -2561,6 +2640,7 @@ renderer_getCapturedFrameSize: () => number
renderer_getCulled: () => number
renderer_getDrawCalls: () => number
renderer_getGpuTimeMs: (() => number) | undefined
+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
renderer_getPreviewHeight: () => number
renderer_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 | null
getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (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 | null
getWorldTick: () => number
getWorldVersion: () => number
@@ -8887,6 +8972,11 @@ TransformData
AiRegistry<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
```
TextInputPlugin
diff --git a/sdk/etc/physics.api.md b/sdk/etc/physics.api.md
index 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) => number
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 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) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+es_getMallocBytes: (() => number) | undefined
esshader_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: () => number
geometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void
@@ -307,6 +308,7 @@ renderer_getCapturedFrameSize: () => number
renderer_getCulled: () => number
renderer_getDrawCalls: () => number
renderer_getGpuTimeMs: (() => number) | undefined
+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
renderer_getPreviewHeight: () => number
renderer_getPreviewPtr: () => number
@@ -398,3 +400,14 @@ unlink: (path: string) => void
writeFile: (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.md
index 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) => number
getTextureRefs: (path: string) => number[]
getTotalRefCount: () => { textures: number; fonts: number; materials: number; }
+getTotalRefRows: () => number
removeAllRefsForEntity: (entity: number) => void
removeFontRef: (path: string, entity: number) => void
removeMaterialRef: (path: string, entity: number) => void
@@ -668,6 +669,7 @@ get: (key: string) => T | undefined
getOrLoad: (key: string, loader: () => Promise<T>, timeout?: number) => Promise<T>
has: (key: string) => boolean
invalidate: (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: number
y: 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) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+es_getMallocBytes: (() => number) | undefined
esshader_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: () => number
geometry_init: (handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean) => void
@@ -2561,6 +2640,7 @@ renderer_getCapturedFrameSize: () => number
renderer_getCulled: () => number
renderer_getDrawCalls: () => number
renderer_getGpuTimeMs: (() => number) | undefined
+renderer_getLiveObjects: (() => GfxLiveObjects | null) | undefined
renderer_getMeshes: () => number
renderer_getPreviewHeight: () => number
renderer_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 | null
getEntitiesWithComponents: (components: AnyComponentDef[], withFilters?: AnyComponentDef[], withoutFilters?: AnyComponentDef[], precomputedKey?: string, filter?: QueryFilter, precomputedDepIds?: symbol[]) => readonly Entity[]
getQueryCacheStats: () => QueryCacheStats
getRemovedEntitiesSince: (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 | null
getWorldTick: () => number
getWorldVersion: () => number
@@ -8669,6 +8754,11 @@ TransformData
AiRegistry<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
```
TextInputPlugin
diff --git a/sdk/src/asset/AssetRefCounter.ts b/sdk/src/asset/AssetRefCounter.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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;