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.

perf(inspector): index script names once per runtime tree snapshot

yhh5a82bb5b8f7e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 35aa4c75d..f73d524b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Runtime tree inspection indexes script component names once per snapshot.** Large script catalogues no longer require a name search for every component on every entity. The index is rebuilt for each group read, so registration, removal, aliases and context changes remain visible; builtin membership is still read from the current core.
+
- **Selected runtime details reuse maintained hierarchy links.** Refreshing one entity reads its own parent and children instead of scanning every entity's parent. Child ordering still follows world storage, including after reparenting and draw-order edits; disabled children remain inspectable and native reparenting is read from the current core.
- **Runtime inspectors clear destroyed entity selections.** A selected entity that despawns now returns no detail row instead of an empty ghost entity, including when its native slot is reused. Requests without a live selection or tree avoid traversing the world; disabled live entities remain inspectable.
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 025d77751..36098d518 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -9852,6 +9852,7 @@ tabIndex: number | undefined
@internal enableChangeTracking: (component: AnyComponentDef) => void
@internal endIteration: () => void
@internal ensureTransformsComposed: () => void
+@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]
@internal getCppRegistry: () => CppRegistry | null
@internal getQueryCacheStats: () => QueryCacheStats
@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 7aefafee4..2ba6eab2a 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -10057,6 +10057,7 @@ tabIndex: number | undefined
@internal enableChangeTracking: (component: AnyComponentDef) => void
@internal endIteration: () => void
@internal ensureTransformsComposed: () => void
+@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]
@internal getCppRegistry: () => CppRegistry | null
@internal getQueryCacheStats: () => QueryCacheStats
@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 04991764c..85b2352a6 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -9847,6 +9847,7 @@ tabIndex: number | undefined
@internal enableChangeTracking: (component: AnyComponentDef) => void
@internal endIteration: () => void
@internal ensureTransformsComposed: () => void
+@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]
@internal getCppRegistry: () => CppRegistry | null
@internal getQueryCacheStats: () => QueryCacheStats
@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 5508cd6e4..47cbf7682 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -10134,6 +10134,7 @@ tabIndex: number | undefined
@internal enableChangeTracking: (component: AnyComponentDef) => void
@internal endIteration: () => void
@internal ensureTransformsComposed: () => void
+@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]
@internal getCppRegistry: () => CppRegistry | null
@internal getQueryCacheStats: () => QueryCacheStats
@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d74413195..50ef1424c 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -9878,6 +9878,7 @@ tabIndex: number | undefined
@internal enableChangeTracking: (component: AnyComponentDef) => void
@internal endIteration: () => void
@internal ensureTransformsComposed: () => void
+@internal getComponentTypesBatch: (entities: readonly Entity[]) => string[][]
@internal getCppRegistry: () => CppRegistry | null
@internal getQueryCacheStats: () => QueryCacheStats
@internal getRemovedEntitiesSince: (component: AnyComponentDef, sinceTick: number) => Entity[]
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index a409bdc6e..46d69ec53 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -1086,6 +1086,21 @@ export class World {
/** The names of every component on `entity` — for inspectors and diagnostics;
* a system asks {@link has} about the definitions it knows. */
getComponentTypes(entity: Entity): string[] {
+ return this.componentTypes_(entity);
+ }
+
+ /** @internal Inspect a group with one script catalogue index, preserving input order. */
+ getComponentTypesBatch(entities: readonly Entity[]): string[][] {
+ if (entities.length === 0) return [];
+ const scriptNames = new Map<symbol, string>();
+ for (const [name, def] of getUserComponents()) {
+ // Match the scalar lookup's first registered name for an id.
+ if (!scriptNames.has(def._id)) scriptNames.set(def._id, name);
+ }
+ return entities.map(entity => this.componentTypes_(entity, scriptNames));
+ }
+
+ private componentTypes_(entity: Entity, scriptNames?: ReadonlyMap<symbol, string>): string[] {
const names = this.builtin_.componentNames(entity);
const types = new Set<string>(names ?? []);
const methods = this.builtin_.getMethodCache();
@@ -1104,9 +1119,14 @@ export class World {
}
const ids = this.scripts_.getEntityComponentIds(entity);
if (ids) {
- const registry = getUserComponents();
+ const registry = scriptNames ? null : getUserComponents();
for (const id of ids) {
- for (const [name, def] of registry) {
+ if (scriptNames) {
+ const name = scriptNames.get(id);
+ if (name !== undefined) types.add(name);
+ continue;
+ }
+ for (const [name, def] of registry!) {
if (def._id === id) {
types.add(name);
break;
diff --git a/sdk/src/runtime/worldSnapshot.ts b/sdk/src/runtime/worldSnapshot.ts
index b7e1575dd..2b2f36c20 100644
--- a/sdk/src/runtime/worldSnapshot.ts
+++ b/sdk/src/runtime/worldSnapshot.ts
@@ -165,12 +165,13 @@ export function worldSnapshot(
};
let selectedTypes: string[] | null = null;
+ const treeTypes = withTree ? world.getComponentTypesBatch(all) : null;
const tree = withTree
? {
version: '1.0' as const, name: 'live' as const,
- entities: all.map((e) => {
+ entities: all.map((e, index) => {
const id = e as never as number;
- const types = world.getComponentTypes(e);
+ const types = treeTypes![index];
if (id === selectedId) selectedTypes = types;
return shape(id, filterInspectableTypes(types).map((type) => ({ type, data: {} })), types);
}),
diff --git a/sdk/tests/component-inspection-batch.test.ts b/sdk/tests/component-inspection-batch.test.ts
new file mode 100644
index 000000000..a78dbe638
--- /dev/null
+++ b/sdk/tests/component-inspection-batch.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import { World } from '../src/ecs/world';
+import { AppContext, getDefaultContext, setDefaultContext } from '../src/ecs/context';
+import { defineComponent, getUserComponents, unregisterComponent } from '../src/ecs/component';
+
+function isolated(run: (context: AppContext, world: World) => void) {
+ const previous = getDefaultContext(), context = new AppContext();
+ setDefaultContext(context);
+ try { run(context, new World()); }
+ finally { setDefaultContext(previous); }
+}
+
+describe('group component inspection', () => {
+ it('matches scalar ordering and builds the script index once for a large group', () => isolated((_context, world) => {
+ for (let i = 0; i < 200; i++) defineComponent('Unused' + i, { value: 0 });
+ const a = defineComponent('GroupFirst', { value: 1 }), b = defineComponent('GroupSecond', { value: 2 });
+ const entities = Array.from({ length: 100 }, () => world.spawn());
+ for (const entity of entities) { world.insert(entity, b); world.insert(entity, a); }
+ const input = [entities[1], entities[0], ...entities];
+ const expected = input.map(entity => world.getComponentTypes(entity));
+ const iterator = vi.spyOn(getUserComponents(), Symbol.iterator);
+ expect(world.getComponentTypesBatch(input)).toEqual(expected);
+ expect(iterator).toHaveBeenCalledTimes(1);
+ iterator.mockRestore();
+ world.remove(entities[0], b);
+ expect(world.getComponentTypesBatch(input)).toEqual(input.map(entity => world.getComponentTypes(entity)));
+ world.despawn(entities[1]);
+ expect(world.getComponentTypesBatch(input)).toEqual(input.map(entity => world.getComponentTypes(entity)));
+ expect(world.getComponentTypesBatch([])).toEqual([]);
+ }));
+
+ it('follows aliases, same-size catalogue edits and replacement registrations', () => isolated((context, world) => {
+ const component = defineComponent('Original', { value: 1 }), entity = world.spawn();
+ world.insert(entity, component);
+ context.componentRegistry.set('Alias', component);
+ expect(world.getComponentTypesBatch([entity])).toEqual([['Original']]);
+ unregisterComponent('Original');
+ expect(world.getComponentTypesBatch([entity])).toEqual([world.getComponentTypes(entity)]);
+ expect(world.getComponentTypesBatch([entity])).toEqual([['Alias']]);
+ context.componentRegistry.delete('Alias');
+ context.componentRegistry.set('Renamed', component);
+ expect(world.getComponentTypesBatch([entity])).toEqual([['Renamed']]);
+ context.componentRegistry.clear();
+ const replacement = defineComponent('Renamed', { value: 2 });
+ expect(world.getComponentTypesBatch([entity])).toEqual([[]]);
+ world.insert(entity, replacement);
+ expect(world.getComponentTypesBatch([entity])).toEqual([world.getComponentTypes(entity)]);
+ expect(world.getComponentTypesBatch([entity])).toEqual([['Renamed']]);
+ }));
+
+ it('uses the current context on every group read', () => isolated((_context, world) => {
+ const component = defineComponent('ContextComponent', { value: 0 }), entity = world.spawn();
+ world.insert(entity, component);
+ expect(world.getComponentTypesBatch([entity])).toEqual([['ContextComponent']]);
+ const previous = getDefaultContext();
+ setDefaultContext(new AppContext());
+ try {
+ expect(world.getComponentTypesBatch([entity])).toEqual([[]]);
+ defineComponent('DifferentContextComponent', { value: 0 });
+ expect(world.getComponentTypesBatch([entity])).toEqual([[]]);
+ defineComponent('ContextComponent', { value: 0 });
+ expect(world.getComponentTypesBatch([entity])).toEqual([world.getComponentTypes(entity)]);
+ expect(world.getComponentTypesBatch([entity])).toEqual([['ContextComponent']]);
+ } finally { setDefaultContext(previous); }
+ expect(world.getComponentTypesBatch([entity])).toEqual([['ContextComponent']]);
+ }));
+});
diff --git a/sdk/tests/component-inspection-wasm.test.ts b/sdk/tests/component-inspection-wasm.test.ts
index 28c1245a4..0cf0ebd99 100644
--- a/sdk/tests/component-inspection-wasm.test.ts
+++ b/sdk/tests/component-inspection-wasm.test.ts
@@ -21,14 +21,17 @@ describe.skipIf(!HAS_WASM)('bulk builtin inspection on the core', () => {
world.insert(entity, script);
world.insert(entity, Disabled);
const bulk = world.getComponentTypes(entity);
+ expect(world.getComponentTypesBatch([entity, entity])).toEqual([bulk, bulk]);
expect(bulk).toEqual(expect.arrayContaining(['Name', 'Transform', 'Sprite', 'Disabled', 'BulkInspectionScript']));
const read = registry.getBuiltinComponentNames!;
registry.getBuiltinComponentNames = undefined;
const legacy = world.getComponentTypes(entity);
+ expect(world.getComponentTypesBatch([entity])).toEqual([legacy]);
registry.getBuiltinComponentNames = read;
expect(bulk).toEqual(legacy);
registry.removeSprite(entity);
expect(world.getComponentTypes(entity)).not.toContain('Sprite');
+ expect(world.getComponentTypesBatch([entity])).toEqual([world.getComponentTypes(entity)]);
world.remove(entity, script);
expect(world.getComponentTypes(entity)).not.toContain('BulkInspectionScript');
world.despawn(entity);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 5342eec96..43f05a470 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(inspector): index script names once per runtime tree snapshot':
+ { note: 'Runtime tree inspection indexes script component names once per snapshot.' },
'perf(inspector): reuse hierarchy links for selected runtime details':
{ note: 'Selected runtime details reuse maintained hierarchy links.' },
'fix(inspector): clear destroyed runtime entity selections':