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.

fix(aot): a road takes a twin only for the parts of a call it can carry

yhh6617c8dfa904
diff --git a/compiler/src/codegen.ts b/compiler/src/codegen.ts
index b9255560b..eed6133a0 100644
--- a/compiler/src/codegen.ts
+++ b/compiler/src/codegen.ts
@@ -1014,6 +1014,8 @@ export interface ModuleDeclaration {
readonly resources: { name: string; mut: boolean; fields?: string[] }[];
readonly readers: { slot: number; event: string; fields: string[] }[];
readonly writers: { slot: number; event: string; fields: string[] }[];
+ /** Whether the body appends a command record, which a host has to flush. */
+ readonly commands: boolean;
}
export function moduleDeclarations(
@@ -1039,6 +1041,30 @@ export function moduleDeclarations(
writers: plan.writers.map((w) => ({
slot: w.slot, event: w.event, fields: fieldsOf(module.events, w.event),
})),
+ commands: writesCommands(sys, plan),
};
});
}
+
+/**
+ * Whether this system appends a COMMAND record — an emit that is not an event.
+ *
+ * The BODY, not the declaration: taking `Commands()` and never despawning
+ * writes nothing, and refusing on the channel would send a system back to the
+ * interpreter for a promise it does not make.
+ */
+function writesCommands(sys: EirSystem, plan: SysPlan): boolean {
+ const writerSlots = new Set(plan.writers.map((w) => w.slot));
+ const isCommand = (channel: Place): boolean => {
+ if (channel.p !== 'local') return true;
+ const at = plan.slots.get(channel.id);
+ return at === undefined || at.table !== 'channel' || !writerSlots.has(at.slot);
+ };
+ const walk = (body: readonly Stmt[]): boolean => body.some((s) => {
+ if (s.s === 'emit') return isCommand(s.channel);
+ if (s.s === 'rowLoop') return walk(s.body);
+ if (s.s === 'if') return walk(s.then) || walk(s.otherwise);
+ return false;
+ });
+ return walk(sys.body);
+}
diff --git a/pipeline/src/bundle/buildCompiledSystems.ts b/pipeline/src/bundle/buildCompiledSystems.ts
index 1eda664d0..95fef6272 100644
--- a/pipeline/src/bundle/buildCompiledSystems.ts
+++ b/pipeline/src/bundle/buildCompiledSystems.ts
@@ -55,6 +55,12 @@ export interface CompiledSystemInfo {
/** Event readers and writers, with the payload layout each one uses. */
readers: { slot: number; event: string; fields: string[] }[];
writers: { slot: number; event: string; fields: string[] }[];
+ /**
+ * Whether the body appends a command record. A road that cannot flush one to
+ * the world the interpreter would have flushed it to leaves the system to the
+ * interpreter, so this is what that decision is made on.
+ */
+ commands: boolean;
}
export interface CompiledSystemsManifest {
diff --git a/pipeline/tests/build-compiled-systems.test.ts b/pipeline/tests/build-compiled-systems.test.ts
index 59f3740a7..ca97d453d 100644
--- a/pipeline/tests/build-compiled-systems.test.ts
+++ b/pipeline/tests/build-compiled-systems.test.ts
@@ -97,6 +97,42 @@ export const moveSystem = defineSystem(
);
`;
+/** Takes the channel AND uses it: the declaration alone is not the question,
+ * because a system that never despawns writes no record for a host to flush. */
+const COMMANDS = `import { defineSystem, Query, Mut, Commands } from 'esengine';
+import { Mover } from './components';
+
+/**
+ * @compiled
+ */
+export const reapSystem = defineSystem(
+ [Query(Mut(Mover)), Commands()],
+ (query, cmds) => {
+ for (const [e, mover] of query) {
+ mover.speed = mover.speed - 1;
+ if (mover.speed <= 0) cmds.despawn(e);
+ }
+ },
+ { name: 'ReapSystem' },
+);
+`;
+
+/** Takes the channel and never writes to it. */
+const IDLE_COMMANDS = `import { defineSystem, Query, Mut, Commands } from 'esengine';
+import { Mover } from './components';
+
+/**
+ * @compiled
+ */
+export const idleSystem = defineSystem(
+ [Query(Mut(Mover)), Commands()],
+ (query, _cmds) => {
+ for (const [, mover] of query) mover.speed = mover.speed - 1;
+ },
+ { name: 'IdleSystem' },
+);
+`;
+
/** Promised, and outside the subset: trig is refused on purpose (§3.3). */
const BROKEN = PROMISED
.replace('mover.directionX * mover.speed', 'Math.sin(mover.directionX) * mover.speed')
@@ -226,6 +262,9 @@ describe('the AOT build step', () => {
// never has to tell "none" from "an older manifest".
readers: [],
writers: [],
+ // Off the BODY: this one takes no Commands channel, and one that took it
+ // and never despawned would say the same.
+ commands: false,
}]);
expect(out.manifest!.engineAbi).toMatch(/^[0-9a-f]{16}$/);
expect(out.manifest!.projectShapes).toMatch(/^[0-9a-f]{16}$/);
@@ -450,6 +489,27 @@ export const moveSystem = defineSystem(
* wrote the projectShapes a runtime would compute rather than the one a build
* produces — so a real reader module had never been loaded by anything.
*/
+describe('a compiled system that appends a command', () => {
+ it.skipIf(!HOST_CC)('says so, so a road that cannot flush one can refuse it', async () => {
+ const out = await buildCompiledSystems(
+ project({ 'src/components.ts': COMPONENTS, 'src/systems.ts': COMMANDS }),
+ { mode: 'release', target: 'native', cc: HOST_CC, run });
+ expect(out.errors).toEqual([]);
+ expect(out.manifest!.systems[0]!.commands).toBe(true);
+ });
+
+ // The declaration is not the question. Refusing on the channel would send a
+ // system to the interpreter for a promise it never makes, and the difference
+ // is a whole road's worth of systems on a host that cannot flush records.
+ it.skipIf(!HOST_CC)('and one that takes the channel without writing to it does not', async () => {
+ const out = await buildCompiledSystems(
+ project({ 'src/components.ts': COMPONENTS, 'src/systems.ts': IDLE_COMMANDS }),
+ { mode: 'release', target: 'native', cc: HOST_CC, run });
+ expect(out.errors).toEqual([]);
+ expect(out.manifest!.systems[0]!.commands).toBe(false);
+ });
+});
+
describe('a compiled system that reads an event', () => {
const READER = `import { defineComponent, defineEvent, defineSystem, Query, Mut, EventReader } from 'esengine';
export const Mover = defineComponent('Mover', { speed: 100 });
diff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.ts
index 588d09169..98131401c 100644
--- a/sdk/src/ecs/aot/AotSystems.ts
+++ b/sdk/src/ecs/aot/AotSystems.ts
@@ -37,6 +37,13 @@ export interface AotSystemDecl {
readonly readers?: readonly { slot: number; event: string; fields: readonly string[] }[];
/** Event writers, by the slot the appended record names. */
readonly writers?: readonly { slot: number; event: string; fields: readonly string[] }[];
+ /**
+ * Whether the body appends a COMMAND record. From the body rather than the
+ * declaration: taking `Commands()` and never despawning writes nothing.
+ * Absent is a manifest older than this field — read it as `true`, because
+ * the road that cannot flush them fails silently.
+ */
+ readonly commands?: boolean;
}
/**
diff --git a/sdk/src/ecs/aot/executorCapabilities.ts b/sdk/src/ecs/aot/executorCapabilities.ts
new file mode 100644
index 000000000..22b35c77a
--- /dev/null
+++ b/sdk/src/ecs/aot/executorCapabilities.ts
@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file executorCapabilities.ts
+ * @brief What a road can carry out of a call, and what a system needs carried.
+ *
+ * @details A twin is only a twin where the road can do everything the closure
+ * did. Two of those turned out not to be true of every road, and both
+ * failed silently in their own way:
+ *
+ * - EVENTS. A loading host hands the call `events = 0` and the emitted
+ * C dereferences it in the prologue, so a writer's twin faults on a
+ * frame where the system would have done nothing.
+ * - COMMANDS. The C++ host applies a despawn to its Registry inside
+ * the call and nothing tells the SDK's World, so the entity stays in
+ * every query, its children are never torn down and its script rows
+ * are never freed. Measured: four entities, eight frames, the
+ * interpreted road counts 3,2,1,0 and the compiled one counts 4.
+ *
+ * Queries and resources are deliberately NOT here. A host that cannot
+ * name a component leaves the system unbound at the first call, which
+ * is a per-frame answer about this world rather than a standing fact
+ * about the road — and the fallback already covers it.
+ *
+ * An unsupported capability is a FALLBACK, never a half-support: the
+ * interpreter still has the closure, and running it is the correct
+ * answer rather than the degraded one.
+ */
+import type { AotSystemDecl } from './AotSystems';
+
+/** The parts of a call a road may not be able to carry. */
+export interface AotExecutorCapabilities {
+ /** Payloads delivered INTO a call, as a query slot of event rows. */
+ readonly eventRead: boolean;
+ /** Payloads appended BY a call, which the host has to deliver after it. */
+ readonly eventWrite: boolean;
+ /** Command records appended by a call, which the host has to apply — to the
+ * same world the interpreter would have applied them to. */
+ readonly commands: boolean;
+}
+
+/**
+ * The wasm road: the module shares the engine's memory, so every table the ctx
+ * carries has somewhere to live and `AotDispatch` drains all of them.
+ */
+export const WEB_AOT: AotExecutorCapabilities = {
+ eventRead: true,
+ eventWrite: true,
+ commands: true,
+};
+
+/**
+ * The loading road: a host in its own process, packing its own rows.
+ *
+ * Neither event table exists (`AotHost.hpp` fills `events = 0`), and commands
+ * are applied to the C++ Registry by `es_aot_run` — a world the SDK's own
+ * `World.despawn` is not part of, so a despawn there is half a despawn.
+ */
+export const NATIVE_AOT: AotExecutorCapabilities = {
+ eventRead: false,
+ eventWrite: false,
+ commands: false,
+};
+
+/** What this system needs a road to carry, off what the build declared. */
+export function requiredCapabilities(decl: AotSystemDecl): AotExecutorCapabilities {
+ return {
+ eventRead: (decl.readers?.length ?? 0) > 0,
+ eventWrite: (decl.writers?.length ?? 0) > 0,
+ // Absent means a manifest older than this field, and the road that
+ // cannot flush them is the one that would crash quietly: assume the
+ // system commands rather than assume it does not.
+ commands: decl.commands ?? true,
+ };
+}
+
+/** Every capability this system needs that the road does not have. */
+export function missingCapabilities(
+ decl: AotSystemDecl,
+ road: AotExecutorCapabilities,
+): (keyof AotExecutorCapabilities)[] {
+ const need = requiredCapabilities(decl);
+ return (Object.keys(need) as (keyof AotExecutorCapabilities)[])
+ .filter((k) => need[k] && !road[k]);
+}
+
+/** What to say when a road leaves a system to the interpreter, in one place so
+ * both roads say it the same way. */
+export function whyInterpreted(name: string, missing: readonly string[]): string {
+ const what = missing.map((m) => SAID[m] ?? m).join(' and ');
+ return `AOT: ${name} needs ${what}, which this host cannot hand compiled code `
+ + '— the interpreter keeps it';
+}
+
+const SAID: Record<string, string> = {
+ eventRead: 'to read events',
+ eventWrite: 'to write events',
+ commands: 'to append commands',
+};
diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.ts
index e0382bd02..01d8d9bb1 100644
--- a/sdk/src/ecs/aot/installAot.ts
+++ b/sdk/src/ecs/aot/installAot.ts
@@ -32,6 +32,8 @@ import { AotEvents, type EventBusAccess } from './AotEvents';
import { AotSystems, type AotManifest } from './AotSystems';
import type { AotAddresses, AotRuntime } from './AotRuntime';
import { AotDispatch } from './AotDispatch';
+import { missingCapabilities, whyInterpreted, WEB_AOT } from './executorCapabilities';
+import { log } from '../../util/logger';
/**
* The engine module a compiled system shares memory with. The Memory OBJECT,
@@ -106,11 +108,20 @@ export async function prepareAot(opts: Omit<InstallAotOptions, 'runner'>): Promi
(exports['_initialize'] as (() => void) | undefined)?.();
const systems = new AotSystems();
+ // Through the same question the loading road asks, though this road answers
+ // yes to all of it: a road that does not DECLARE what it carries is a road
+ // outside the model, and the next capability to differ would find no gate.
+ const takeable = new Map(opts.manifest.systems.map((decl) => {
+ const missing = missingCapabilities(decl, WEB_AOT);
+ if (missing.length > 0) log.info('runtime', whyInterpreted(decl.name, missing));
+ return [decl.name, missing.length === 0];
+ }));
systems.install(opts.manifest, exports, componentNamed, {
resourceFields: opts.resourceFields ?? ((name) => {
const value = opts.resources(name);
return value === undefined ? undefined : Object.keys(value);
}),
+ runs: (name) => takeable.get(name) ?? false,
moduleContract: moduleContractOf(exports),
});
diff --git a/sdk/src/ecs/aot/installNativeAot.ts b/sdk/src/ecs/aot/installNativeAot.ts
index bd2053127..b2575f5b9 100644
--- a/sdk/src/ecs/aot/installNativeAot.ts
+++ b/sdk/src/ecs/aot/installNativeAot.ts
@@ -27,6 +27,7 @@ import { WasmPoolMemory, type WasmHeap } from '../WasmPoolMemory';
import { AotSystems, type AotManifest, type AotSystemDecl, type AotTwin } from './AotSystems';
import { AotResources, type ResourceReader } from './AotResources';
import type { AotDispatcher, AotRuntime } from './AotRuntime';
+import { missingCapabilities, whyInterpreted, NATIVE_AOT } from './executorCapabilities';
/** `sizeof(es_addr_t)` where a loaded library runs. */
const NATIVE_ADDRESS_BYTES = 8;
@@ -80,15 +81,6 @@ function declaredResourceLayouts(manifest: AotManifest): Map<string, readonly st
*/
const SPARSE_INDEX_MASK = ENTITY_INDEX_MASK;
-/**
- * Whether a native host can hand this system what it compiled against. Not
- * events: the ctx carries `events = 0` (AotHost.hpp) and the emitted C
- * dereferences it in the PROLOGUE, so a writer's twin faults on a frame where
- * it would have done nothing. A capability this road lacks is a FALLBACK.
- */
-function nativeCanHost(decl: AotSystemDecl): boolean {
- return !decl.readers?.length && !decl.writers?.length;
-}
/** Read the `es_aot_*` globals a native host bound, or null where it bound none. */
export function nativeAotBindings(
@@ -137,9 +129,9 @@ export function installNativeAot(opts: InstallNativeAotOptions): AotRuntime | nu
// that component, and until then the interpreter keeps the system.
const byName = new Map<string, number>();
for (const decl of opts.manifest.systems) {
- if (!nativeCanHost(decl)) {
- log.info('runtime', `AOT: ${decl.name} reads or writes events, which a loading host `
- + 'cannot hand compiled code — the interpreter keeps it');
+ const missing = missingCapabilities(decl, NATIVE_AOT);
+ if (missing.length > 0) {
+ log.info('runtime', whyInterpreted(decl.name, missing));
continue;
}
const at = bindings.index(decl.name);
diff --git a/sdk/tests/aot-native-install.test.ts b/sdk/tests/aot-native-install.test.ts
index 829962327..d5073c069 100644
--- a/sdk/tests/aot-native-install.test.ts
+++ b/sdk/tests/aot-native-install.test.ts
@@ -25,6 +25,7 @@ import { defineComponent, getComponent } from '../src/ecs/component';
import { defineSystem, SystemRunner } from '../src/ecs/system';
import { defineEvent, EventReader, EventWriter, EventRegistry } from '../src/ecs/event';
import { Query, Mut, Changed } from '../src/ecs/query';
+import { Commands } from '../src/ecs/commands';
import { ResourceStorage } from '../src/ecs/resource';
import { engineAbiDigest, projectShapeDigest } from '../src/ecs/aot/abiDigest';
import type { AotManifest } from '../src/ecs/aot/AotSystems';
@@ -51,8 +52,8 @@ const MANIFEST: AotManifest = {
engineAbi: engineAbiDigest(8),
projectShapes: projectShapeDigest([{ name: 'Drift', fields: ['x'] }]),
systems: [
- { name: 'DriftSystem', symbol: 'es_sys_Drift', queries: [[{ comp: 'Drift', mut: true }]], resources: [] },
- { name: 'OtherSystem', symbol: 'es_sys_Other', queries: [[{ comp: 'Drift', mut: true }]], resources: [] },
+ { name: 'DriftSystem', symbol: 'es_sys_Drift', commands: false, queries: [[{ comp: 'Drift', mut: true }]], resources: [] },
+ { name: 'OtherSystem', symbol: 'es_sys_Other', commands: false, queries: [[{ comp: 'Drift', mut: true }]], resources: [] },
],
};
@@ -109,17 +110,24 @@ const EVENT_MANIFEST: AotManifest = {
]),
systems: [
{
- name: 'SendSystem', symbol: 'es_sys_Send', resources: [],
+ name: 'SendSystem', symbol: 'es_sys_Send', commands: false, resources: [],
queries: [[{ comp: 'Drift', mut: true }]],
writers: [{ slot: 0, event: 'Hit', fields: ['amount'] }],
},
{
- name: 'ReadSystem', symbol: 'es_sys_Read', resources: [],
+ name: 'ReadSystem', symbol: 'es_sys_Read', commands: false, resources: [],
queries: [[{ comp: 'Hit', mut: false }], [{ comp: 'Drift', mut: true }]],
readers: [{ slot: 0, event: 'Hit', fields: ['amount'] }],
},
{
- name: 'PlainSystem', symbol: 'es_sys_Plain', resources: [],
+ name: 'PlainSystem', symbol: 'es_sys_Plain', commands: false, resources: [],
+ queries: [[{ comp: 'Drift', mut: true }]],
+ },
+ // The other capability this road lacks, and the quiet one: a loading
+ // host applies a despawn to its own Registry inside the call, and the
+ // World the interpreter would have despawned from never hears.
+ {
+ name: 'ReapSystem', symbol: 'es_sys_Reap', commands: true, resources: [],
queries: [[{ comp: 'Drift', mut: true }]],
},
],
@@ -317,6 +325,22 @@ describe('a capability a loading host cannot hand compiled code', () => {
expect(seen).toEqual([3]);
});
+ it('leaves a system that COMMANDS to the interpreter, and the despawn lands', () => {
+ const f = eventFixture();
+ const reap = defineSystem([Query(Mut(f.Drift)), Commands()], (query, cmds) => {
+ for (const [e] of query) cmds.despawn(e);
+ }, { name: 'ReapSystem' });
+
+ const entity = f.world.spawn();
+ f.world.insert(entity, f.Drift, { x: 0 });
+ f.runner.run(reap);
+
+ expect(f.calls).not.toContain('ReapSystem');
+ // The half that was silent: the twin ran, the C++ Registry lost the
+ // entity and this world kept it in every query it matched.
+ expect(f.world.valid(entity)).toBe(false);
+ });
+
it('and takes the system that needs none of it', () => {
const f = eventFixture();
const plain = defineSystem([Query(Mut(f.Drift))], () => {
@@ -400,7 +424,7 @@ describe('an event payload is a project shape', () => {
{ name: 'Struck', fields: [...fields] },
]),
systems: [{
- name: 'AbsorbSystem', symbol: 'es_sys_Absorb', resources: [],
+ name: 'AbsorbSystem', symbol: 'es_sys_Absorb', commands: false, resources: [],
queries: [[{ comp: 'Struck', mut: false }], [{ comp: 'Drift', mut: true }]],
readers: [{ slot: 0, event: 'Struck', fields: [...fields] }],
}],