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: 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.cppindex 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);