A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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<Quprivate 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<Qudescriptor._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<Quconst 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<Quresult[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.tsindex 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.tsindex 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 };