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
feat(ecs): a core with no module is handed the composition seam
esengine4252cba43f63
diff --git a/native/host/bindings/EcsBindings.cpp b/native/host/bindings/EcsBindings.cppindex 7d6888dd6..4e127b6cc 100644--- a/native/host/bindings/EcsBindings.cpp+++ b/native/host/bindings/EcsBindings.cpp@@ -22,7 +22,7 @@#include "esn_shim.hpp" // esn_entity-#include "esengine/ecs/TransformSystem.hpp" // ecs::setParent+#include "esengine/ecs/TransformSystem.hpp" // ecs::setParent, the composition epoch#include "esengine/ecs/components/Hierarchy.hpp" // Parent / Children#include "esengine/ecs/components/MeshRenderer.hpp" // MeshSkin@@ -107,6 +107,23 @@ JSValue js_setMeshSkinJoints(JSContext* ctx, JSValueConst, int argc, JSValueConsreturn JS_UNDEFINED;}+/**+ * The composition's staleness counter, as MEMORY rather than a call: every+ * Transform write announces through it, and an ABI call for one integer nearly+ * doubles the write it follows (bench/transform-invalidation).+ */+JSValue js_transformEpochBuffer(JSContext* ctx, JSValueConst, int, JSValueConst*) {+ return esn_arraybuffer(ctx, &ecs::transformMutationEpoch(), sizeof(u32));+}+/** The consumer half: compose if a producer said the inputs moved. A headless+ * host installs no renderer, and nothing else would ever schedule it. */+JSValue js_transformEnsureComposed(JSContext* ctx, JSValueConst, int, JSValueConst*) {+ if (host().ctx && host().registry) {+ if (auto* ts = host().ctx->tryGet<ecs::TransformSystem>()) ts->ensureComposed(*host().registry);+ }+ return JS_UNDEFINED;+}+} // namespacevoid registerEcsBindings(HostState& h, JSValue global) {@@ -121,6 +138,8 @@ void registerEcsBindings(HostState& h, JSValue global) {bindGlobal(h, global, "es_getMeshSkinJoints", js_getMeshSkinJoints, 1);bindGlobal(h, global, "es_setMeshSkinJoints", js_setMeshSkinJoints, 2);bindGlobal(h, global, "es_registryLayoutEpoch", js_layoutEpoch, 0);+ bindGlobal(h, global, "es_transformEpochBuffer", js_transformEpochBuffer, 0);+ bindGlobal(h, global, "es_transformEnsureComposed", js_transformEnsureComposed, 0);}} // namespace eshostdiff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.tsindex 178273a55..794f45f18 100644--- a/sdk/src/ecs/bridge/BuiltinBridge.ts+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts@@ -301,6 +301,20 @@ export interface BridgeConnectOptions {* bridge reaches components through the host's `es_<Component>_buffer` bindings.*/readonly memory?: MemoryProvider;++ /**+ * The world-transform composition seam, for a core with no emscripten module.+ * `epoch` is a one-word view over the engine's staleness counter and `ensure`+ * composes; the web build reads both off `module`. Without it a producer's+ * announcement goes nowhere and nothing ever recomposes.+ */+ readonly transformComposition?: TransformComposition;+}++/** The two halves of the composition seam a core has to expose. */+export interface TransformComposition {+ readonly epoch: Uint32Array;+ ensure(): void;}const METHOD_PREFIXES = ['add', 'get', 'has', 'remove'] as const;@@ -341,6 +355,7 @@ export class BuiltinBridge {private cppRegistry_: CppRegistry | null = null;private module_: ESEngineModule | null = null;private transformEpochWord_ = -1;+ private transformComposition_: TransformComposition | null = null;private memory_: MemoryProvider | null = null;private builtinMethodCache_ = new Map<string, BuiltinMethods>();private builtinEntitySets_ = new Map<string, Set<Entity>>();@@ -371,6 +386,10 @@ export class BuiltinBridge {this.transformEpochWord_ = module?.transform_epochAddress? module.transform_epochAddress() >>> 2: -1;+ // A native core has no module to read either half off, so it hands them+ // over: without this the epoch is unreachable from here and a world moved+ // only from script never recomposes.+ this.transformComposition_ = options.transformComposition ?? null;// Web derives a wasm-HEAP backend from the module; the native runtime// injects its own (es_<Component>_buffer). No module and no override => no// fast path (resolvePtr* return null), exactly as before.@@ -405,6 +424,8 @@ export class BuiltinBridge {this.cppRegistry_ = null;this.module_ = null;this.memory_ = null;+ this.transformComposition_ = null;+ this.transformEpochWord_ = -1;this.builtinMethodCache_.clear();this.builtinEntitySets_.clear();}@@ -415,6 +436,11 @@ export class BuiltinBridge {* friends, which are the composition's own output.*/invalidateTransformComposition(): void {+ const injected = this.transformComposition_;+ if (injected) {+ injected.epoch[0] = (injected.epoch[0]! + 1) >>> 0;+ return;+ }if (this.transformEpochWord_ < 0) return;const heap = this.module_?.HEAPU32;if (!heap) return;@@ -423,6 +449,7 @@ export class BuiltinBridge {/** Compose if any producer invalidated since the last one; O(1) otherwise. */ensureTransformsComposed(): void {+ if (this.transformComposition_) { this.transformComposition_.ensure(); return; }if (!this.cppRegistry_) return;this.module_?.transform_ensureComposed?.(this.cppRegistry_);}@@ -430,6 +457,7 @@ export class BuiltinBridge {/** @internal What the staleness counter reads, for the fixtures that assert* a producer notified. */transformEpoch(): number {+ if (this.transformComposition_) return this.transformComposition_.epoch[0]!;const heap = this.module_?.HEAPU32;return this.transformEpochWord_ < 0 || !heap ? -1 : heap[this.transformEpochWord_];}diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.tsindex 9323eed89..ba6b5927c 100644--- a/sdk/src/ecs/bridge/nativeBindings.ts+++ b/sdk/src/ecs/bridge/nativeBindings.ts@@ -40,6 +40,11 @@ export const REGISTRY_BINDINGS = {// The web build reaches this as an embind free function on the module; a// native host has no module, so it is a binding like the rest.layoutEpoch: 'es_registryLayoutEpoch',+ // The world-transform composition's two halves, for the same reason. The+ // epoch is handed over as MEMORY, not read through a call: every Transform+ // write announces through it.+ transformEpoch: 'es_transformEpochBuffer',+ ensureComposed: 'es_transformEnsureComposed',} as const;/**diff --git a/sdk/src/ecs/bridge/nativeRuntime.ts b/sdk/src/ecs/bridge/nativeRuntime.tsindex 348671af2..a47491979 100644--- a/sdk/src/ecs/bridge/nativeRuntime.ts+++ b/sdk/src/ecs/bridge/nativeRuntime.ts@@ -22,7 +22,7 @@ import { installNativePlatform, type NativeBridge } from '../../platform/native'import { createNativeRegistry } from './nativeRegistry';import { NativeMemoryProvider } from './memoryProvider';import { createNativeResourceManager } from './nativeResourceManager';-import { HOST_FLAGS, TEXT_BINDINGS, hasTextBindings, hasRendererBindings } from './nativeBindings';+import { HOST_FLAGS, REGISTRY_BINDINGS, TEXT_BINDINGS, hasTextBindings, hasRendererBindings } from './nativeBindings';import { createNativeRendererBackend, nativeSurfaceSize } from './nativeRenderer';import { createNativeEngineApi } from './nativeEngineApi.generated';import { setNativeEngineApi, engineApi } from './engineApi';@@ -55,6 +55,24 @@ import { platformLoadImagePixels } from '../../platform';* returned World is the real SDK World — the game script authors entities and* components through it, and the native host reads the resulting ECS each frame.*/+/**+ * The composition seam over the host's two bindings. The epoch is a view over the+ * engine's own word, so a producer STORES rather than calling.+ *+ * A host binding neither leaves the seam absent; `assertNativeBindings` says so at+ * boot rather than at the first frame that does not move.+ */+function nativeTransformComposition(scope: Record<string, unknown>) {+ const buffer = scope[REGISTRY_BINDINGS.transformEpoch];+ const ensure = scope[REGISTRY_BINDINGS.ensureComposed];+ if (typeof buffer !== 'function' || typeof ensure !== 'function') return undefined;+ const bytes = (buffer as () => ArrayBuffer | null)();+ if (!bytes) return undefined;+ // The arena never moves, unlike a growable wasm heap, so one view lasts.+ const epoch = new Uint32Array(bytes, 0, 1);+ return { epoch, ensure: () => { (ensure as () => void)(); } };+}+export function createNativeWorld(scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,): World {@@ -66,6 +84,7 @@ export function createNativeWorld(const world = new World();world.connectCpp(createNativeRegistry(scope), undefined, {memory: new NativeMemoryProvider(scope),+ transformComposition: nativeTransformComposition(scope),});return world;}@@ -93,6 +112,7 @@ export function createNativeApp(const app = App.new();app.connectCpp(createNativeRegistry(scope), undefined, {memory: new NativeMemoryProvider(scope),+ transformComposition: nativeTransformComposition(scope),});// The optional subsystems (physics today) come from the host binary rather than// a fetched wasm side module, through the same acquirer the web realms use — sodiff --git a/sdk/tests/world-transform-authority.test.ts b/sdk/tests/world-transform-authority.test.tsindex 4c509c77a..1c78944b4 100644--- a/sdk/tests/world-transform-authority.test.ts+++ b/sdk/tests/world-transform-authority.test.ts@@ -258,3 +258,59 @@ describe.skipIf(!HAS_WASM)('the editor writes through the same authority', () =>world.disconnectCpp();});});++/**+ * A core with no emscripten module — the shape a native host connects in — reads+ * neither half of the seam off `module`, so it hands them over instead. Here the+ * web engine stands in for that host: the epoch view and the compose call are the+ * engine's own, reached the way a native binding would deliver them.+ */+describe.skipIf(!HAS_WASM)('a core that hands the composition seam over', () => {+ let module: ESEngineModule;+ beforeAll(async () => { module = await loadWasmModule(); });++ /** What a native host binds: a one-word view, and the call that composes. On a+ * native core the word lives in an arena that never moves; here it borrows the+ * wasm heap, which is why nothing in these tests grows it. */+ const handedOver = (registry: CppRegistry) => ({+ epoch: new Uint32Array(module.HEAPU32.buffer, module.transform_epochAddress!(), 1),+ ensure: () => module.transform_ensureComposed!(registry),+ });++ function parented(handOver: boolean) {+ const app = App.new();+ const registry = new module.Registry() as unknown as CppRegistry;+ app.connectCpp(registry, undefined,+ handOver ? { transformComposition: handedOver(registry) } : {});+ const world = app.world;+ const parent = world.spawn('parent');+ world.insert(parent, Transform, { position: { x: 100, y: 0, z: 0 } });+ const child = world.spawn('child');+ world.insert(child, Transform, { position: { x: 5, y: 0, z: 0 } });+ world.setParent(child, parent);+ const worldX = () => (world.get(child, Transform) as { worldPosition: { x: number } })+ .worldPosition.x;+ return { world, parent, worldX };+ }++ it('composes through the seam it was handed', () => {+ const { world, parent, worldX } = parented(true);+ world.ensureTransformsComposed();+ expect(worldX()).toBe(105);++ const before = world.transformEpoch();+ world.update(parent, Transform, (t) => { (t as { position: { x: number } }).position.x = 200; });+ expect(world.transformEpoch()).not.toBe(before);+ world.ensureTransformsComposed();+ expect(worldX()).toBe(205);+ world.disconnectCpp();+ });++ it('without it, an announcement goes nowhere and nothing recomposes', () => {+ const { world, worldX } = parented(false);+ world.ensureTransformsComposed();+ expect(world.transformEpoch()).toBe(-1);+ expect(worldX()).toBe(0);+ world.disconnectCpp();+ });+});diff --git a/tools/census-transform-writers.mjs b/tools/census-transform-writers.mjsindex a91300046..8efe49330 100644--- a/tools/census-transform-writers.mjs+++ b/tools/census-transform-writers.mjs@@ -80,6 +80,20 @@ const OUTPUT_FIELDS = ['worldPosition', 'worldRotation', 'worldScale', 'cachedMa* spelling of the write that the scan does not see. */const OUTPUT_WRITE = new RegExp(String.raw`(?:(?:\.|->)\s*|^\s*)(${OUTPUT_FIELDS.join('|')})\s*(?:\.\w+\s*)?=[^=]`);+/**+ * The seam has to exist on BOTH cores. A producer announces by storing into the+ * epoch, so a core that does not hand that word over turns every announcement+ * into a no-op — nothing recomposes, and the only symptom is a world that stops+ * moving. Each entry: what the SDK asks for, and where that core answers it.+ */+const SEAM_SURFACES = [+ { core: 'web (embind)', asks: 'sdk/src/wasm.ts', answers: 'src/esengine/bindings/WebSDKEntry.cpp',+ names: ['transform_epochAddress', 'transform_ensureComposed'] },+ { core: 'native (QuickJS)', asks: 'sdk/src/ecs/bridge/nativeBindings.ts',+ answers: 'native/host/bindings/EcsBindings.cpp',+ names: ['es_transformEpochBuffer', 'es_transformEnsureComposed'] },+];+/** The hierarchy is the composition's other input, and one function writes it. */const HIERARCHY_WRITER = { file: 'src/esengine/ecs/TransformSystem.hpp', fn: 'setParent' };@@ -257,6 +271,18 @@ if (!outputWords) {}}+for (const surface of SEAM_SURFACES) {+ for (const file of [surface.asks, surface.answers]) {+ if (missing.some((m) => file.startsWith(m))) continue;+ const text = readFileSync(path.join(ROOT, file), 'utf8');+ for (const name of surface.names) {+ if (!text.includes(name)) {+ errors.push(`${file} — the ${surface.core} core does not carry \`${name}\`, so a producer there announces into nothing`);+ }+ }+ }+}+{const text = readFileSync(path.join(ROOT, HIERARCHY_WRITER.file), 'utf8');const i = text.split('\n').findIndex((l) => l.includes(`${HIERARCHY_WRITER.fn}(`) && l.includes('Registry&'));@@ -282,6 +308,9 @@ say(` ${HIERARCHY_WRITER.fn.padEnd(w)} hierarchy announces`);say(` ${' '.repeat(w)} ${HIERARCHY_WRITER.file}`);say(` ${' '.repeat(w)} a reparent moves a subtree without touching one transform field`);say('');+say(' The seam both cores carry:');+for (const surface of SEAM_SURFACES) say(` ${surface.core.padEnd(17)} ${surface.answers}`);+say('');say(' The composition\'s OUTPUT has one author:');for (const [file, why] of OUTPUT_AUTHORS) say(` ${file} — ${why}`);say('');