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(ecs): zero-alloc color conversion, WASM ptr bounds check, QueryCache stats
esengine870e260f75ec
diff --git a/sdk/src/ecs/BuiltinBridge.ts b/sdk/src/ecs/BuiltinBridge.tsindex ff131b03b..bcce66eaa 100644--- a/sdk/src/ecs/BuiltinBridge.ts+++ b/sdk/src/ecs/BuiltinBridge.ts@@ -16,34 +16,50 @@ import { PTR_ACCESSORS } from './ptrAccessors.generated';// Color conversion helpers// =============================================================================+/**+ * Rewrite color-typed fields from the WASM {x,y,z,w} shape into the SDK+ * {r,g,b,a} shape. The outer object comes fresh from embind on every+ * Registry method call and has no outside aliases, so we mutate it in+ * place; the inner color objects are likewise fresh. Setting r/g/b/a+ * on the same object leaves ghost x/y/z/w properties, but consumers+ * only read r/g/b/a — net zero allocations per get().+ */export function convertFromWasm(obj: Record<string, unknown>,colorKeys: readonly string[],): Record<string, unknown> {if (colorKeys.length === 0) return obj;- const result: Record<string, unknown> = { ...obj };for (const key of colorKeys) {- const val = result[key] as Record<string, unknown> | null | undefined;+ const val = obj[key] as { x?: number; y?: number; z?: number; w?: number } & Record<string, unknown> | null | undefined;if (val && typeof val === 'object') {- result[key] = { r: val.x, g: val.y, b: val.z, a: val.w };+ (val as { r: unknown }).r = val.x;+ (val as { g: unknown }).g = val.y;+ (val as { b: unknown }).b = val.z;+ (val as { a: unknown }).a = val.w;}}- return result;+ return obj;}+/**+ * Rewrite color-typed fields from the SDK {r,g,b,a} shape into the WASM+ * {x,y,z,w} shape. The outer object is always a fresh merge constructed+ * by the caller, but inner color values may alias user-supplied data or+ * the shared component defaults, so we replace those slots with fresh+ * {x,y,z,w} objects rather than mutating them.+ */export function convertForWasm(obj: Record<string, unknown>,colorKeys: readonly string[],): Record<string, unknown> {if (colorKeys.length === 0) return obj;- const result: Record<string, unknown> = { ...obj };for (const key of colorKeys) {- const val = result[key] as Record<string, unknown> | null | undefined;+ const val = obj[key] as { r?: number; g?: number; b?: number; a?: number } | null | undefined;if (val && typeof val === 'object') {- result[key] = { x: val.r, y: val.g, z: val.b, w: val.a };+ obj[key] = { x: val.r, y: val.g, z: val.b, w: val.a };}}- return result;+ return obj;}// =============================================================================@@ -58,11 +74,31 @@ interface PtrFieldDesc {readonly offset: number;}+function fieldByteSize(type: PtrFieldType): number {+ switch (type) {+ case 'f32': case 'i32': case 'u32': return 4;+ case 'bool': case 'u8': return 1;+ case 'vec2': return 8;+ case 'vec3': return 12;+ case 'vec4': case 'quat': case 'color': return 16;+ }+}++function assertPtrInBounds(heapByteLength: number, byteOff: number, size: number): void {+ if (byteOff < 0 || byteOff + size > heapByteLength) {+ throw new RangeError(+ `WASM pointer field access out of bounds: offset ${String(byteOff)} + size ${String(size)} ` ++ `exceeds heap byteLength ${String(heapByteLength)} (typed-array detached, or C++ returned a stale pointer)`,+ );+ }+}+export function readPtrField(f32: Float32Array, u32: Uint32Array, u8: Uint8Array,ptr: number, field: PtrFieldDesc,): unknown {const byteOff = ptr + field.offset;+ assertPtrInBounds(u8.byteLength, byteOff, fieldByteSize(field.type));const idx = byteOff >> 2;switch (field.type) {case 'f32': return f32[idx];@@ -87,6 +123,16 @@ export function fillPtrFields(f32: Float32Array, u32: Uint32Array, u8: Uint8Array,ptr: number, fields: readonly PtrFieldDesc[], target: Record<string, unknown>,): void {+ // One bounds check for the whole struct: compute the maximum byte extent+ // across all fields and verify against the heap view once.+ let maxEnd = 0;+ for (let i = 0; i < fields.length; i++) {+ const f = fields[i];+ const end = f.offset + fieldByteSize(f.type);+ if (end > maxEnd) maxEnd = end;+ }+ if (maxEnd > 0) assertPtrInBounds(u8.byteLength, ptr, maxEnd);+for (let i = 0; i < fields.length; i++) {const field = fields[i];const byteOff = ptr + field.offset;@@ -144,6 +190,7 @@ export function writePtrField(ptr: number, field: PtrFieldDesc, value: PtrFieldValue | unknown,): void {const byteOff = ptr + field.offset;+ assertPtrInBounds(u8.byteLength, byteOff, fieldByteSize(field.type));const idx = byteOff >> 2;switch (field.type) {case 'f32': f32[idx] = value as number; break;diff --git a/sdk/src/ecs/QueryCache.ts b/sdk/src/ecs/QueryCache.tsindex 652c629d5..834eef74d 100644--- a/sdk/src/ecs/QueryCache.ts+++ b/sdk/src/ecs/QueryCache.ts@@ -11,11 +11,30 @@ interface CacheEntry {result: Entity[];}+/** Cumulative counters for query-cache activity (observability only). */+export interface QueryCacheStats {+ /** Lookups that returned a still-valid cached result. */+ readonly hits: number;+ /** Lookups that recomputed — either no entry or stale. */+ readonly misses: number;+ /** Times an entry was found but rejected because structural version moved. */+ readonly structuralInvalidations: number;+ /** Times an entry was rejected because one of its dep components changed. */+ readonly componentInvalidations: number;+ /** Current number of entries held. */+ readonly size: number;+}+export class QueryCache {private structuralVersion_ = 0;private componentVersions_ = new Map<symbol, number>();private cache_ = new Map<string, CacheEntry>();+ private hits_ = 0;+ private misses_ = 0;+ private structuralInvalidations_ = 0;+ private componentInvalidations_ = 0;+get structuralVersion(): number {return this.structuralVersion_;}@@ -39,9 +58,17 @@ export class QueryCache {computeFn: () => Entity[],): Entity[] {const cached = this.cache_.get(cacheKey);- if (cached && this.isValid_(cached, dependentComponentIds)) {- return cached.result;+ if (cached) {+ const validity = this.checkValidity_(cached, dependentComponentIds);+ if (validity === 0) {+ this.hits_++;+ return cached.result;+ }+ // 1 = structural, 2 = component — classify the miss for stats.+ if (validity === 1) this.structuralInvalidations_++;+ else this.componentInvalidations_++;}+ this.misses_++;const result = computeFn();@@ -58,13 +85,36 @@ export class QueryCache {return result;}- private isValid_(entry: CacheEntry, dependentComponentIds: symbol[]): boolean {- if (entry.structuralVersion !== this.structuralVersion_) return false;+ /** Snapshot of counters. Read-only; callers can diff across frames. */+ getStats(): QueryCacheStats {+ return {+ hits: this.hits_,+ misses: this.misses_,+ structuralInvalidations: this.structuralInvalidations_,+ componentInvalidations: this.componentInvalidations_,+ size: this.cache_.size,+ };+ }++ /** Reset counters without dropping cached entries. */+ resetStats(): void {+ this.hits_ = 0;+ this.misses_ = 0;+ this.structuralInvalidations_ = 0;+ this.componentInvalidations_ = 0;+ }++ /**+ * Returns 0 when the entry is still valid, 1 when structural version moved,+ * 2 when a dependent component changed.+ */+ private checkValidity_(entry: CacheEntry, dependentComponentIds: symbol[]): 0 | 1 | 2 {+ if (entry.structuralVersion !== this.structuralVersion_) return 1;for (const id of dependentComponentIds) {const current = this.componentVersions_.get(id) ?? 0;const cached = entry.componentVersions.get(id) ?? 0;- if (current !== cached) return false;+ if (current !== cached) return 2;}- return true;+ return 0;}}diff --git a/sdk/src/world.ts b/sdk/src/world.tsindex e6cb4cdea..2933e3000 100644--- a/sdk/src/world.ts+++ b/sdk/src/world.ts@@ -11,7 +11,7 @@ import { BuiltinBridge, convertFromWasm, convertForWasm, type BridgeConnectOptioimport { ScriptStorage } from './ecs/ScriptStorage';import { NameIndex } from './ecs/NameIndex';import { ChangeTracker } from './ecs/ChangeTracker';-import { QueryCache } from './ecs/QueryCache';+import { QueryCache, type QueryCacheStats } from './ecs/QueryCache';import { log } from './logger';export { PTR_LAYOUTS } from './ptrLayouts.generated';@@ -251,6 +251,16 @@ export class World {return this.queries_.structuralVersion;}+ /** Cumulative query-cache counters (hits, misses, invalidation causes). */+ getQueryCacheStats(): QueryCacheStats {+ return this.queries_.getStats();+ }++ /** Reset the query-cache counters. Entries themselves are kept. */+ resetQueryCacheStats(): void {+ this.queries_.resetStats();+ }+beginIteration(): void {this.iterationDepth_++;}diff --git a/sdk/tests/color-conversion.test.ts b/sdk/tests/color-conversion.test.tsnew file mode 100644index 000000000..5be6be07c--- /dev/null+++ b/sdk/tests/color-conversion.test.ts@@ -0,0 +1,81 @@+/**+ * @file color-conversion.test.ts+ * @brief convertFromWasm mutates in place; convertForWasm replaces color+ * slots without touching the caller's inner color objects.+ */+import { describe, expect, it } from 'vitest';+import { convertForWasm, convertFromWasm } from '../src/ecs/BuiltinBridge';++describe('convertFromWasm', () => {+ it('returns the same outer object (zero outer allocation)', () => {+ const src = { color: { x: 1, y: 0.5, z: 0.25, w: 0.1 } };+ const out = convertFromWasm(src as Record<string, unknown>, ['color']);+ expect(out).toBe(src);+ });++ it('writes r/g/b/a into the same color object (zero inner allocation)', () => {+ const color = { x: 0.1, y: 0.2, z: 0.3, w: 0.4 };+ const src = { color };+ const out = convertFromWasm(src as Record<string, unknown>, ['color']);+ // Same reference preserved — the caller's nested object was mutated in place.+ expect(out.color).toBe(color);+ // r/g/b/a are written alongside the original x/y/z/w (ghost keys are+ // intentional — consumers read r/g/b/a only, and leaving the xyzw+ // slots keeps the hidden class stable across calls).+ const c = out.color as { r: number; g: number; b: number; a: number };+ expect(c.r).toBeCloseTo(0.1);+ expect(c.g).toBeCloseTo(0.2);+ expect(c.b).toBeCloseTo(0.3);+ expect(c.a).toBeCloseTo(0.4);+ });++ it('is a no-op when there are no color keys', () => {+ const src = { x: 1, y: 2 };+ expect(convertFromWasm(src as Record<string, unknown>, [])).toBe(src);+ });++ it('skips color slots that are not objects', () => {+ const src = { color: null };+ const out = convertFromWasm(src as Record<string, unknown>, ['color']);+ expect(out.color).toBeNull();+ });+});++describe('convertForWasm', () => {+ it('does NOT mutate the caller-provided color object', () => {+ const color = { r: 0.1, g: 0.2, b: 0.3, a: 0.4 };+ const src = { color };+ convertForWasm(src as Record<string, unknown>, ['color']);+ // Caller's original object is untouched (still has r/g/b/a, no x/y/z/w).+ expect(color).toEqual({ r: 0.1, g: 0.2, b: 0.3, a: 0.4 });+ });++ it('replaces the color slot with a fresh {x,y,z,w} object', () => {+ const color = { r: 0.1, g: 0.2, b: 0.3, a: 0.4 };+ const src = { color };+ const out = convertForWasm(src as Record<string, unknown>, ['color']);+ expect(out.color).not.toBe(color);+ expect(out.color).toEqual({ x: 0.1, y: 0.2, z: 0.3, w: 0.4 });+ });++ it('returns the same outer object (zero outer allocation)', () => {+ const src = { color: { r: 1, g: 0, b: 0, a: 1 } };+ const out = convertForWasm(src as Record<string, unknown>, ['color']);+ expect(out).toBe(src);+ });+});++describe('round-trip', () => {+ it('convertFromWasm then convertForWasm restores the original numeric values', () => {+ const fromWasm = { tint: { x: 0.5, y: 0.6, z: 0.7, w: 0.8 } };+ const sdkView = convertFromWasm(fromWasm as Record<string, unknown>, ['tint']) as {+ tint: { r: number; g: number; b: number; a: number };+ };+ expect(sdkView.tint.r).toBeCloseTo(0.5);++ const back = convertForWasm({ tint: { r: sdkView.tint.r, g: sdkView.tint.g, b: sdkView.tint.b, a: sdkView.tint.a } }, ['tint']) as {+ tint: { x: number; y: number; z: number; w: number };+ };+ expect(back.tint).toEqual({ x: 0.5, y: 0.6, z: 0.7, w: 0.8 });+ });+});diff --git a/sdk/tests/ptr-bounds.test.ts b/sdk/tests/ptr-bounds.test.tsnew file mode 100644index 000000000..681928081--- /dev/null+++ b/sdk/tests/ptr-bounds.test.ts@@ -0,0 +1,64 @@+/**+ * @file ptr-bounds.test.ts+ * @brief BuiltinBridge pointer helpers reject out-of-bounds access.+ */+import { describe, expect, it } from 'vitest';+import { fillPtrFields, readPtrField, writePtrField } from '../src/ecs/BuiltinBridge';++function makeHeap(size = 64) {+ const buffer = new ArrayBuffer(size);+ return {+ f32: new Float32Array(buffer),+ u32: new Uint32Array(buffer),+ u8: new Uint8Array(buffer),+ };+}++describe('WASM pointer bounds', () => {+ it('readPtrField reads within bounds', () => {+ const { f32, u32, u8 } = makeHeap(32);+ f32[5] = 42.5;+ expect(readPtrField(f32, u32, u8, 20, { name: 'x', type: 'f32', offset: 0 })).toBeCloseTo(42.5);+ });++ it('readPtrField throws on out-of-bounds offset', () => {+ const { f32, u32, u8 } = makeHeap(32);+ expect(() => readPtrField(f32, u32, u8, 28, { name: 'v', type: 'vec2', offset: 0 }))+ .toThrow(/out of bounds/i);+ });++ it('writePtrField throws on out-of-bounds offset', () => {+ const { f32, u32, u8 } = makeHeap(32);+ expect(() => writePtrField(f32, u32, u8, 28, { name: 'v', type: 'vec4', offset: 0 }, { x: 1, y: 2, z: 3, w: 4 }))+ .toThrow(/out of bounds/i);+ });++ it('fillPtrFields throws when the struct spans past the heap', () => {+ const { f32, u32, u8 } = makeHeap(32);+ const fields = [+ { name: 'a', type: 'f32' as const, offset: 0 },+ { name: 'v', type: 'vec4' as const, offset: 20 }, // 20 + 16 = 36 > 32+ ];+ expect(() => fillPtrFields(f32, u32, u8, 0, fields, {}))+ .toThrow(/out of bounds/i);+ });++ it('fillPtrFields succeeds when every field fits', () => {+ const { f32, u32, u8 } = makeHeap(64);+ const fields = [+ { name: 'a', type: 'f32' as const, offset: 0 },+ { name: 'v', type: 'vec4' as const, offset: 16 },+ ];+ f32[0] = 1; f32[4] = 2; f32[5] = 3; f32[6] = 4; f32[7] = 5;+ const out: Record<string, unknown> = { v: { x: 0, y: 0, z: 0, w: 0 } };+ fillPtrFields(f32, u32, u8, 0, fields, out);+ expect(out.a).toBeCloseTo(1);+ expect(out.v).toMatchObject({ x: 2, y: 3, z: 4, w: 5 });+ });++ it('rejects negative offsets', () => {+ const { f32, u32, u8 } = makeHeap(32);+ expect(() => readPtrField(f32, u32, u8, -4, { name: 'x', type: 'f32', offset: 0 }))+ .toThrow(/out of bounds/i);+ });+});diff --git a/sdk/tests/query-cache-stats.test.ts b/sdk/tests/query-cache-stats.test.tsnew file mode 100644index 000000000..89ad8d632--- /dev/null+++ b/sdk/tests/query-cache-stats.test.ts@@ -0,0 +1,77 @@+/**+ * @file query-cache-stats.test.ts+ * @brief QueryCache hit/miss/invalidation accounting.+ */+import { describe, expect, it, beforeEach } from 'vitest';+import { QueryCache } from '../src/ecs/QueryCache';++describe('QueryCache.getStats', () => {+ let cache: QueryCache;++ beforeEach(() => {+ cache = new QueryCache();+ });++ it('counts the first lookup as a miss', () => {+ let computed = 0;+ cache.getOrCompute('q1', [], () => { computed++; return []; });+ const s = cache.getStats();+ expect(s.misses).toBe(1);+ expect(s.hits).toBe(0);+ expect(s.size).toBe(1);+ expect(computed).toBe(1);+ });++ it('counts a repeated lookup as a hit', () => {+ let computed = 0;+ cache.getOrCompute('q1', [], () => { computed++; return []; });+ cache.getOrCompute('q1', [], () => { computed++; return []; });+ expect(computed).toBe(1);+ const s = cache.getStats();+ expect(s.hits).toBe(1);+ expect(s.misses).toBe(1);+ });++ it('attributes a structural-change miss to structuralInvalidations', () => {+ cache.getOrCompute('q1', [], () => []);+ cache.markStructuralChange();+ cache.getOrCompute('q1', [], () => []);+ const s = cache.getStats();+ expect(s.structuralInvalidations).toBe(1);+ expect(s.componentInvalidations).toBe(0);+ });++ it('attributes a component-dirty miss to componentInvalidations', () => {+ const comp = Symbol('Position');+ cache.getOrCompute('q1', [comp], () => []);+ cache.markComponentDirty(comp);+ cache.getOrCompute('q1', [comp], () => []);+ const s = cache.getStats();+ expect(s.componentInvalidations).toBe(1);+ expect(s.structuralInvalidations).toBe(0);+ });++ it('resetStats zeroes counters but keeps cached entries', () => {+ cache.getOrCompute('q1', [], () => [1, 2, 3]);+ cache.getOrCompute('q1', [], () => [99]); // hit+ cache.resetStats();++ const s = cache.getStats();+ expect(s.hits).toBe(0);+ expect(s.misses).toBe(0);+ expect(s.size).toBe(1);++ let called = false;+ cache.getOrCompute('q1', [], () => { called = true; return []; });+ expect(called).toBe(false);+ expect(cache.getStats().hits).toBe(1);+ });++ it('size reflects entry count independent of hit/miss volume', () => {+ cache.getOrCompute('q1', [], () => []);+ cache.getOrCompute('q2', [], () => []);+ cache.getOrCompute('q1', [], () => []);+ cache.getOrCompute('q2', [], () => []);+ expect(cache.getStats().size).toBe(2);+ });+});