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.

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.cpp
index 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, JSValueCons
return 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;
+}
+
} // namespace
void 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 eshost
diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.ts
index 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.ts
index 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.ts
index 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 — so
diff --git a/sdk/tests/world-transform-authority.test.ts b/sdk/tests/world-transform-authority.test.ts
index 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.mjs
index 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('');