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(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.ts
index 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.ts
index 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.ts
index e6cb4cdea..2933e3000 100644
--- a/sdk/src/world.ts
+++ b/sdk/src/world.ts
@@ -11,7 +11,7 @@ import { BuiltinBridge, convertFromWasm, convertForWasm, type BridgeConnectOptio
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+ });
+});