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: pre-resolve storage maps and getters for query hot paths

esengine84c5fe19b8ea
diff --git a/sdk/benchmarks/query-cache-miss.bench.ts b/sdk/benchmarks/query-cache-miss.bench.ts
new file mode 100644
index 000000000..dcf0b4f2b
--- /dev/null
+++ b/sdk/benchmarks/query-cache-miss.bench.ts
@@ -0,0 +1,105 @@
+import { describe, bench } from 'vitest';
+import { World } from '../src/world';
+import { defineComponent } from '../src/component';
+
+const A = defineComponent('CMA', { v: 0 });
+const B = defineComponent('CMB', { v: 0 });
+const C = defineComponent('CMC', { v: 0 });
+const D = defineComponent('CMD', { v: 0 });
+
+function makeWorld(n: number) {
+ const world = new World();
+ for (let i = 0; i < n; i++) {
+ const e = world.spawn();
+ world.insert(e, A, { v: i });
+ if (i % 2 === 0) world.insert(e, B, { v: i });
+ if (i % 3 === 0) world.insert(e, C, { v: i });
+ if (i % 5 === 0) world.insert(e, D, { v: i });
+ }
+ return world;
+}
+
+describe('Query cache miss - isolate query cost (2000 entities)', () => {
+ const world = makeWorld(2000);
+
+ bench('cache hit (baseline)', () => {
+ world.getEntitiesWithComponents([A], [], []);
+ });
+
+ bench('cache miss: 1 comp (force version bump)', () => {
+ (world as any).worldVersion_++;
+ world.getEntitiesWithComponents([A], [], []);
+ });
+
+ bench('cache miss: 2 comp', () => {
+ (world as any).worldVersion_++;
+ world.getEntitiesWithComponents([A, B], [], []);
+ });
+
+ bench('cache miss: 2 comp + without filter', () => {
+ (world as any).worldVersion_++;
+ world.getEntitiesWithComponents([A, B], [], [C]);
+ });
+
+ bench('cache miss: 3 comp', () => {
+ (world as any).worldVersion_++;
+ world.getEntitiesWithComponents([A, B, C], [], []);
+ });
+});
+
+describe('Query cache miss - scale by entity count', () => {
+ const w500 = makeWorld(500);
+ const w2000 = makeWorld(2000);
+ const w5000 = makeWorld(5000);
+ const w10000 = makeWorld(10000);
+
+ bench('500 entities, 2 comp miss', () => {
+ (w500 as any).worldVersion_++;
+ w500.getEntitiesWithComponents([A, B], [], []);
+ });
+
+ bench('2000 entities, 2 comp miss', () => {
+ (w2000 as any).worldVersion_++;
+ w2000.getEntitiesWithComponents([A, B], [], []);
+ });
+
+ bench('5000 entities, 2 comp miss', () => {
+ (w5000 as any).worldVersion_++;
+ w5000.getEntitiesWithComponents([A, B], [], []);
+ });
+
+ bench('10000 entities, 2 comp miss', () => {
+ (w10000 as any).worldVersion_++;
+ w10000.getEntitiesWithComponents([A, B], [], []);
+ });
+});
+
+describe('Query cache miss - has() breakdown', () => {
+ const world = makeWorld(2000);
+ const entities: number[] = [];
+ for (const [e] of (world as any).entities_) entities.push(e);
+ const storage = (world as any).tsStorage_.get(A._id) as Map<number, unknown>;
+
+ bench('Map.has() x2000 (direct storage)', () => {
+ for (let i = 0; i < entities.length; i++) {
+ storage.has(entities[i] as any);
+ }
+ });
+
+ bench('world.has() x2000 (through dispatch)', () => {
+ for (let i = 0; i < entities.length; i++) {
+ world.has(entities[i] as any, A);
+ }
+ });
+
+ bench('entities.slice() x2000', () => {
+ entities.slice();
+ });
+
+ bench('Array.push x2000', () => {
+ const arr: number[] = [];
+ for (let i = 0; i < entities.length; i++) {
+ arr.push(entities[i]);
+ }
+ });
+});
diff --git a/sdk/benchmarks/system.bench.ts b/sdk/benchmarks/system.bench.ts
new file mode 100644
index 000000000..91913fbcc
--- /dev/null
+++ b/sdk/benchmarks/system.bench.ts
@@ -0,0 +1,211 @@
+import { describe, bench } from 'vitest';
+import { World } from '../src/world';
+import { defineComponent } from '../src/component';
+import { defineSystem, SystemRunner, Schedule } from '../src/system';
+import { ResourceStorage } from '../src/resource';
+import { EventRegistry } from '../src/event';
+import { Query, Mut } from '../src/query';
+import { Commands } from '../src/commands';
+import { Res, defineResource, ResMut } from '../src/resource';
+import { EventWriter, EventReader, defineEvent } from '../src/event';
+
+const Position = defineComponent('BenchSysPos', { x: 0, y: 0 });
+const Velocity = defineComponent('BenchSysVel', { dx: 0, dy: 0 });
+const TimeRes = defineResource({ delta: 0.016, elapsed: 0, frameCount: 0 }, 'BenchTime');
+const HitEvent = defineEvent<{ entity: number; x: number; y: number }>('BenchHitEvent');
+
+describe('System - Dispatch overhead (empty system)', () => {
+ const world = new World();
+ const resources = new ResourceStorage();
+ const events = new EventRegistry();
+ const runner = new SystemRunner(world, resources, events);
+
+ const emptySystem = defineSystem([], () => {});
+ const querySystem = defineSystem([Query(Position)], () => {});
+ const multiParamSystem = defineSystem(
+ [Query(Position, Velocity), Res(TimeRes), Commands()],
+ () => {}
+ );
+
+ bench('0 params', () => {
+ runner.run(emptySystem);
+ });
+
+ bench('1 param (Query)', () => {
+ runner.run(querySystem);
+ });
+
+ bench('3 params (Query + Res + Commands)', () => {
+ runner.run(multiParamSystem);
+ });
+});
+
+describe('System - Dispatch with iteration (1000 entities)', () => {
+ const world = new World();
+ const resources = new ResourceStorage();
+ const events = new EventRegistry();
+ const runner = new SystemRunner(world, resources, events);
+
+ for (let i = 0; i < 1000; i++) {
+ const e = world.spawn();
+ world.insert(e, Position, { x: i, y: i });
+ world.insert(e, Velocity, { dx: 1, dy: 1 });
+ }
+
+ const iterSystem = defineSystem(
+ [Query(Position, Velocity)],
+ (query) => { for (const _ of query) {} }
+ );
+
+ const mutSystem = defineSystem(
+ [Query(Mut(Position), Velocity)],
+ (query) => {
+ for (const [, pos, vel] of query) {
+ pos.x += vel.dx;
+ pos.y += vel.dy;
+ }
+ }
+ );
+
+ const forEachSystem = defineSystem(
+ [Query(Position, Velocity)],
+ (query) => { query.forEach(() => {}); }
+ );
+
+ bench('for-of iteration', () => {
+ runner.run(iterSystem);
+ });
+
+ bench('Mut query iteration', () => {
+ runner.run(mutSystem);
+ });
+
+ bench('forEach iteration', () => {
+ runner.run(forEachSystem);
+ });
+});
+
+describe('System - Resource resolution', () => {
+ const world = new World();
+ const resources = new ResourceStorage();
+ const events = new EventRegistry();
+ const runner = new SystemRunner(world, resources, events);
+ resources.insert(TimeRes, { delta: 0.016, elapsed: 0, frameCount: 0 });
+
+ const resSystem = defineSystem([Res(TimeRes)], () => {});
+ const resMutSystem = defineSystem([ResMut(TimeRes)], () => {});
+
+ bench('Res (readonly)', () => {
+ runner.run(resSystem);
+ });
+
+ bench('ResMut', () => {
+ runner.run(resMutSystem);
+ });
+});
+
+describe('System - Event params', () => {
+ const world = new World();
+ const resources = new ResourceStorage();
+ const events = new EventRegistry();
+ const runner = new SystemRunner(world, resources, events);
+
+ const writerSystem = defineSystem([EventWriter(HitEvent)], () => {});
+ const readerSystem = defineSystem([EventReader(HitEvent)], () => {});
+ const bothSystem = defineSystem(
+ [EventWriter(HitEvent), EventReader(HitEvent)],
+ () => {}
+ );
+
+ bench('EventWriter', () => {
+ runner.run(writerSystem);
+ });
+
+ bench('EventReader', () => {
+ runner.run(readerSystem);
+ });
+
+ bench('Writer + Reader', () => {
+ runner.run(bothSystem);
+ });
+});
+
+describe('System - Commands spawn+flush', () => {
+ const world = new World();
+ const resources = new ResourceStorage();
+ const events = new EventRegistry();
+ const runner = new SystemRunner(world, resources, events);
+
+ const spawnFlushSystem = defineSystem([Commands()], (cmds) => {
+ for (let i = 0; i < 10; i++) {
+ cmds.spawn().insert(Position, { x: i, y: i });
+ }
+ });
+
+ bench('spawn 10 + flush', () => {
+ runner.run(spawnFlushSystem);
+ });
+});
+
+describe('System - Commands despawn+flush (100 entities)', () => {
+ const world2 = new World();
+ const resources2 = new ResourceStorage();
+ const events2 = new EventRegistry();
+ const runner2 = new SystemRunner(world2, resources2, events2);
+
+ const despawnFlushSystem = defineSystem([Query(Position), Commands()], (query, cmds) => {
+ let count = 0;
+ for (const [entity] of query) {
+ cmds.despawn(entity);
+ if (++count >= 10) break;
+ }
+ });
+
+ const refillSystem = defineSystem([Commands()], (cmds) => {
+ for (let i = 0; i < 10; i++) {
+ cmds.spawn().insert(Position, { x: i, y: i });
+ }
+ });
+
+ for (let i = 0; i < 100; i++) {
+ const e = world2.spawn();
+ world2.insert(e, Position, { x: i, y: i });
+ }
+
+ bench('despawn 10 + flush (from 100)', () => {
+ runner2.run(despawnFlushSystem);
+ runner2.run(refillSystem);
+ });
+});
+
+describe('System - Full frame simulation (10 systems)', () => {
+ const world = new World();
+ const resources = new ResourceStorage();
+ const events = new EventRegistry();
+ const runner = new SystemRunner(world, resources, events);
+ resources.insert(TimeRes, { delta: 0.016, elapsed: 0, frameCount: 0 });
+
+ for (let i = 0; i < 500; i++) {
+ const e = world.spawn();
+ world.insert(e, Position, { x: i, y: i });
+ world.insert(e, Velocity, { dx: 1, dy: 1 });
+ }
+
+ const systems: ReturnType<typeof defineSystem>[] = [];
+ for (let i = 0; i < 10; i++) {
+ systems.push(defineSystem(
+ [Query(Position, Velocity)],
+ (query) => { for (const _ of query) {} }
+ ));
+ }
+
+ bench('run 10 systems', () => {
+ events.swapAll();
+ world.advanceTick();
+ world.resetQueryPool();
+ for (const sys of systems) {
+ runner.run(sys);
+ }
+ world.cleanRemovedBuffer(2);
+ });
+});
diff --git a/sdk/benchmarks/world-internals.bench.ts b/sdk/benchmarks/world-internals.bench.ts
new file mode 100644
index 000000000..076e0fc4b
--- /dev/null
+++ b/sdk/benchmarks/world-internals.bench.ts
@@ -0,0 +1,141 @@
+import { describe, bench } from 'vitest';
+import { World } from '../src/world';
+import { defineComponent } from '../src/component';
+
+const Position = defineComponent('BenchWIPos', { x: 0, y: 0 });
+const Velocity = defineComponent('BenchWIVel', { dx: 0, dy: 0 });
+const Health = defineComponent('BenchWIHp', { value: 100 });
+
+describe('World internals - valid() check', () => {
+ const world = new World();
+ const entities: number[] = [];
+ for (let i = 0; i < 1000; i++) {
+ entities.push(world.spawn());
+ }
+ const invalidEntity = 99999;
+
+ bench('valid (existing) x1000', () => {
+ for (let i = 0; i < 1000; i++) {
+ world.valid(entities[i] as any);
+ }
+ });
+
+ bench('valid (non-existing) x1000', () => {
+ for (let i = 0; i < 1000; i++) {
+ world.valid(invalidEntity as any);
+ }
+ });
+});
+
+describe('World internals - per-frame operations', () => {
+ const world = new World();
+ for (let i = 0; i < 500; i++) {
+ const e = world.spawn();
+ world.insert(e, Position, { x: i, y: i });
+ }
+
+ bench('advanceTick', () => {
+ world.advanceTick();
+ });
+
+ bench('resetQueryPool', () => {
+ world.resetQueryPool();
+ });
+
+ bench('cleanRemovedBuffer (nothing to clean)', () => {
+ world.cleanRemovedBuffer(2);
+ });
+});
+
+describe('World internals - getEntitiesWithComponents (cache behavior)', () => {
+ const world = new World();
+ for (let i = 0; i < 2000; i++) {
+ const e = world.spawn();
+ world.insert(e, Position, { x: i, y: i });
+ if (i % 2 === 0) world.insert(e, Velocity, { dx: 1, dy: 1 });
+ if (i % 3 === 0) world.insert(e, Health, { value: 100 });
+ }
+
+ bench('1 comp cache hit x100', () => {
+ for (let i = 0; i < 100; i++) {
+ world.getEntitiesWithComponents([Position], [], []);
+ }
+ });
+
+ bench('2 comp cache hit x100', () => {
+ for (let i = 0; i < 100; i++) {
+ world.getEntitiesWithComponents([Position, Velocity], [], []);
+ }
+ });
+
+ bench('with + without filter cache hit x100', () => {
+ for (let i = 0; i < 100; i++) {
+ world.getEntitiesWithComponents([Position], [Velocity], [Health]);
+ }
+ });
+
+ bench('cache miss (after version bump) x100', () => {
+ for (let i = 0; i < 100; i++) {
+ const e = world.spawn();
+ world.insert(e, Position, { x: 0, y: 0 });
+ world.getEntitiesWithComponents([Position], [], []);
+ world.despawn(e);
+ }
+ });
+});
+
+describe('World internals - insert + remove cycle (script components)', () => {
+ const world = new World();
+ const entities: number[] = [];
+ for (let i = 0; i < 200; i++) {
+ entities.push(world.spawn());
+ }
+
+ bench('insert + remove x200', () => {
+ for (let i = 0; i < 200; i++) {
+ world.insert(entities[i] as any, Position, { x: i, y: i });
+ }
+ for (let i = 0; i < 200; i++) {
+ world.remove(entities[i] as any, Position);
+ }
+ });
+});
+
+describe('World internals - entityComponents tracking', () => {
+ const world = new World();
+ const entities: number[] = [];
+ for (let i = 0; i < 500; i++) {
+ const e = world.spawn();
+ entities.push(e);
+ world.insert(e as any, Position, { x: 0, y: 0 });
+ world.insert(e as any, Velocity, { dx: 0, dy: 0 });
+ world.insert(e as any, Health, { value: 100 });
+ }
+
+ bench('has x1000 (3 comp entities)', () => {
+ for (let i = 0; i < 500; i++) {
+ world.has(entities[i] as any, Position);
+ world.has(entities[i] as any, Health);
+ }
+ });
+
+ bench('get x1000 (3 comp entities)', () => {
+ for (let i = 0; i < 500; i++) {
+ world.get(entities[i] as any, Position);
+ world.get(entities[i] as any, Velocity);
+ }
+ });
+});
+
+describe('World internals - spawn + despawn throughput', () => {
+ const world = new World();
+
+ bench('spawn+insert+despawn x100', () => {
+ for (let i = 0; i < 100; i++) {
+ const e = world.spawn();
+ world.insert(e, Position, { x: i, y: i });
+ world.insert(e, Velocity, { dx: 1, dy: 1 });
+ world.despawn(e);
+ }
+ });
+});
diff --git a/sdk/src/query.ts b/sdk/src/query.ts
index 9a1096330..1e75cea23 100644
--- a/sdk/src/query.ts
+++ b/sdk/src/query.ts
@@ -168,6 +168,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
private readonly mutData_: Array<{ component: AnyComponentDef; data: Record<string, unknown> }>;
private readonly cacheKey_: string;
private readonly lastRunTick_: number;
+ private readonly getters_: Array<((entity: Entity) => unknown) | null>;
constructor(world: World, descriptor: QueryDescriptor<C>, lastRunTick = -1) {
this.world_ = world;
@@ -185,6 +186,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
descriptor._with,
descriptor._without,
);
+ this.getters_ = this.actualComponents_.map(comp => world.resolveGetter(comp));
for (const f of descriptor._addedFilters) {
world.enableChangeTracking(f.component);
}
@@ -222,6 +224,7 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
const mutData = this.mutData_;
const mutCount = mutData.length;
const world = this.world_;
+ const getters = this.getters_;
const self = this;
let idx = 0;
@@ -264,7 +267,8 @@ export class QueryInstance<C extends readonly QueryArg[]> implements Iterable<Qu
result[0] = entity;
for (let i = 0; i < compCount; i++) {
- result[i + 1] = world.get(entity, actualComponents[i]);
+ const getter = getters[i];
+ result[i + 1] = getter ? getter(entity) : world.get(entity, actualComponents[i]);
}
if (hasMut) {
diff --git a/sdk/src/world.ts b/sdk/src/world.ts
index aba76d81c..ced0a325b 100644
--- a/sdk/src/world.ts
+++ b/sdk/src/world.ts
@@ -569,6 +569,22 @@ export class World {
return storage;
}
+ /** @internal Pre-resolve a component to its direct storage/getter for fast iteration. */
+ resolveGetter(component: AnyComponentDef): ((entity: Entity) => unknown) | null {
+ if (isBuiltinComponent(component)) {
+ if (!this.cppRegistry_) return null;
+ const methods = this.getBuiltinMethods(component._cppName);
+ const colorKeys = component._colorKeys;
+ if (colorKeys.length === 0) {
+ return (e) => methods.get(e);
+ }
+ return (e) => convertFromWasm(methods.get(e) as Record<string, unknown>, colorKeys);
+ }
+ const storage = this.tsStorage_.get(component._id);
+ if (!storage) return null;
+ return (e) => storage.get(e);
+ }
+
// =========================================================================
// Query Support
// =========================================================================
@@ -607,6 +623,24 @@ export class World {
return Array.from(types);
}
+ private resolveStorages_(
+ comps: AnyComponentDef[],
+ scriptOut: Map<Entity, unknown>[],
+ builtinOut: BuiltinMethods[],
+ ): boolean {
+ for (const comp of comps) {
+ if (isBuiltinComponent(comp)) {
+ if (!this.cppRegistry_) return false;
+ builtinOut.push(this.getBuiltinMethods(comp._cppName));
+ } else {
+ const storage = this.tsStorage_.get(comp._id);
+ if (!storage) return false;
+ scriptOut.push(storage);
+ }
+ }
+ return true;
+ }
+
getEntitiesWithComponents(
components: AnyComponentDef[],
withFilters: AnyComponentDef[] = [],
@@ -623,49 +657,79 @@ export class World {
return cached.result;
}
- let smallestPool: Map<Entity, unknown> | null = null;
- let smallestSize = Infinity;
-
- for (const comp of components) {
- if (!isBuiltinComponent(comp)) {
- const storage = this.tsStorage_.get(comp._id);
- const size = storage ? storage.size : 0;
- if (size < smallestSize) {
- smallestSize = size;
- smallestPool = storage ?? null;
- }
- }
- }
-
if (this.queryPoolIdx_ >= this.queryPool_.length) {
this.queryPool_.push([]);
}
const entities = this.queryPool_[this.queryPoolIdx_++];
entities.length = 0;
+ const reqScript: Map<Entity, unknown>[] = [];
+ const reqBuiltin: BuiltinMethods[] = [];
+ if (!this.resolveStorages_(components, reqScript, reqBuiltin)) {
+ this.queryCache_.set(cacheKey, { version: this.worldVersion_, result: [] });
+ return entities;
+ }
+
+ let withScript: Map<Entity, unknown>[] | null = null;
+ let withBuiltin: BuiltinMethods[] | null = null;
+ if (withFilters.length > 0) {
+ withScript = [];
+ withBuiltin = [];
+ if (!this.resolveStorages_(withFilters, withScript, withBuiltin)) {
+ this.queryCache_.set(cacheKey, { version: this.worldVersion_, result: [] });
+ return entities;
+ }
+ }
+
+ let woScript: Map<Entity, unknown>[] | null = null;
+ let woBuiltin: BuiltinMethods[] | null = null;
+ if (withoutFilters.length > 0) {
+ woScript = [];
+ woBuiltin = [];
+ this.resolveStorages_(withoutFilters, woScript, woBuiltin);
+ }
+
+ let smallestPool: Map<Entity, unknown> | null = null;
+ let smallestSize = Infinity;
+ for (let i = 0; i < reqScript.length; i++) {
+ const size = reqScript[i].size;
+ if (size < smallestSize) {
+ smallestSize = size;
+ smallestPool = reqScript[i];
+ }
+ }
+
const candidates = smallestPool ? smallestPool.keys() : this.entities_.keys();
+ const rsLen = reqScript.length;
+ const rbLen = reqBuiltin.length;
for (const entity of candidates) {
let match = true;
- for (const comp of components) {
- if (!this.has(entity, comp)) {
- match = false;
- break;
- }
+ for (let i = 0; i < rsLen; i++) {
+ if (!reqScript[i].has(entity)) { match = false; break; }
}
if (match) {
- for (const comp of withFilters) {
- if (!this.has(entity, comp)) {
- match = false;
- break;
+ for (let i = 0; i < rbLen; i++) {
+ if (!reqBuiltin[i].has(entity)) { match = false; break; }
+ }
+ }
+ if (match && withScript) {
+ for (let i = 0; i < withScript.length; i++) {
+ if (!withScript[i].has(entity)) { match = false; break; }
+ }
+ if (match) {
+ for (let i = 0; i < withBuiltin!.length; i++) {
+ if (!withBuiltin![i].has(entity)) { match = false; break; }
}
}
}
- if (match) {
- for (const comp of withoutFilters) {
- if (this.has(entity, comp)) {
- match = false;
- break;
+ if (match && woScript) {
+ for (let i = 0; i < woScript.length; i++) {
+ if (woScript[i].has(entity)) { match = false; break; }
+ }
+ if (match) {
+ for (let i = 0; i < woBuiltin!.length; i++) {
+ if (woBuiltin![i].has(entity)) { match = false; break; }
}
}
}
diff --git a/sdk/tests/system.test.ts b/sdk/tests/system.test.ts
index 8b1525a68..4d4464d7f 100644
--- a/sdk/tests/system.test.ts
+++ b/sdk/tests/system.test.ts
@@ -57,6 +57,7 @@ function createMockWorld() {
isChangedSince: vi.fn(() => false),
getRemovedEntitiesSince: vi.fn(() => []),
enableChangeTracking: vi.fn(),
+ resolveGetter: vi.fn(() => null),
};
return { world: world as unknown as World, entities, worldTick };