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
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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] }],}],