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: add pointer-based component reads bypassing embind marshalling

esengine824875c79dc9
diff --git a/sdk/benchmarks/wasm-vs-world.bench.ts b/sdk/benchmarks/wasm-vs-world.bench.ts
new file mode 100644
index 000000000..09db479f3
--- /dev/null
+++ b/sdk/benchmarks/wasm-vs-world.bench.ts
@@ -0,0 +1,323 @@
+import { describe, bench, beforeAll } from 'vitest';
+import path from 'path';
+import { World } from '../src/world';
+import { defineBuiltin } from '../src/component';
+import type { CppRegistry, ESEngineModule } from '../src/wasm';
+
+let wasmModule: ESEngineModule;
+
+const WASM_DIR = path.resolve(__dirname, '../../desktop/public/wasm');
+
+beforeAll(async () => {
+ const jsPath = path.join(WASM_DIR, 'esengine.js');
+ const mod = await import(jsPath);
+ wasmModule = await mod.default({
+ locateFile(p: string) {
+ return path.join(WASM_DIR, p);
+ },
+ });
+});
+
+const Transform = defineBuiltin('Transform', {
+ position: { x: 0, y: 0, z: 0 },
+ rotation: { x: 0, y: 0, z: 0, w: 1 },
+ scale: { x: 1, y: 1, z: 1 },
+ worldPosition: { x: 0, y: 0, z: 0 },
+ worldRotation: { x: 0, y: 0, z: 0, w: 1 },
+ worldScale: { x: 1, y: 1, z: 1 },
+});
+
+const Sprite = defineBuiltin('Sprite', {
+ texture: 0,
+ color: { r: 1, g: 1, b: 1, a: 1 },
+ size: { x: 100, y: 100 },
+ uvOffset: { x: 0, y: 0 },
+ uvScale: { x: 1, y: 1 },
+ layer: 0,
+ flipX: false,
+ flipY: false,
+ material: 0,
+ enabled: true,
+});
+
+const TRANSFORM_WASM = {
+ position: { x: 1, y: 2, z: 0 },
+ rotation: { x: 0, y: 0, z: 0, w: 1 },
+ scale: { x: 1, y: 1, z: 1 },
+ worldPosition: { x: 0, y: 0, z: 0 },
+ worldRotation: { x: 0, y: 0, z: 0, w: 1 },
+ worldScale: { x: 1, y: 1, z: 1 },
+};
+
+const SPRITE_SDK = {
+ texture: 0,
+ color: { r: 1, g: 1, b: 1, a: 1 },
+ size: { x: 100, y: 100 },
+ uvOffset: { x: 0, y: 0 },
+ uvScale: { x: 1, y: 1 },
+ layer: 0,
+ flipX: false,
+ flipY: false,
+ material: 0,
+ enabled: true,
+};
+
+const SPRITE_WASM = {
+ texture: 0,
+ color: { x: 1, y: 1, z: 1, w: 1 },
+ size: { x: 100, y: 100 },
+ uvOffset: { x: 0, y: 0 },
+ uvScale: { x: 1, y: 1 },
+ layer: 0,
+ flipX: false,
+ flipY: false,
+ material: 0,
+ enabled: true,
+};
+
+describe('World wrapper vs direct WASM - spawn', () => {
+ bench('direct WASM: registry.create()', () => {
+ const reg = new wasmModule.Registry();
+ for (let i = 0; i < 100; i++) reg.create();
+ reg.delete();
+ });
+
+ bench('World wrapper: world.spawn()', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ for (let i = 0; i < 100; i++) world.spawn();
+ reg.delete();
+ });
+});
+
+describe('World wrapper vs direct WASM - has (no color)', () => {
+ bench('direct WASM: hasTransform x1000', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ for (let i = 0; i < 1000; i++) reg.hasTransform(e);
+ reg.delete();
+ });
+
+ bench('World wrapper: world.has(Transform) x1000', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ for (let i = 0; i < 1000; i++) world.has(e, Transform);
+ reg.delete();
+ });
+});
+
+describe('World wrapper vs direct WASM - get (no color)', () => {
+ bench('direct WASM: getTransform x100', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ for (let i = 0; i < 100; i++) reg.getTransform(e);
+ reg.delete();
+ });
+
+ bench('World wrapper: world.get(Transform) x100', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ for (let i = 0; i < 100; i++) world.get(e, Transform);
+ reg.delete();
+ });
+});
+
+describe('World wrapper vs direct WASM - get (with color conversion)', () => {
+ bench('direct WASM: getSprite x100 (no conversion)', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addSprite(e, SPRITE_WASM);
+ for (let i = 0; i < 100; i++) reg.getSprite(e);
+ reg.delete();
+ });
+
+ bench('World wrapper: world.get(Sprite) x100 (color conversion)', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Sprite, SPRITE_SDK as any);
+ for (let i = 0; i < 100; i++) world.get(e, Sprite);
+ reg.delete();
+ });
+});
+
+describe('World wrapper vs direct WASM - insert', () => {
+ bench('direct WASM: addTransform', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ reg.delete();
+ });
+
+ bench('World wrapper: world.insert(Transform)', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ reg.delete();
+ });
+});
+
+describe('World wrapper vs direct WASM - tryGet', () => {
+ bench('direct WASM: has+get Transform x100', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ for (let i = 0; i < 100; i++) {
+ if (reg.hasTransform(e)) reg.getTransform(e);
+ }
+ reg.delete();
+ });
+
+ bench('World wrapper: world.tryGet(Transform) x100', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ for (let i = 0; i < 100; i++) world.tryGet(e, Transform);
+ reg.delete();
+ });
+});
+
+describe('World wrapper vs direct WASM - pre-resolved getter', () => {
+ bench('direct WASM: getTransform x100', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ for (let i = 0; i < 100; i++) reg.getTransform(e);
+ reg.delete();
+ });
+
+ bench('World pre-resolved getter: x100', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ const getter = world.resolveGetter(Transform)!;
+ for (let i = 0; i < 100; i++) getter(e);
+ reg.delete();
+ });
+});
+
+describe('Ptr-based getter vs embind getter - Transform', () => {
+ bench('embind: getTransform x100', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ for (let i = 0; i < 100; i++) reg.getTransform(e);
+ reg.delete();
+ });
+
+ bench('ptr-based: resolveGetter(Transform) x100', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ const getter = world.resolveGetter(Transform)!;
+ for (let i = 0; i < 100; i++) getter(e);
+ reg.delete();
+ });
+});
+
+describe('Ptr-based getter vs embind getter - Sprite', () => {
+ bench('embind: getSprite x100', () => {
+ const reg = new wasmModule.Registry();
+ const e = reg.create();
+ reg.addSprite(e, SPRITE_WASM);
+ for (let i = 0; i < 100; i++) reg.getSprite(e);
+ reg.delete();
+ });
+
+ bench('ptr-based: resolveGetter(Sprite) x100', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const e = world.spawn();
+ world.insert(e, Sprite, SPRITE_SDK as any);
+ const getter = world.resolveGetter(Sprite)!;
+ for (let i = 0; i < 100; i++) getter(e);
+ reg.delete();
+ });
+});
+
+describe('Ptr-based multi-entity query - Transform + Sprite', () => {
+ bench('embind: 100 entities x get Transform+Sprite', () => {
+ const reg = new wasmModule.Registry();
+ const entities: number[] = [];
+ for (let i = 0; i < 100; i++) {
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ reg.addSprite(e, SPRITE_WASM);
+ entities.push(e);
+ }
+ for (const e of entities) {
+ reg.getTransform(e);
+ reg.getSprite(e);
+ }
+ reg.delete();
+ });
+
+ bench('ptr-based: 100 entities x resolveGetter Transform+Sprite', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ const entities: number[] = [];
+ for (let i = 0; i < 100; i++) {
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ world.insert(e, Sprite, SPRITE_SDK as any);
+ entities.push(e);
+ }
+ const getT = world.resolveGetter(Transform)!;
+ const getS = world.resolveGetter(Sprite)!;
+ for (const e of entities) {
+ getT(e);
+ getS(e);
+ }
+ reg.delete();
+ });
+});
+
+describe('World wrapper overhead - full entity lifecycle', () => {
+ bench('direct WASM: create + addTransform + addSprite + getTransform + destroy', () => {
+ const reg = new wasmModule.Registry();
+ for (let i = 0; i < 50; i++) {
+ const e = reg.create();
+ reg.addTransform(e, TRANSFORM_WASM);
+ reg.addSprite(e, SPRITE_WASM);
+ reg.getTransform(e);
+ reg.getSprite(e);
+ reg.destroy(e);
+ }
+ reg.delete();
+ });
+
+ bench('World wrapper: spawn + insert x2 + get x2 + despawn', () => {
+ const world = new World();
+ const reg = new wasmModule.Registry();
+ world.connectCpp(reg as unknown as CppRegistry, wasmModule);
+ for (let i = 0; i < 50; i++) {
+ const e = world.spawn();
+ world.insert(e, Transform, TRANSFORM_WASM as any);
+ world.insert(e, Sprite, SPRITE_SDK as any);
+ world.get(e, Transform);
+ world.get(e, Sprite);
+ world.despawn(e);
+ }
+ reg.delete();
+ });
+});
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 6422bef1e..b321008d2 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -263,6 +263,10 @@ export interface ESEngineModule {
_anim_updateTweens(registry: CppRegistry, deltaTime: number): void;
_anim_getTweenState(registry: CppRegistry, tweenEntity: number): number;
+ // Pointer-based component access
+ getTransformPtr(registry: CppRegistry, entity: number): number;
+ getSpritePtr(registry: CppRegistry, entity: number): number;
+
_malloc(size: number): number;
_free(ptr: number): void;
diff --git a/sdk/src/world.ts b/sdk/src/world.ts
index 8c1ab9a80..33b83a902 100644
--- a/sdk/src/world.ts
+++ b/sdk/src/world.ts
@@ -578,6 +578,12 @@ export class World {
resolveGetter(component: AnyComponentDef): ((entity: Entity) => unknown) | null {
if (isBuiltinComponent(component)) {
if (!this.cppRegistry_) return null;
+
+ if (this.module_) {
+ const ptrGetter = this.resolvePtrGetter_(component._cppName);
+ if (ptrGetter) return ptrGetter;
+ }
+
const methods = this.getBuiltinMethods(component._cppName);
const colorKeys = component._colorKeys;
if (colorKeys.length === 0) {
@@ -590,6 +596,54 @@ export class World {
return (e) => storage.get(e);
}
+ private resolvePtrGetter_(cppName: string): ((entity: Entity) => unknown) | null {
+ const mod = this.module_!;
+ const reg = this.cppRegistry_!;
+
+ if (cppName === 'Transform') {
+ return (e: Entity) => {
+ const ptr = mod.getTransformPtr(reg, e);
+ if (!ptr) return null;
+ const f = mod.HEAPF32;
+ const b = ptr >> 2;
+ return {
+ position: { x: f[b], y: f[b+1], z: f[b+2] },
+ rotation: { x: f[b+3], y: f[b+4], z: f[b+5], w: f[b+6] },
+ scale: { x: f[b+7], y: f[b+8], z: f[b+9] },
+ worldPosition: { x: f[b+10], y: f[b+11], z: f[b+12] },
+ worldRotation: { x: f[b+13], y: f[b+14], z: f[b+15], w: f[b+16] },
+ worldScale: { x: f[b+17], y: f[b+18], z: f[b+19] },
+ };
+ };
+ }
+
+ if (cppName === 'Sprite') {
+ return (e: Entity) => {
+ const ptr = mod.getSpritePtr(reg, e);
+ if (!ptr) return null;
+ const f = mod.HEAPF32;
+ const u8 = mod.HEAPU8;
+ const i32 = new Int32Array(mod.HEAPF32.buffer);
+ const u32 = mod.HEAPU32;
+ const fb = ptr >> 2;
+ return {
+ texture: u32[fb],
+ color: { r: f[fb+1], g: f[fb+2], b: f[fb+3], a: f[fb+4] },
+ size: { x: f[fb+5], y: f[fb+6] },
+ uvOffset: { x: f[fb+7], y: f[fb+8] },
+ uvScale: { x: f[fb+9], y: f[fb+10] },
+ layer: i32[fb+11],
+ flipX: u8[ptr + 48] !== 0,
+ flipY: u8[ptr + 49] !== 0,
+ material: u32[fb+13],
+ enabled: u8[ptr + 56] !== 0,
+ };
+ };
+ }
+
+ return null;
+ }
+
// =========================================================================
// Query Support
// =========================================================================
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 395dda39f..8af519707 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -43,6 +43,7 @@
#include <glm/glm.hpp>
#include <cstring>
+#include <cstddef>
static_assert(sizeof(void*) == 4, "EM_JS pointer passing assumes wasm32 (4-byte pointers)");
@@ -279,8 +280,48 @@ resource::ResourceManager* getResourceManager() {
return g_resourceManager;
}
+// =============================================================================
+// Pointer-based Component Access
+// =============================================================================
+
+static_assert(offsetof(ecs::Transform, position) == 0);
+static_assert(offsetof(ecs::Transform, rotation) == 12);
+static_assert(offsetof(ecs::Transform, scale) == 28);
+static_assert(offsetof(ecs::Transform, worldPosition) == 40);
+static_assert(offsetof(ecs::Transform, worldRotation) == 52);
+static_assert(offsetof(ecs::Transform, worldScale) == 68);
+
+static_assert(offsetof(ecs::Sprite, texture) == 0);
+static_assert(offsetof(ecs::Sprite, color) == 4);
+static_assert(offsetof(ecs::Sprite, size) == 20);
+static_assert(offsetof(ecs::Sprite, uvOffset) == 28);
+static_assert(offsetof(ecs::Sprite, uvScale) == 36);
+static_assert(offsetof(ecs::Sprite, layer) == 44);
+static_assert(offsetof(ecs::Sprite, flipX) == 48);
+static_assert(offsetof(ecs::Sprite, flipY) == 49);
+static_assert(offsetof(ecs::Sprite, material) == 52);
+static_assert(offsetof(ecs::Sprite, enabled) == 56);
+
+int getTransformPtr(ecs::Registry& r, u32 e) {
+ auto* t = r.tryGet<ecs::Transform>(static_cast<Entity>(e));
+ if (!t) return 0;
+ t->ensureDecomposed();
+ return static_cast<int>(reinterpret_cast<uintptr_t>(t));
+}
+
+int getSpritePtr(ecs::Registry& r, u32 e) {
+ auto* s = r.tryGet<ecs::Sprite>(static_cast<Entity>(e));
+ if (!s) return 0;
+ return static_cast<int>(reinterpret_cast<uintptr_t>(s));
+}
+
} // namespace esengine
+EMSCRIPTEN_BINDINGS(esengine_ptr_access) {
+ emscripten::function("getTransformPtr", &esengine::getTransformPtr);
+ emscripten::function("getSpritePtr", &esengine::getSpritePtr);
+}
+
EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("initRenderer", &esengine::initRenderer);
emscripten::function("initRendererWithCanvas", &esengine::initRendererWithCanvas);