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(aot): events compile, in both directions
esengine04279e131824
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f444de0a8..1dde4e368 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -45,6 +45,14 @@ published separately; it ships inside the editor.`UICameraInfo.viewProjection` is deliberately not in it, since a member has tohave a fixed width.+ Events compile too, both directions. `EventWriter(E)` and `EventReader(E)` are+ parameters a compiled system may declare: `writer.send({ … })` flattens the+ payload into the fields the event declares and appends one record, and+ `for (const e of reader)` walks this frame's payloads as memory. A payload's+ shape comes from the TYPE argument of `defineEvent`, including one named by an+ interface and one that nests — `color: { r, g, b }` is three fields, not a+ refusal. Fields must be `number`, `boolean` or `Entity`.+Hosts embedding the runtime themselves can do the same through`App.useCompiledSystems`, and `App.compiledSystems` reports which systems arerunning compiled and how many twin calls have happened (bothdiff --git a/compiler/src/abi.ts b/compiler/src/abi.tsindex e9b169eb4..ecc556eab 100644--- a/compiler/src/abi.ts+++ b/compiler/src/abi.ts@@ -129,6 +129,28 @@ export class AbiMemory {return base;}+ /**+ * Payloads of `name` waiting for a reader this frame, as base addresses.+ * Laid out like a component's row, because that is what the reader walks.+ */+ payloadsOf(name: string): readonly number[] {+ return this.payloads.get(name) ?? [];+ }++ /** Place one payload in the image, for a reader to be given this frame. */+ addPayload(name: string, fields: Record<string, number | boolean>): number {+ const shape = this.layout.comps.get(name);+ if (!shape) throw new Error(`ABI: no layout for event '${name}'`);+ const base = this.alloc(shape.stride);+ for (const [path, v] of Object.entries(fields)) this.writeLeaf(shape, base, path, v);+ const list = this.payloads.get(name) ?? [];+ list.push(base);+ this.payloads.set(name, list);+ return base;+ }++ private readonly payloads = new Map<string, number[]>();+addResource(name: string, fields: Record<string, number | boolean>): number {const shape = this.layout.resources.get(name);if (!shape) throw new Error(`ABI: no layout for resource '${name}'`);@@ -220,8 +242,16 @@ export interface SysPlan {/** One entry per declared `Res`/`ResMut`, in declaration order. `mut` is* what tells a mirroring host to write the block back after the call. */readonly resources: readonly ResourceArg[];- /** One entry per declared channel (`Commands`, later an event reader). */+ /** One entry per declared channel, in declaration order. */readonly channels: readonly string[];+ /**+ * Which query slots are EVENT readers, and of what. A reader's rows are one+ * payload each, so it rides the query table rather than a second one — the+ * host fills it differently, and this is what says so.+ */+ readonly readers: readonly { readonly slot: number; readonly event: string }[];+ /** Which channel slots are event WRITERS, in the order the ctx carries. */+ readonly writers: readonly { readonly slot: number; readonly event: string }[];/** A parameter's local id -> which of the three tables, and which slot. */readonly slots: ReadonlyMap<number, { readonly table: 'query' | 'res' | 'channel'; readonly slot: number }>;}@@ -230,6 +260,8 @@ export function planFor(sys: EirSystem): SysPlan {const queries: (readonly QueryArg[])[] = [];const resources: ResourceArg[] = [];const channels: string[] = [];+ const readers: { slot: number; event: string }[] = [];+ const writers: { slot: number; event: string }[] = [];const slots = new Map<number, { table: 'query' | 'res' | 'channel'; slot: number }>();for (const p of sys.params) {switch (p.type.k) {@@ -241,21 +273,33 @@ export function planFor(sys: EirSystem): SysPlan {slots.set(p.id, { table: 'res', slot: resources.length });resources.push({ name: p.type.name, mut: p.type.mut });break;+ case 'events':+ // One row per payload, one "component" per row: the query table+ // already carries exactly that shape.+ slots.set(p.id, { table: 'query', slot: queries.length });+ readers.push({ slot: queries.length, event: p.type.name });+ queries.push([{ comp: p.type.name, mut: false }]);+ break;case 'channel':slots.set(p.id, { table: 'channel', slot: channels.length });+ if (p.type.channel === 'event') writers.push({ slot: channels.length, event: p.type.name });channels.push(p.type.name);break;default:throw new Error(`ABI: '${p.name}' is a ${p.type.k}, which SysCtx has no table for`);}}- return { system: sys.name, queries, resources, channels, slots };+ return { system: sys.name, queries, resources, channels, readers, writers, slots };}/** A materialised call: where the ctx is, and where its count word lives. */export interface AbiCall {readonly ctx: number;readonly cmdCount: number;+ /** The event queue this call may append to, and how much of it is used. */+ readonly eventBuf: number;+ readonly eventCap: number;+ readonly eventCount: number;}/**@@ -270,7 +314,13 @@ export function materialize(mem: AbiMemory, plan: SysPlan): AbiCall {plan.queries.forEach((args, k) => {const stride = 1 + args.length;const matched: number[] = [];- for (const e of mem.entities) {+ const reader = plan.readers.find((r) => r.slot === k);+ if (reader) {+ // A reader's rows are the payloads this frame, entity-less: the+ // host packs the same [entity, base] pairs so the walk is one walk.+ for (const at of mem.payloadsOf(reader.event)) matched.push(0, at);+ }+ for (const e of reader ? [] : mem.entities) {const binds = args.map((a) => mem.baseOf(a.comp, e));if (binds.some((b) => b === undefined)) continue;matched.push(e, ...(binds as number[]));@@ -287,6 +337,18 @@ export function materialize(mem: AbiMemory, plan: SysPlan): AbiCall {const cmdCount = mem.scratch(4);mem.u32[cmdCount >> 2] = 0;+ // The event queue, sized for the writers this system declared. A system+ // with none gets a valid empty one rather than a null: the generated code+ // reads the struct before it knows whether it will append.+ const eventCap = plan.writers.length === 0 ? 0 : EVENT_SLOTS;+ const eventBuf = mem.scratch(Math.max(8, eventCap * 8));+ const eventCount = mem.scratch(4);+ mem.u32[eventCount >> 2] = 0;+ const eventOut = mem.scratch(3 * 4);+ mem.u32[eventOut >> 2] = eventBuf;+ mem.u32[(eventOut >> 2) + 1] = eventCap;+ mem.u32[(eventOut >> 2) + 2] = eventCount;+const ctx = mem.scratch(SYSCTX_WORDS_ * 4);const w = ctx >> 2;mem.u32[w] = queryTable;@@ -294,10 +356,13 @@ export function materialize(mem: AbiMemory, plan: SysPlan): AbiCall {mem.u32[w + 2] = mem.cmdBuf;mem.u32[w + 3] = mem.cmdCap;mem.u32[w + 4] = cmdCount;- mem.u32[w + 5] = 0; // events: no channel in v1 carries one yet- return { ctx, cmdCount };+ mem.u32[w + 5] = eventOut;+ return { ctx, cmdCount, eventBuf, eventCap, eventCount };}+/** Doubles a system may append per call. Bounded here, checked in the code. */+const EVENT_SLOTS = 256;+/*** The host a compiled system sees, reaching the world through NOTHING but the* ctx `materialize` wrote. It reads the packed row array rather than re-deriving@@ -318,7 +383,12 @@ export function abiHost(mem: AbiMemory, layout: AbiLayout, plan: SysPlan, call:const cmdCap = mem.u32[w + 3]!;return {*rows(args: readonly QueryArg[]) {- const k = plan.queries.indexOf(args);+ // By identity for a query the plan owns; by NAME for an event+ // reader, whose one-component args the caller builds fresh.+ let k = plan.queries.indexOf(args);+ if (k < 0 && args.length === 1) {+ k = plan.readers.find((r) => r.event === args[0]!.comp)?.slot ?? -1;+ }if (k < 0) throw new Error(`ABI: '${plan.system}' walks a query it did not declare`);const rows = mem.u32[(queryTable >> 2) + k * QUERYROWS_WORDS_]!;const count = mem.u32[(queryTable >> 2) + k * QUERYROWS_WORDS_ + 1]!;@@ -352,7 +422,20 @@ export function abiHost(mem: AbiMemory, layout: AbiLayout, plan: SysPlan, call:if (k < 0) throw new Error(`ABI: '${plan.system}' reads a resource it did not declare`);return mem.u32[(resTable >> 2) + k]!;},- emit(record, args) {+ emit(channel, record, args) {+ const writer = plan.writers.find((w) => w.event === channel);+ if (writer) {+ // The same record the compiled code appends: a slot then the+ // fields, in the order the payload declares them.+ const used = mem.u32[call.eventCount >> 2]!;+ const stride = args.length + 1;+ if (used + stride > call.eventCap) throw new Error('ABI: event buffer overflow');+ const at = (call.eventBuf >> 3) + used;+ mem.f64[at] = writer.slot;+ args.forEach((v, i) => { mem.f64[at + 1 + i] = typeof v === 'boolean' ? (v ? 1 : 0) : v; });+ mem.u32[call.eventCount >> 2] = used + stride;+ return;+ }const n = mem.u32[call.cmdCount >> 2]!;if (n >= cmdCap) throw new Error('ABI: command buffer overflow');const at = (cmdBuf >> 2) + n * CMD_WORDS_;diff --git a/compiler/src/codegen.ts b/compiler/src/codegen.tsindex f8220f521..7d0553338 100644--- a/compiler/src/codegen.ts+++ b/compiler/src/codegen.ts@@ -169,6 +169,18 @@ typedef struct EsSysCtx {/* What a host needs in order to CALL a system without glue written by hand.The compiler knows a system's queries and resources -- that is what _paramsis -- so it says so here rather than leaving each host to be told twice. */+/* Where a system APPENDS events: f64 records, because a payload is fields and+ not four words. A record is [writer slot, ...fields], and how long one is+ comes from the manifest — the host declared it.++ Its own queue rather than a wider EsCmd: fixed-width records and+ variable-width ones cannot share a buffer without stride guesswork. */+typedef struct EsEventOut {+ es_addr_t buf; /* double * */+ es_addr_t cap; /* capacity, in doubles */+ es_addr_t count; /* address of the used-doubles word */+} EsEventOut;+typedef struct EsQueryDecl {const char *const *comps; /* component names, in the order the query names them */const unsigned char *mut; /* 1 where the system may write that component */@@ -573,6 +585,11 @@ class Emitter {* contract's: writing past it is forbidden, and the host is what sized it.*/private emitCommand(s: Stmt & { s: 'emit' }, indent: number): void {+ const writer = s.channel.p === 'local'+ ? this.plan!.writers.find((w) => w.slot === this.plan!.slots.get(s.channel.p === 'local'+ ? s.channel.id : -1)?.slot)+ : undefined;+ if (writer) { this.emitEvent(s, writer.slot, indent); return; }const kind = s.record === 'despawn' ? 'ES_CMD_DESPAWN' : 'ES_CMD_REMOVE';const fields = ['a', 'b', 'c'];this.line(indent, 'if (es_cmd_n < es_cmd_cap) {');@@ -587,6 +604,24 @@ class Emitter {this.line(indent, '}');}+ /**+ * One payload appended: the writer's slot, then its fields in declared+ * order. Bounds-checked against the capacity the host set, and silent when+ * full for the same reason a command queue is — a system that overran would+ * otherwise write past a buffer it does not own.+ */+ private emitEvent(s: Stmt & { s: 'emit' }, slot: number, indent: number): void {+ const stride = s.args.length + 1;+ this.line(indent, `if (es_ev_n + ${stride}u <= es_ev_cap) {`);+ this.line(indent + 1, `double *es_rec = es_ev_buf + es_ev_n;`);+ this.line(indent + 1, `es_rec[0] = ${slot}.0;`);+ s.args.forEach((a, i) => {+ this.line(indent + 1, `es_rec[${i + 1}] = ${coerce(this.expr(a), a.type, F64)};`);+ });+ this.line(indent + 1, `es_ev_n += ${stride}u;`);+ this.line(indent, '}');+ }+/*** The op EIR exists to keep: a strided walk of a packed row array.* One `es_u32` per component per row and no lookup — the host already did@@ -655,14 +690,22 @@ class Emitter {if (usesRes) {this.line(1, 'const es_addr_t *es_resources = (const es_addr_t *)ES_PTR(es_c->resources);');}- const emits = hasEmit(sys.body);+ const sends = plan.writers.length > 0 && hasEmit(sys.body);+ const emits = hasEmit(sys.body) && plan.channels.length > plan.writers.length;if (emits) {this.line(1, 'EsCmd *es_cmd_buf = (EsCmd *)ES_PTR(es_c->cmdBuf);');this.line(1, 'const uint32_t es_cmd_cap = (uint32_t)es_c->cmdCap;');this.line(1, 'uint32_t *es_cmd_at = (uint32_t *)ES_PTR(es_c->cmdCount);');this.line(1, 'uint32_t es_cmd_n = *es_cmd_at;');}- if (plan.queries.length === 0 && !usesRes && !emits) this.line(1, '(void)es_c;');+ if (sends) {+ this.line(1, 'const EsEventOut *es_ev = (const EsEventOut *)ES_PTR(es_c->events);');+ this.line(1, 'double *es_ev_buf = (double *)ES_PTR(es_ev->buf);');+ this.line(1, 'const uint32_t es_ev_cap = (uint32_t)es_ev->cap;');+ this.line(1, 'uint32_t *es_ev_at = (uint32_t *)ES_PTR(es_ev->count);');+ this.line(1, 'uint32_t es_ev_n = *es_ev_at;');+ }+ if (plan.queries.length === 0 && !usesRes && !emits && !sends) this.line(1, '(void)es_c;');// A resource base is one indirection, resolved once at entry rather than// per row: the host already put the address in the table.for (const p of sys.params) {@@ -673,6 +716,7 @@ class Emitter {this.declare(sys.locals.filter((l) => !bound.has(l.id)), reads, 1);this.stmts(sys.body, 1);if (emits) this.line(1, '*es_cmd_at = es_cmd_n;');+ if (sends) this.line(1, '*es_ev_at = es_ev_n;');this.line(0, '}');this.line(0, '');}diff --git a/compiler/src/eir.ts b/compiler/src/eir.tsindex 5356964c7..758d613bc 100644--- a/compiler/src/eir.ts+++ b/compiler/src/eir.ts@@ -31,7 +31,10 @@ export type EirType =| { readonly k: 'res'; readonly name: string; readonly mut: boolean }| { readonly k: 'query'; readonly args: readonly QueryArg[] }/** A deferred-mutation channel: Commands, and later an EventWriter. */- | { readonly k: 'channel'; readonly name: string };+ /** Something a system APPENDS to: the command queue, or one event's writer. */+ | { readonly k: 'channel'; readonly name: string; readonly channel: 'commands' | 'event' }+ /** `EventReader(E)`: this frame's payloads of one event, walked like rows. */+ | { readonly k: 'events'; readonly name: string };export const F64: EirType = { k: 'f64' };export const BOOL: EirType = { k: 'bool' };@@ -220,6 +223,9 @@ export interface EirModule {readonly systems: readonly EirSystem[];readonly comps: ReadonlyMap<string, CompShape>;readonly fns: ReadonlyMap<string, EirFn>;+ /** Event payloads, by declared name. A separate namespace from components:+ * a program may name one of each the same thing without meaning one. */+ readonly events: ReadonlyMap<string, CompShape>;}// =============================================================================diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.tsindex 0d4f7a0e5..801d7b223 100644--- a/compiler/src/frontend.ts+++ b/compiler/src/frontend.ts@@ -219,8 +219,17 @@ class SystemLowerer {private readonly fns: ReadonlyMap<string, EirFn>,/** Why a function is absent, so the call site can say more than "no". */private readonly fnFailures: ReadonlyMap<string, string> = new Map(),+ /** Event payloads by declared name, and the const each is bound to. */+ private readonly events: ReadonlyMap<string, CompShape> = new Map(),+ private readonly eventBindings: ReadonlyMap<string, string> = new Map(),) {}+ /** The event a binding names, or null when the program declares no such one. */+ private eventName(binding: string): string | null {+ const name = this.eventBindings.get(binding) ?? binding;+ return this.events.has(name) ? name : null;+ }+/** Lower a module-level function; `lower` does the same for a system body. */lowerFn(name: string, params: readonly ts.ParameterDeclaration[], body: ts.ConciseBody): EirFn {const bound = params.map((p) => {@@ -317,9 +326,20 @@ class SystemLowerer {if (!arg || !ts.isIdentifier(arg)) throw new NotInSubset(el, `${kind}(...) needs a named resource`);return { k: 'res', name: this.compName(arg.text), mut: kind === 'ResMut' } as EirType;}+ if (kind === 'EventWriter' || kind === 'EventReader') {+ const arg = el.arguments[0];+ if (!arg || !ts.isIdentifier(arg)) throw new NotInSubset(el, `${kind}(...) needs a named event`);+ const name = this.eventName(arg.text);+ if (!name) {+ throw new NotInSubset(el, `'${arg.text}' is not an event this program declares`);+ }+ return kind === 'EventWriter'+ ? { k: 'channel', name, channel: 'event' } as EirType+ : { k: 'events', name } as EirType;+ }if (kind === 'Commands') {if (el.arguments.length !== 0) throw new NotInSubset(el, 'Commands() takes no arguments');- return { k: 'channel', name: 'Commands' } as EirType;+ return { k: 'channel', name: 'Commands', channel: 'commands' } as EirType;}if (kind !== 'Query') {// GetWorld hands over the whole World — arbitrary access, the one@@ -423,6 +443,9 @@ class SystemLowerer {}const q = this.lookup(node.expression, node.expression.text);const qt = q.type;+ // An event reader yields ONE payload per step, so it binds a plain name+ // rather than destructuring a row of components.+ if (qt.k === 'events') return this.eventLoop(node, q, qt.name);if (qt.k !== 'query') throw new NotInSubset(node.expression, `'${q.name}' is not a query`);const decl = ts.isVariableDeclarationList(node.initializer) ? node.initializer.declarations[0] : undefined;@@ -486,6 +509,12 @@ class SystemLowerer {throw new NotInSubset(node, `'${target.name}' is not a channel this subset can emit to`);}const record = callee.name.text;+ if (target.type.channel === 'event') {+ if (record !== 'send') {+ throw new NotInSubset(node, `an event writer has only 'send', not '${record}'`);+ }+ return this.sendEvent(node, target, target.type.name);+ }const arity = COMMAND_RECORDS[record];if (arity === undefined) {throw new NotInSubset(node, `Commands.${record} is not a record this subset emits yet`);@@ -497,6 +526,69 @@ class SystemLowerer {return { s: 'emit', channel: { p: 'local', id: target.id }, record, args };}+ /**+ * `for (const blow of blows)` over an `EventReader`. One binding, no entity:+ * an event is a payload rather than a row of components, and the loop is+ * the same statement so every later pass walks one shape.+ */+ private eventLoop(node: ts.ForOfStatement, reader: Local, event: string): Stmt {+ const decl = ts.isVariableDeclarationList(node.initializer)+ ? node.initializer.declarations[0] : undefined;+ if (!decl || !decl.name || !ts.isIdentifier(decl.name)) {+ throw new NotInSubset(node, 'an event loop binds one plain name');+ }+ const bindingName = decl.name.text;+ return this.scoped(() => {+ const bound = this.define(bindingName, { k: 'comp', name: event });+ const body = ts.isBlock(node.statement)+ ? node.statement.statements.flatMap((st) => this.stmt(st))+ : this.stmt(node.statement);+ return { s: 'rowLoop', query: { p: 'local', id: reader.id }, entity: null, binds: [bound.id], body };+ });+ }++ /**+ * `writer.send({ target: e, amount: 3 })` — the payload is FLATTENED into+ * the fields the event declares, in that order, so nothing needs a heap.+ * A field the event does not declare, or one it declares and the literal+ * omits, is refused: the record's shape is the contract.+ */+ private sendEvent(node: ts.CallExpression, writer: Local, event: string): Stmt {+ const arg = node.arguments[0];+ if (node.arguments.length !== 1 || !arg || !ts.isObjectLiteralExpression(arg)) {+ throw new NotInSubset(node, 'send takes one object literal');+ }+ const shape = this.events.get(event);+ if (!shape) throw new NotInSubset(node, `'${event}' has no declared payload`);++ const given = new Map<string, ts.Expression>();+ const collect = (obj: ts.ObjectLiteralExpression, prefix: string): void => {+ for (const prop of obj.properties) {+ if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) {+ throw new NotInSubset(prop, 'a payload field must be `name: value`');+ }+ const path = prefix ? `${prefix}.${prop.name.text}` : prop.name.text;+ if (ts.isObjectLiteralExpression(prop.initializer)) {+ collect(prop.initializer, path);+ continue;+ }+ given.set(path, prop.initializer);+ }+ };+ collect(arg, '');++ const args: Expr[] = [];+ for (const field of shape.fields.keys()) {+ const value = given.get(field);+ if (!value) throw new NotInSubset(node, `send is missing '${field}' of event '${event}'`);+ args.push(this.expr(value));+ given.delete(field);+ }+ const extra = [...given.keys()][0];+ if (extra) throw new NotInSubset(node, `event '${event}' has no field '${extra}'`);+ return { s: 'emit', channel: { p: 'local', id: writer.id }, record: 'send', args };+ }+private assignment(node: ts.Expression): Stmt {if (!ts.isBinaryExpression(node)) {throw new NotInSubset(node, 'only assignments are statements in this subset');@@ -754,6 +846,57 @@ function componentShape(call: ts.CallExpression, tag: boolean): CompShape | nullreturn { name: nameArg.text, storage: 'host', fields };}+/**+ * `defineEvent<{ target: Entity; amount: number }>('DamageDealt')` -> a shape.+ *+ * A payload's fields live only in the TYPE argument, read as syntax rather than+ * asked of the checker. A named type resolves against the program's own+ * interfaces; nesting flattens to dotted paths, as a component's does.+ */+function eventShape(+ call: ts.CallExpression, interfaces: ReadonlyMap<string, ts.InterfaceDeclaration>,+): CompShape | null {+ const nameArg = call.arguments[0];+ const arg = call.typeArguments?.[0];+ if (!nameArg || !ts.isStringLiteral(nameArg) || !arg) return null;++ const fields = new Map<string, FieldSpec>();+ const members = (t: ts.TypeNode): readonly ts.TypeElement[] | null => {+ if (ts.isTypeLiteralNode(t)) return t.members;+ if (ts.isTypeReferenceNode(t) && ts.isIdentifier(t.typeName)) {+ return interfaces.get(t.typeName.text)?.members ?? null;+ }+ return null;+ };+ const walk = (t: ts.TypeNode, prefix: string): boolean => {+ const ms = members(t);+ if (!ms) return false;+ for (const m of ms) {+ if (!ts.isPropertySignature(m) || !ts.isIdentifier(m.name) || !m.type) return false;+ const path = prefix ? `${prefix}.${m.name.text}` : m.name.text;+ const leaf = eventLeaf(m.type);+ if (leaf) { fields.set(path, leaf); continue; }+ if (!walk(m.type, path)) return false;+ }+ return true;+ };+ if (!walk(arg, '') || fields.size === 0) return null;+ // A host record like a `defineComponent` shape: f64 per leaf, laid out by+ // the ABI rather than by any C++ struct.+ return { name: nameArg.text, storage: 'host', fields };+}++/** A payload leaf: the three types an event field may be. */+function eventLeaf(t: ts.TypeNode): FieldSpec | null {+ if (t.kind === ts.SyntaxKind.NumberKeyword) return { type: F64, enc: HOST_ENC, offset: null };+ if (t.kind === ts.SyntaxKind.BooleanKeyword) return { type: BOOL, enc: HOST_ENC, offset: null };+ // `Entity` is a branded number, and the ABI carries it as one.+ if (ts.isTypeReferenceNode(t) && ts.isIdentifier(t.typeName) && t.typeName.text === 'Entity') {+ return { type: ENTITY, enc: HOST_ENC, offset: null };+ }+ return null;+}+/** Two declarations of one name are the same component only if every field matches. */function sameShape(a: CompShape, b: CompShape): boolean {if (a.fields.size !== b.fields.size) return false;@@ -796,6 +939,9 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str// things; move.ts happens to use one word for both, which is why this was// missing until a fixture used two.const bindings = new Map<string, string>();+ /** Event payloads, by declared name — a second namespace from components. */+ const events = new Map<string, CompShape>();+ const eventBindings = new Map<string, string>();const consts = new Map<string, ConstValue>();const fns = new Map<string, EirFn>();// Why a function could not be lowered, reported at the CALL SITE rather than@@ -843,9 +989,42 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<strif (v !== null) consts.set(node.name.text, v);});}+ // Interfaces first: an event's payload may name one declared in another file.+ const interfaces = new Map<string, ts.InterfaceDeclaration>();+ for (const sf of sources) {+ ts.forEachChild(sf, (node) => {+ if (ts.isInterfaceDeclaration(node)) interfaces.set(node.name.text, node);+ });+ }for (const sf of sources) {walkTop(sf, (node, binding) => {if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;+ if (node.expression.text === 'defineEvent') {+ const shape = eventShape(node, interfaces);+ if (!shape) {+ diagnostics.push({+ file: sf.fileName, line: lineOf(sf, node), kind: 'pending', severity: 'note',+ message: 'defineEvent needs a payload whose fields are all number, boolean or Entity',+ });+ return;+ }+ const clash = comps.get(shape.name);+ if (clash && !sameShape(clash, shape)) {+ diagnostics.push({+ file: sf.fileName, line: lineOf(sf, node), kind: 'permanent', severity: 'note',+ message: `'${shape.name}' is declared both as an event and as something else`+ + ' — one program cannot hold two',+ });+ return;+ }+ events.set(shape.name, shape);+ // ONE shape table downstream: a payload's fields are read the+ // same way a component's are, so every later pass finds them+ // without asking which kind of thing this name is.+ comps.set(shape.name, shape);+ if (binding) eventBindings.set(binding, shape.name);+ return;+ }const tag = node.expression.text === 'defineTag';if (!tag && node.expression.text !== 'defineComponent') return;const shape = componentShape(node, tag);@@ -890,7 +1069,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str}if (!name || !params || !body || fns.has(name)) return;try {- fns.set(name, new SystemLowerer(comps, bindings, consts, fns, fnFailures)+ fns.set(name, new SystemLowerer(comps, bindings, consts, fns, fnFailures, events, eventBindings).lowerFn(name, params, body));} catch (e) {if (!(e instanceof NotInSubset)) throw e;@@ -915,7 +1094,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<strif (!params || !fn || !ts.isArrowFunction(fn)) {throw new NotInSubset(node, 'defineSystem takes a parameter array and an arrow function');}- systems.push(new SystemLowerer(comps, bindings, consts, fns, fnFailures).lower(name, params, fn));+ systems.push(new SystemLowerer(comps, bindings, consts, fns, fnFailures, events, eventBindings).lower(name, params, fn));} catch (e) {if (!(e instanceof NotInSubset)) throw e;diagnostics.push({@@ -929,7 +1108,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str});}- return { module: { systems, comps, fns }, diagnostics, seen, systemBindings, required };+ return { module: { systems, comps, fns, events }, diagnostics, seen, systemBindings, required };}/** `{ name: 'MoveSystem' }` if given, else the const it is assigned to. */diff --git a/compiler/src/interp.ts b/compiler/src/interp.tsindex 3f15f268f..e23aacd18 100644--- a/compiler/src/interp.ts+++ b/compiler/src/interp.ts@@ -40,7 +40,9 @@ export interface EirHost {* mirrored the answer into. Agreeing is what the differential proves.*/service(resource: string, method: string, key: string | number): boolean;- emit(record: string, args: readonly (number | boolean)[]): void;+ /** `channel` is the parameter appended to: the command queue, or one+ * event's writer. Two queues, and a record means nothing without it. */+ emit(channel: string, record: string, args: readonly (number | boolean)[]): void;/** Called once after the body, where the SDK's runner flushes. */flush(): void;}@@ -51,10 +53,15 @@ export interface EirWorld {/** component name -> entity -> its row. An absent entity simply has none. */readonly comps: ReadonlyMap<string, Map<number, Row>>;readonly resources: ReadonlyMap<string, Row>;+ /** event name -> this frame's payloads, which is what a reader walks. */+ readonly events?: ReadonlyMap<string, readonly Row[]>;+ /** event name -> what systems SENT, in field order. Written by a flush. */+ sent?: Map<string, unknown[]>;}/** One appended record, waiting for the flush at system end. */interface Command {+ readonly channel: string;readonly record: string;readonly args: readonly unknown[];}@@ -186,9 +193,12 @@ function exec(case 'assign':writePlace(s.target, frame, host, owners, evalExpr(s.value, frame, fns, host, owners));break;- case 'emit':- host.emit(s.record, s.args.map((a) => evalExpr(a, frame, fns, host, owners)));+ case 'emit': {+ const channel = owners.get((s.channel as { id: number }).id);+ if (!channel) throw new Error('EIR: emit to an unbound channel');+ host.emit(channel, s.record, s.args.map((a) => evalExpr(a, frame, fns, host, owners)));break;+ }case 'if': {const out = evalExpr(s.cond, frame, fns, host, owners)? exec(s.then, frame, fns, host, owners)@@ -217,7 +227,10 @@ function exec(function ownersOf(sys: EirSystem): Map<number, string> {const out = new Map<number, string>();for (const l of [...sys.params, ...sys.locals]) {- if (l.type.k === 'comp' || l.type.k === 'res') out.set(l.id, l.type.name);+ // Channels and readers are named too: an emit says WHICH queue, and a+ // reader's rows come from the event it names.+ if (l.type.k === 'comp' || l.type.k === 'res' || l.type.k === 'channel'+ || l.type.k === 'events') out.set(l.id, l.type.name);}return out;}@@ -234,6 +247,11 @@ export function runSystemOn(sys: EirSystem, host: EirHost, fns: Fns = new Map())if (p.type.k === 'query') frame.set(p.id, { args: p.type.args });else if (p.type.k === 'res') frame.set(p.id, host.resource(p.type.name));else if (p.type.k === 'channel') frame.set(p.id, null);+ // A reader is walked exactly like a one-component query, and the host+ // decides whether those rows come from entities or from a queue.+ else if (p.type.k === 'events') {+ frame.set(p.id, { args: [{ comp: p.type.name, mut: false }] });+ }else throw new Error(`EIR: '${p.name}' has no parameter binding for ${p.type.k}`);}exec(sys.body, frame, fns, host, owners);@@ -249,6 +267,14 @@ export function jsHost(world: EirWorld): EirHost {const queued: Command[] = [];return {*rows(args) {+ // An event reader is one "component" that is an EVENT: its rows are+ // this frame's payloads, and no entity carries them.+ const only = args.length === 1 ? args[0]!.comp : null;+ const payloads = only === null ? undefined : world.events?.get(only);+ if (payloads) {+ for (const p of payloads) yield { entity: 0, binds: [p] };+ return;+ }for (const e of world.entities) {if (!args.every((a) => world.comps.get(a.comp)?.has(e))) continue;yield { entity: e, binds: args.map((a) => world.comps.get(a.comp)!.get(e)!) };@@ -274,11 +300,21 @@ export function jsHost(world: EirWorld): EirHost {if (typeof fn !== 'function') throw new Error(`EIR: resource '${name}' has no method '${method}'`);return (fn as (k: unknown) => unknown).call(row, key) === true;},- emit(record, args) {- queued.push({ record, args });+ emit(channel, record, args) {+ queued.push({ channel, record, args });},flush() {for (const c of queued) {+ if (c.record === 'send') {+ // Delivered where a reader would find them NEXT frame, which+ // is what the SDK's double-buffered bus does.+ const out = world.sent ?? new Map<string, unknown[]>();+ if (!world.sent) (world as { sent?: Map<string, unknown[]> }).sent = out;+ const list = out.get(c.channel) ?? [];+ list.push(c.args);+ out.set(c.channel, list);+ continue;+ }if (c.record !== 'despawn') throw new Error(`EIR: no flush for '${c.record}'`);const e = c.args[0] as number;const at = world.entities.indexOf(e);diff --git a/compiler/src/verify.ts b/compiler/src/verify.tsindex 6380b456c..498b79ef8 100644--- a/compiler/src/verify.ts+++ b/compiler/src/verify.ts@@ -198,7 +198,26 @@ class Verifier {}case 'emit': {const ch = this.placeType(s.channel);- if (ch && ch.k !== 'channel') this.fail(`emit to a ${typeName(ch)}`);+ if (ch && ch.k !== 'channel') { this.fail(`emit to a ${typeName(ch)}`); break; }+ if (ch?.channel === 'event') {+ // One argument per declared field, in declaration order —+ // re-derived from the shape rather than trusted, because a+ // short record would leave the host reading the next one.+ const shape = this.comps.get(ch.name);+ if (s.record !== 'send') this.fail(`'${s.record}' is not a record an event writer emits`);+ else if (!shape) this.fail(`event '${ch.name}' has no declared payload`);+ else if (s.args.length !== shape.fields.size) {+ this.fail(`send to '${ch.name}' carries ${s.args.length} field(s), not ${shape.fields.size}`);+ } else {+ [...shape.fields.values()].forEach((f, i) => {+ const t = this.exprType(s.args[i]!);+ if (t && t.k !== f.type.k) {+ this.fail(`send to '${ch.name}' field ${i} is ${typeName(t)}, not ${typeName(f.type)}`);+ }+ });+ }+ break;+ }if (s.record === 'despawn') {const t = s.args[0] ? this.exprType(s.args[0]) : null;if (s.args.length !== 1) this.fail(`despawn takes 1 argument, not ${s.args.length}`);@@ -217,6 +236,22 @@ class Verifier {case 'rowLoop': {const q = this.placeType(s.query);if (!q) break;+ // An event reader yields one payload per step, bound like a+ // component so the body reads its fields the same way.+ if (q.k === 'events') {+ if (s.binds.length !== 1 || s.entity !== null) {+ this.fail('an event loop binds exactly one payload and no entity');+ break;+ }+ const l = this.local(s.binds[0]!);+ if (l && (l.type.k !== 'comp' || l.type.name !== q.name)) {+ this.fail(`event loop binds '${l.name}' as ${typeName(l.type)} for '${q.name}'`);+ }+ this.loopDepth++;+ for (const b of s.body) this.stmt(b);+ this.loopDepth--;+ break;+ }if (q.k !== 'query') { this.fail(`rowLoop over a ${typeName(q)}`); break; }if (q.args.length !== s.binds.length) {this.fail(`rowLoop binds ${s.binds.length} components for a query of ${q.args.length}`);diff --git a/compiler/tests/codegen.test.ts b/compiler/tests/codegen.test.tsindex 353b3a11c..fbe67c984 100644--- a/compiler/tests/codegen.test.ts+++ b/compiler/tests/codegen.test.ts@@ -208,6 +208,25 @@ function build(dir: string, cModule: CModule, symbol: string, how: Addressing =}/** One call of the contract: materialise, run the compiled code, flush. */+/** The event records one call appended, as [slot, ...fields] per record. */+function recordsOf(mem: AbiMemory, sys: EirSystem, run: () => void): number[][] {+ const plan = planFor(sys);+ const before = materialize(mem, plan);+ run();+ const used = mem.u32[before.eventCount >> 2]!;+ const out: number[][] = [];+ for (let i = 0; i < used;) {+ // One slot word then the payload's fields; a writer's record length is+ // what the plan says its event declares.+ const slot = mem.f64[(before.eventBuf >> 3) + i]!;+ const event = plan.writers.find((w) => w.slot === slot)?.event ?? '';+ const len = (fixtures.module.events.get(event)?.fields.size ?? 0) + 1;+ out.push([...mem.f64.subarray((before.eventBuf >> 3) + i, (before.eventBuf >> 3) + i + len)]);+ i += len;+ }+ return out;+}+function frameOfC(exe: string, mem: AbiMemory, sys: EirSystem): void {const plan = planFor(sys);const call = materialize(mem, plan);@@ -300,6 +319,8 @@ function fixtureWorld(layout: AbiLayout): AbiMemory {mem.addResource('Input', {});mem.setResourceBit('Input', 'isKeyDown', 'KeyW', true);mem.setResourceBit('Input', 'isKeyPressed', 'Space', true);+ // Payloads for a reader to walk, in the image so both sides see the same.+ for (let i = 1; i <= 3; i++) mem.addPayload('FixturePinged', { by: i * 7 });for (let i = 1; i <= N; i++) {const s = seed(i);mem.addComponent('Transform', i, { 'position.x': s['tx']!, 'position.y': s['ty']! });@@ -385,7 +406,7 @@ describe('the emitted C says what the interpreter says', () => {// ternaries, folded module constants with a shadowing local, an inlined// helper, and the Math arguments where libm and ECMAScript disagree.for (const name of ['FixtureDrift', 'FixtureClampSys', 'FixtureTuned', 'FixtureHelpers',- 'FixtureMathOps', 'FixtureCamera', 'FixtureGate']) {+ 'FixtureMathOps', 'FixtureCamera', 'FixtureGate', 'FixturePong']) {it(`${name}: the whole image agrees with the interpreter`, () => {const sys = systemOf(fixtures, name);const layout = packLayout(fixtures.module.comps);@@ -438,6 +459,27 @@ describe('the emitted C says what the interpreter says', () => {expect(entities.some((e) => (drifts.get(e)! as { rate: number }).rate !== seed(e)['rate']!)).toBe(true);});+ /**+ * The WRITING half. Its effect is not in the image — a sent payload lives in+ * the per-call queue — so the records themselves are what the two sides have+ * to agree on, read back the way a host reads them.+ */+ it('FixturePing: the records the C appends are the records the interpreter does', () => {+ const ping = systemOf(fixtures, 'FixturePing');+ const layout = packLayout(fixtures.module.comps);+ const exe = build(join(tmp, 'ping'), emitC(fixtures.module, layout, [ping]), cSymbol('FixturePing'));++ const byC = fixtureWorld(layout);+ const byInterp = fixtureWorld(layout);+ const fromC = recordsOf(byC, ping, () => frameOfC(exe, byC, ping));+ const fromInterp = recordsOf(byInterp, ping,+ () => runOnAbi(ping, byInterp, layout, fixtures.module.fns));++ expect(fromC).toEqual(fromInterp);+ // An empty queue would agree with anything at all.+ expect(fromC.length).toBeGreaterThan(0);+ });+it('FixtureDrift also agrees with node, not only with the interpreter', () => {const drift = systemOf(fixtures, 'FixtureDrift');const layout = packLayout(fixtures.module.comps);diff --git a/compiler/tests/conformance.test.ts b/compiler/tests/conformance.test.tsindex 7598fa515..3fe4dc73a 100644--- a/compiler/tests/conformance.test.ts+++ b/compiler/tests/conformance.test.ts@@ -22,7 +22,10 @@ import { inlineSystem } from '../src/inline';import { builtinShapes } from '../src/builtins';import { printSystem } from '../src/eir';-import { driftSystem, clampSystem, tunedSystem, helperSystem, mathSystem, gateSystem } from './fixtures/in-subset';+import {+ driftSystem, clampSystem, tunedSystem, helperSystem, mathSystem, gateSystem,+ pingSystem, pongSystem,+} from './fixtures/in-subset';import { PROBE, probeRow } from './probe';import type { StubSystem } from './stubs/esengine';@@ -91,6 +94,8 @@ const drift = module.systems.find((s) => s.name === 'FixtureDrift');const clamp = module.systems.find((s) => s.name === 'FixtureClampSys');const tuned = module.systems.find((s) => s.name === 'FixtureTuned');const gate = module.systems.find((s) => s.name === 'FixtureGate');+const ping = module.systems.find((s) => s.name === 'FixturePing');+const pong = module.systems.find((s) => s.name === 'FixturePong');describe('conformance — locals, branches, logic', () => {it('compiles', () => {@@ -222,6 +227,71 @@ describe('conformance — a service question, and the ways out of a row loop', (});});+describe('conformance — an event out of memory and back into it', () => {+ it('compiles both halves, and verifies them', () => {+ expect(diagnostics.filter((d) => d.system === 'FixturePing' || d.system === 'FixturePong')).toEqual([]);+ expect(ping).toBeDefined();+ expect(pong).toBeDefined();+ expect(verifySystem(ping!, module.comps, module.fns)).toEqual([]);+ expect(verifySystem(pong!, module.comps, module.fns)).toEqual([]);+ });++ it('reads back as a send and a walk, not as calls', () => {+ expect(printSystem(ping!)).toMatchInlineSnapshot(`+ "system FixturePing(query: query<mut FixtureDrift>, out: channel<FixturePinged>) {+ rowLoop query -> (_, d) {+ if d.enabled {+ emit out.send(d.rate)+ }+ }+ }"+ `);+ expect(printSystem(pong!)).toMatchInlineSnapshot(`+ "system FixturePong(pings: events, query: query<mut FixtureDrift>) {+ let total = 0+ rowLoop pings -> (_, p) {+ total = (total + p.by)+ }+ rowLoop query -> (_, d) {+ d.wrap = total+ }+ }"+ `);+ });++ it('what one sends is what the other walks, and node agrees', () => {+ const byNode = makeWorld();+ const byEir = makeWorld();+ const run = (world: EirWorld, viaNode: boolean): void => {+ // A frame: send, then deliver what was sent, then read.+ if (viaNode) {+ const sent: { by: number }[] = [];+ const drifts = world.comps.get('FixtureDrift')!;+ const rows = {+ *[Symbol.iterator]() { for (const e of world.entities) yield [e, drifts.get(e)!]; },+ };+ (pingSystem as unknown as StubSystem).fn(rows, { send: (p: { by: number }) => sent.push(p) });+ (pongSystem as unknown as StubSystem).fn(sent, rows);+ return;+ }+ runSystem(ping!, world);+ const sent = (world.sent?.get('FixturePinged') ?? []) as (readonly number[])[];+ (world as { events?: Map<string, Row[]> }).events =+ new Map([['FixturePinged', sent.map((args) => ({ by: args[0]! }))]]);+ world.sent?.clear();+ runSystem(pong!, world);+ };+ for (let f = 0; f < 20; f++) { run(byNode, true); run(byEir, false); }+ expect(byEir.comps.get('FixtureDrift')).toEqual(byNode.comps.get('FixtureDrift'));+ });++ it('and something was actually sent — an empty queue agrees with anything', () => {+ const world = makeWorld();+ runSystem(ping!, world);+ expect((world.sent?.get('FixturePinged') ?? []).length).toBeGreaterThan(0);+ });+});+describe('conformance — ternaries and exact Math', () => {function clampWorld(): EirWorld {let a = 0x9e3779b1 >>> 0;diff --git a/compiler/tests/coverage.test.ts b/compiler/tests/coverage.test.tsindex c4d5e21a5..e9b0436c0 100644--- a/compiler/tests/coverage.test.ts+++ b/compiler/tests/coverage.test.ts@@ -50,9 +50,9 @@ import { builtinShapes } from '../src/builtins';const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));/** Per-frame systems only. See the file header before lowering these. */-const FRAME_FLOOR = 13;+const FRAME_FLOOR = 14;/** Per-frame systems the contract could take once the pending work is done. */-const CEILING_FLOOR = 85;+const CEILING_FLOOR = 84;function walk(dir: string, out: string[] = []): string[] {for (const name of readdirSync(dir)) {diff --git a/compiler/tests/fixtures/in-subset.ts b/compiler/tests/fixtures/in-subset.tsindex a1663abe0..9a48a4cd9 100644--- a/compiler/tests/fixtures/in-subset.ts+++ b/compiler/tests/fixtures/in-subset.ts@@ -8,7 +8,10 @@* by conformance.test.ts — a feature the frontend lowers but nobody* runs both ways is a feature nobody has checked.*/-import { defineComponent, defineSystem, Query, Mut, Res, Camera, Input, Time, Transform } from 'esengine';+import {+ defineComponent, defineEvent, defineSystem, EventReader, EventWriter,+ Query, Mut, Res, Camera, Input, Time, Transform,+} from 'esengine';export const Drift = defineComponent('FixtureDrift', { rate: 40, wrap: 100, enabled: true });@@ -158,3 +161,28 @@ export const gateSystem = defineSystem(},{ name: 'FixtureGate' },);++/** One payload, and the two halves that put it into memory and take it out. */+export const Pinged = defineEvent<{ by: number }>('FixturePinged');++export const pingSystem = defineSystem(+ [Query(Mut(Drift)), EventWriter(Pinged)],+ (query, out) => {+ for (const [, d] of query) {+ if (d.enabled) out.send({ by: d.rate });+ }+ },+ { name: 'FixturePing' },+);++export const pongSystem = defineSystem(+ [EventReader(Pinged), Query(Mut(Drift))],+ (pings, query) => {+ let total = 0;+ for (const p of pings) total = total + p.by;+ for (const [, d] of query) {+ d.wrap = total;+ }+ },+ { name: 'FixturePong' },+);diff --git a/compiler/tests/stubs/esengine.ts b/compiler/tests/stubs/esengine.tsindex 43d51c13c..def840f5c 100644--- a/compiler/tests/stubs/esengine.ts+++ b/compiler/tests/stubs/esengine.ts@@ -38,6 +38,16 @@ export function ResMut(resource: unknown): unknown {return { kind: 'resmut', resource };}export const Input = { _name: 'Input' };+export function defineEvent<T>(name: string): { _name: string } {+ void (undefined as T | undefined);+ return { _name: name };+}+export function EventWriter(event: unknown): unknown {+ return { kind: 'event_writer', event };+}+export function EventReader(event: unknown): unknown {+ return { kind: 'event_reader', event };+}export const Sprite = { _name: 'Sprite' };export const Camera = { _name: 'Camera' };export function defineSystem(diff --git a/examples/event-system/src/systems/collect.ts b/examples/event-system/src/systems/collect.tsindex e295e2568..831946576 100644--- a/examples/event-system/src/systems/collect.ts+++ b/examples/event-system/src/systems/collect.ts@@ -1,12 +1,12 @@import {- defineSystem, Query, Res, Time, Commands, EventWriter,+ defineSystem, Query, Mut, Res, Time, Commands, EventWriter,Transform, Sprite,} from 'esengine';import { Collectible } from '../components';import { CollectEventDef } from '../events';export const collectSystem = defineSystem(- [Query(Transform, Sprite, Collectible), Res(Time), Commands(), EventWriter(CollectEventDef)],+ [Query(Transform, Mut(Sprite), Collectible), Res(Time), Commands(), EventWriter(CollectEventDef)],(query, time, cmds, writer) => {for (const [entity, _transform, sprite, collectible] of query) {sprite.color.a -= time.delta * 0.2;diff --git a/pipeline/src/bundle/buildCompiledSystems.ts b/pipeline/src/bundle/buildCompiledSystems.tsindex 8c7962fe4..01999459b 100644--- a/pipeline/src/bundle/buildCompiledSystems.ts+++ b/pipeline/src/bundle/buildCompiledSystems.ts@@ -47,6 +47,9 @@ export interface CompiledSystemInfo {/** One per declared Res/ResMut, in declaration order. `mut` is what makes the* runtime write a mirrored resource back after the call. */resources: { name: string; mut: boolean }[];+ /** 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[] }[];}export interface CompiledSystemsManifest {@@ -76,6 +79,12 @@ export interface BuildCompiledResult {notes: string[];}+/** A payload's fields in LAYOUT order, which is the order the code reads them. */+function fieldsOf(module: { events: ReadonlyMap<string, { fields: ReadonlyMap<string, unknown> }> },+ event: string): string[] {+ return [...(module.events.get(event)?.fields.keys() ?? [])];+}+/** Every `.ts` under `src/`, which is the unit a project's program is. */function sources(root: string): string[] {const out: string[] = [];@@ -227,6 +236,14 @@ export async function buildCompiledSystems(symbol: cSymbol(sys.name),queries: plan.queries.map((q) => q.map((a) => ({ comp: a.comp, mut: a.mut }))),resources: plan.resources.map((r) => ({ name: r.name, mut: r.mut })),+ // The payload layout travels with the manifest: the runtime flattens an+ // object into it, and the compiled code reads at those offsets.+ readers: plan.readers.map((r) => ({+ slot: r.slot, event: r.event, fields: fieldsOf(lowered.module, r.event),+ })),+ writers: plan.writers.map((w) => ({+ slot: w.slot, event: w.event, fields: fieldsOf(lowered.module, w.event),+ })),};}),};diff --git a/pipeline/tests/build-compiled-systems.test.ts b/pipeline/tests/build-compiled-systems.test.tsindex c26a55726..531ee4ea0 100644--- a/pipeline/tests/build-compiled-systems.test.ts+++ b/pipeline/tests/build-compiled-systems.test.ts@@ -219,6 +219,10 @@ describe('the AOT build step', () => {symbol: 'es_sys_MoveSystem',queries: [[{ comp: 'Transform', mut: true }, { comp: 'Mover', mut: false }]],resources: [{ name: 'Time', mut: false }],+ // A system with no events still declares the two lists, so a runtime+ // never has to tell "none" from "an older manifest".+ readers: [],+ writers: [],}]);expect(out.manifest!.engineAbi).toMatch(/^[0-9a-f]{16}$/);expect(out.manifest!.projectShapes).toMatch(/^[0-9a-f]{16}$/);diff --git a/pipeline/tests/export-aot.test.ts b/pipeline/tests/export-aot.test.tsindex defb2d0ac..9e19057f5 100644--- a/pipeline/tests/export-aot.test.ts+++ b/pipeline/tests/export-aot.test.ts@@ -98,13 +98,17 @@ describe('the promised systems in a web package', () => {const manifest = JSON.parse(readFileSync(path.join(f.out, AOT_MANIFEST), 'utf8')) as {engineAbi: string; projectShapes: string;- systems: { name: string; symbol: string; queries: { comp: string; mut: boolean }[][]; resources: { name: string; mut: boolean }[] }[];+ systems: { name: string; symbol: string; queries: { comp: string; mut: boolean }[][]; resources: { name: string; mut: boolean }[]; readers: unknown[]; writers: unknown[] }[];};expect(manifest.systems).toEqual([{name: 'MoveSystem',symbol: 'es_sys_MoveSystem',queries: [[{ comp: 'Transform', mut: true }, { comp: 'Mover', mut: false }]],resources: [{ name: 'Time', mut: false }],+ // A system with no events still declares the two lists, so a runtime+ // never has to tell "none" from "an older manifest".+ readers: [],+ writers: [],}]);expect(manifest.engineAbi).toMatch(/^[0-9a-f]{16}$/);diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex d41ec17f9..17fde38b9 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -521,8 +521,10 @@ systems: readonly AotSystemDecl[]```name: stringqueries: readonly (readonly { comp: string; mut: boolean; }[])[]+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefinedresources: readonly { name: string; mut: boolean; }[]symbol: string+writers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined```## App — class @experimental@@ -3071,6 +3073,7 @@ static prototype: EventReaderInstance<any>## EventRegistry — class @experimental```+busNamed: (name: string) => EventBus<unknown> | undefinedgetBus: <T>(event: EventDef<T>) => EventBus<T>register: <T>(event: EventDef<T>) => voidswapAll: () => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex b676c5b56..6e19d228a 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -521,8 +521,10 @@ systems: readonly AotSystemDecl[]```name: stringqueries: readonly (readonly { comp: string; mut: boolean; }[])[]+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefinedresources: readonly { name: string; mut: boolean; }[]symbol: string+writers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined```## App — class @experimental@@ -3079,6 +3081,7 @@ static prototype: EventReaderInstance<any>## EventRegistry — class @experimental```+busNamed: (name: string) => EventBus<unknown> | undefinedgetBus: <T>(event: EventDef<T>) => EventBus<T>register: <T>(event: EventDef<T>) => voidswapAll: () => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 61088dbcb..04551e4b6 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -516,8 +516,10 @@ systems: readonly AotSystemDecl[]```name: stringqueries: readonly (readonly { comp: string; mut: boolean; }[])[]+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefinedresources: readonly { name: string; mut: boolean; }[]symbol: string+writers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined```## App — class @experimental@@ -3066,6 +3068,7 @@ static prototype: EventReaderInstance<any>## EventRegistry — class @experimental```+busNamed: (name: string) => EventBus<unknown> | undefinedgetBus: <T>(event: EventDef<T>) => EventBus<T>register: <T>(event: EventDef<T>) => voidswapAll: () => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 005de4315..f588e5734 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -516,8 +516,10 @@ systems: readonly AotSystemDecl[]```name: stringqueries: readonly (readonly { comp: string; mut: boolean; }[])[]+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefinedresources: readonly { name: string; mut: boolean; }[]symbol: string+writers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined```## App — class @experimental@@ -3066,6 +3068,7 @@ static prototype: EventReaderInstance<any>## EventRegistry — class @experimental```+busNamed: (name: string) => EventBus<unknown> | undefinedgetBus: <T>(event: EventDef<T>) => EventBus<T>register: <T>(event: EventDef<T>) => voidswapAll: () => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex e659edac0..38ba1a2dc 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -516,8 +516,10 @@ systems: readonly AotSystemDecl[]```name: stringqueries: readonly (readonly { comp: string; mut: boolean; }[])[]+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefinedresources: readonly { name: string; mut: boolean; }[]symbol: string+writers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined```## App — class @experimental@@ -3066,6 +3068,7 @@ static prototype: EventReaderInstance<any>## EventRegistry — class @experimental```+busNamed: (name: string) => EventBus<unknown> | undefinedgetBus: <T>(event: EventDef<T>) => EventBus<T>register: <T>(event: EventDef<T>) => voidswapAll: () => voiddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex deaf19ee0..92b9e4d4b 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -11,7 +11,7 @@ import { builtinResource, ResourceStorage, Time, TimeData, type ResourceDef } frimport { prepareAot, type AotHost } from '../ecs/aot/installAot';import type { AotManifest } from '../ecs/aot/AotSystems';import type { AotRuntime } from '../ecs/aot/AotRuntime';-import { EventRegistry, type EventDef } from '../ecs/event';+import { EventRegistry, eventNamed, type EventDef } from '../ecs/event';import type { ESEngineModule, CppRegistry } from '../wasm';import type { OutputTransform } from '../postprocess';import type { BridgeConnectOptions } from '../ecs/bridge/BuiltinBridge';@@ -632,6 +632,17 @@ export class App {manifest: opts.manifest,wasm: opts.wasm,knowsResource: (name) => builtinResource(name) !== undefined,+ // A manifest carries event NAMES; the registry answers for the ones+ // some system has asked for a reader or a writer of.+ events: (name) => {+ // Through the DEFINITION, so the bus exists whether or not an+ // interpreted system has asked for one yet: a twin sending into+ // a bus nobody had made would drop its payloads and say nothing.+ const def = eventNamed(name);+ if (def === undefined) return undefined;+ const bus = this.eventRegistry_.getBus(def);+ return { read: () => bus.getReadBuffer(), send: (payload) => bus.send(payload) };+ },resources: (name) => {const def = builtinResource(name);// `get`, not `has` then `get`: a slot holding a materialiseddiff --git a/sdk/src/ecs/aot/AotContext.ts b/sdk/src/ecs/aot/AotContext.tsindex e2569243b..998130fb6 100644--- a/sdk/src/ecs/aot/AotContext.ts+++ b/sdk/src/ecs/aot/AotContext.ts@@ -38,13 +38,19 @@ export interface AotCommand {* The per-call scratch, in engine memory. One instance per system is enough —* a call is over before the next begins, and nothing may outlive it.*/+/** The header a system's event queue starts with: buf, cap, count. */+const EVENT_OUT_WORDS = 3;+export class AotContext {private block: PoolBlock | null = null;private words: Uint32Array = EMPTY;private cmdCap: number;+ /** f64 slots a call may append across every writer it declared. */+ private eventCap: number;- constructor(private readonly memory: PoolMemory, cmdCap = 256) {+ constructor(private readonly memory: PoolMemory, cmdCap = 256, eventCap = 512) {this.cmdCap = cmdCap;+ this.eventCap = eventCap;}/** Hand the block back; the arena is dead after this. */@@ -75,7 +81,8 @@ export class AotContext {+ rowWords+ resources.length+ 1 // the count, which the code writes back- + this.cmdCap * CMD_WORDS;+ + this.cmdCap * CMD_WORDS+ + EVENT_OUT_WORDS + 1 + this.eventCap * 2; // f64 slots are two wordsthis.reserve_(need);const base = this.block!.byteOffset;@@ -97,14 +104,29 @@ export class AotContext {w[slot] = base + (rowsAt + offsets[k]!) * 4;w[slot + 1] = counts[k]!;}+ // The event queue: a header of three addresses, its own used-count, and+ // the f64 records themselves. A system that writes none still gets a+ // valid header, because the code reads it before it knows.+ let evAt = cmdBuf + this.cmdCap * CMD_WORDS;+ const evHeader = evAt;+ evAt += EVENT_OUT_WORDS;+ const evCountAt = evAt++;+ w[evCountAt] = 0;+ const evBuf = (evAt + 1) & ~1; // an f64 record starts 8-aligned+ w[evHeader] = base + evBuf * 4;+ w[evHeader + 1] = this.eventCap * 2;+ w[evHeader + 2] = base + evCountAt * 4;+w[0] = base + queryTable * 4;w[1] = base + resTable * 4;w[2] = base + cmdBuf * 4;w[3] = this.cmdCap;w[4] = base + countAt * 4;- w[5] = 0; // events: no channel carries one yet+ w[5] = base + evHeader * 4;this.countAt_ = countAt;this.cmdAt_ = cmdBuf;+ this.evCountAt_ = evCountAt;+ this.evBufAt_ = evBuf;this.address_ = base;return base;}@@ -122,8 +144,42 @@ export class AotContext {return out;}+ /**+ * What the call SENT: each record is a writer slot then its fields, in the+ * order the manifest declares. Valid until the next `build`.+ */+ events(): { slot: number; fields: readonly number[] }[] {+ if (this.block === null) return [];+ const w = this.view_();+ const used = w[this.evCountAt_]!;+ const f64 = new Float64Array(w.buffer, w.byteOffset + this.evBufAt_ * 4,+ Math.max(0, Math.floor((w.byteLength - this.evBufAt_ * 4) / 8)));+ const out: { slot: number; fields: readonly number[] }[] = [];+ // Records are variable length, so the reader has to be told how long+ // each one is; the caller knows, from what it declared.+ for (let i = 0; i < used;) {+ const slot = f64[i]!;+ const len = this.lengthOf_(slot);+ out.push({ slot, fields: [...f64.subarray(i + 1, i + len)] });+ i += len;+ }+ return out;+ }++ /** How long one writer's record is, set by the caller before the call. */+ setRecordLengths(lengths: readonly number[]): void {+ this.lengths_ = lengths;+ }++ private lengthOf_(slot: number): number {+ return (this.lengths_[slot] ?? 0) + 1;+ }++ private lengths_: readonly number[] = [];private countAt_ = 0;private cmdAt_ = 0;+ private evCountAt_ = 0;+ private evBufAt_ = 0;private address_ = 0;/** The ctx `build` last laid out. */diff --git a/sdk/src/ecs/aot/AotDispatch.ts b/sdk/src/ecs/aot/AotDispatch.tsindex 163aa8b89..1ba4fbeff 100644--- a/sdk/src/ecs/aot/AotDispatch.ts+++ b/sdk/src/ecs/aot/AotDispatch.ts@@ -46,6 +46,7 @@ import type { AotTwin } from './AotSystems';/** No `With`/`Without` on a compiled query; the subset has no syntax for one. */const NO_FILTERS: AnyComponentDef[] = [];+const NO_RECORDS: readonly { slot: number; fields: readonly number[] }[] = [];/** What a query that named an unknown component matches. */const EMPTY_ENTITIES: readonly Entity[] = [];@@ -65,6 +66,9 @@ interface QueryPlan {/** False when a name in the manifest is not a component of this world; such* a query matches nothing rather than reading address zero. */readonly resolved: boolean;+ /** Set when this slot is an event READER: its rows are this frame's+ * payloads, so they are rebuilt every call and never reused. */+ readonly reader: { readonly event: string; readonly fields: readonly string[] } | null;}interface Plan {@@ -117,6 +121,8 @@ export class AotDispatch {this.packRows_(plan, this.world.layoutEpoch());const resources = plan.resources.map((r) => this.runtime.addresses.resourceAt(r.name) ?? 0);+ const writers = twin.decl.writers ?? [];+ this.runtime.ctx.setRecordLengths(writers.map((wr) => wr.fields.length));this.runtime.ctx.build(plan.scratch, plan.rowWords, plan.offsets, plan.counts, resources);twin.call(this.runtime.ctx.address);this.runtime.systems.noteCall();@@ -128,6 +134,16 @@ export class AotDispatch {if (r.mut) this.runtime.addresses.resourceWriteBack(r.name);}+ // What it sent. The compiled code appended numbers; the payload is rebuilt+ // from the same field list that flattened it.+ for (const rec of writers.length > 0 ? this.runtime.ctx.events() : NO_RECORDS) {+ const decl = writers.find((wr) => wr.slot === rec.slot);+ if (decl) this.runtime.addresses.sendEvent(decl.event, decl.fields, rec.fields);+ }+ // The payload blocks are valid for exactly this call: `packRows_` takes+ // one per payload per frame, and nothing else hands them back.+ this.runtime.addresses.releasePayloads();+for (const cmd of this.runtime.ctx.commands()) {// Only despawn is in the v1 record set.if (cmd.kind === CMD_DESPAWN) this.world.despawn(cmd.a as unknown as Entity);@@ -154,6 +170,9 @@ export class AotDispatch {const lists: (readonly Entity[])[] = [];for (let k = 0; k < plan.queries.length; k++) {const q = plan.queries[k];+ // A reader's rows are THIS frame's payloads. Nothing about the world's+ // layout says whether one was sent, so the epoch cannot vouch for them.+ if (q.reader) { reuse = false; lists.push(EMPTY_ENTITIES); continue; }const entities = q.resolved? this.world.queryEntities(q.comps, NO_FILTERS, NO_FILTERS, q.key, undefined, q.depIds): EMPTY_ENTITIES;@@ -167,6 +186,18 @@ export class AotDispatch {const q = plan.queries[k];plan.offsets[k] = at;plan.packedFrom[k] = lists[k]!;+ if (q.reader) {+ const payloads = this.runtime.addresses.payloadRows(q.reader.event, q.reader.fields);+ plan.scratch = grow(plan.scratch, at + payloads.length * q.width);+ for (let i = 0; i < payloads.length; i++) {+ const row = payloads[i]!;+ plan.scratch[at + i * q.width] = row[0]!;+ plan.scratch[at + i * q.width + 1] = row[1]!;+ }+ plan.counts[k] = payloads.length;+ at += payloads.length * q.width;+ continue;+ }if (!q.resolved) {plan.counts[k] = 0;continue;@@ -221,7 +252,19 @@ export class AotDispatch {private planFor_(twin: AotTwin): Plan {let plan = this.plans.get(twin);if (plan) return plan;+ const readers = new Map((twin.decl.readers ?? []).map((r) => [r.slot, r]));const queries = twin.decl.queries.map((args, k): QueryPlan => {+ const reader = readers.get(k);+ // A reader's slot declares no components: its width is the entity+ // word (always zero, nothing carries an event) and one payload+ // address, which is the shape `payloadRows` hands back.+ if (reader) {+ return {+ comps: [], resolvers: [], mutated: [], key: '', depIds: [],+ width: 2, resolved: true,+ reader: { event: reader.event, fields: reader.fields },+ };+ }const comps: AnyComponentDef[] = [];for (const a of args) {const def = this.runtime.addresses.componentNamed(a.comp);@@ -236,6 +279,7 @@ export class AotDispatch {depIds: comps.map((c) => c._id as symbol),width: 1 + comps.length,resolved,+ reader: null,};});plan = {diff --git a/sdk/src/ecs/aot/AotEvents.ts b/sdk/src/ecs/aot/AotEvents.tsnew file mode 100644index 000000000..b3c9433d7--- /dev/null+++ b/sdk/src/ecs/aot/AotEvents.ts@@ -0,0 +1,84 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file AotEvents.ts+ * @brief A frame's payloads, as memory a compiled system can walk.+ *+ * @details An event is a JS object on a bus, and compiled code reads addresses.+ * So each payload this frame is flattened into a block laid out in the+ * order the manifest declares — the same order the code reads at — and+ * the reader is handed one row per payload.+ *+ * Sending is the same trade backwards: the code appended numbers, and+ * the object is rebuilt from that field list before it goes on the bus.+ */+import { POOL_SLOT_BYTES, type PoolBlock, type PoolMemory } from '../ScriptPool';++/** What the runtime knows about an event by NAME; a manifest carries names. */+export interface EventBusAccess {+ (name: string): {+ read(): readonly unknown[];+ send(payload: unknown): void;+ } | undefined;+}++export class AotEvents {+ private readonly blocks: PoolBlock[] = [];++ constructor(private readonly memory: PoolMemory, private readonly bus: EventBusAccess) {}++ /**+ * One row per payload: `[entity, address]`, where the entity is zero because+ * nothing carries an event. The blocks live until `release`, which is the+ * end of the call — the same lifetime the row array has.+ */+ rowsFor(event: string, fields: readonly string[]): (readonly number[])[] {+ const payloads = this.bus(event)?.read() ?? [];+ const rows: number[][] = [];+ for (const payload of payloads) {+ const block = this.memory.alloc(Math.max(POOL_SLOT_BYTES, fields.length * POOL_SLOT_BYTES));+ this.blocks.push(block);+ const buffer = this.memory.current?.(block) ?? block.buffer;+ const view = new Float64Array(buffer, block.byteOffset, fields.length);+ fields.forEach((path, i) => { view[i] = numberAt(payload, path); });+ rows.push([0, block.byteOffset]);+ }+ return rows;+ }++ /** Rebuild one payload from the fields the code wrote, and put it on the bus. */+ send(event: string, fields: readonly string[], values: readonly number[]): void {+ const target = this.bus(event);+ if (!target) return;+ const payload: Record<string, unknown> = {};+ fields.forEach((path, i) => { assignAt(payload, path, values[i] ?? 0); });+ target.send(payload);+ }++ /** Give the per-call blocks back; they are only valid inside one call. */+ release(): void {+ for (const block of this.blocks) this.memory.release(block);+ this.blocks.length = 0;+ }+}++/** A dotted path read off a payload; a field it does not carry reads as 0. */+function numberAt(payload: unknown, path: string): number {+ let at: unknown = payload;+ for (const part of path.split('.')) {+ if (at === null || typeof at !== 'object') return 0;+ at = (at as Record<string, unknown>)[part];+ }+ return typeof at === 'boolean' ? (at ? 1 : 0) : (typeof at === 'number' ? at : 0);+}++/** The same path, written back — nested objects are created as needed. */+function assignAt(payload: Record<string, unknown>, path: string, value: number): void {+ const parts = path.split('.');+ let at = payload;+ for (const part of parts.slice(0, -1)) {+ if (typeof at[part] !== 'object' || at[part] === null) at[part] = {};+ at = at[part] as Record<string, unknown>;+ }+ at[parts[parts.length - 1]!] = value;+}diff --git a/sdk/src/ecs/aot/AotRuntime.ts b/sdk/src/ecs/aot/AotRuntime.tsindex bd0b52529..da60f4049 100644--- a/sdk/src/ecs/aot/AotRuntime.ts+++ b/sdk/src/ecs/aot/AotRuntime.ts@@ -28,6 +28,16 @@ export interface AotAddresses {resourceAt(name: string): number | undefined;/** Copy the mirror back, for a resource the system declared `ResMut`. */resourceWriteBack(name: string): void;+ /**+ * This frame's payloads of `event`, as rows: one per payload, each carrying+ * the address of a block laid out in `fields` order. Entity-less, because+ * an event is not carried by one.+ */+ payloadRows(event: string, fields: readonly string[]): readonly (readonly number[])[];+ /** Deliver one payload the compiled code appended, rebuilt from `fields`. */+ sendEvent(event: string, fields: readonly string[], values: readonly number[]): void;+ /** Hand back the blocks `payloadRows` took; they outlive no call. */+ releasePayloads(): void;/** The definition a manifest's component NAME refers to in this world. */componentNamed(name: string): AnyComponentDef | undefined;}diff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.tsindex da057d908..d3f1b0a26 100644--- a/sdk/src/ecs/aot/AotSystems.ts+++ b/sdk/src/ecs/aot/AotSystems.ts@@ -27,6 +27,15 @@ export interface AotSystemDecl {/** One per declared Res/ResMut. `mut` is what makes a host write the mirror* back after the call — without it the write is silently dropped. */readonly resources: readonly { name: string; mut: boolean }[];+ /**+ * Event readers, and the query slot each one's payloads go into. `fields`+ * is the payload's layout, in the order the compiled code reads it — the+ * host flattens an object into exactly that order or the code reads a+ * different field.+ */+ 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[] }[];}export interface AotManifest {diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.tsindex 24e32c2f0..f69e6e71e 100644--- a/sdk/src/ecs/aot/installAot.ts+++ b/sdk/src/ecs/aot/installAot.ts@@ -28,6 +28,7 @@ import type { Entity } from '../../types';import { WasmPoolMemory, type WasmHeap } from '../WasmPoolMemory';import { AotContext } from './AotContext';import { AotResources, type ResourceReader } from './AotResources';+import { AotEvents, type EventBusAccess } from './AotEvents';import { AotSystems, type AotManifest } from './AotSystems';import type { AotAddresses, AotRuntime } from './AotRuntime';@@ -57,6 +58,8 @@ export interface InstallAotOptions {* its first frame has no value yet and is not missing.*/readonly knowsResource?: (name: string) => boolean;+ /** The bus a manifest's event NAME refers to, for reading and for sending. */+ readonly events?: EventBusAccess;}/**@@ -94,7 +97,8 @@ export async function prepareAot(opts: Omit<InstallAotOptions, 'runner'>): Promireturn {systems,- addresses: worldAddresses(new AotResources(memory, opts.resources)),+ addresses: worldAddresses(new AotResources(memory, opts.resources),+ new AotEvents(memory, opts.events ?? (() => undefined))),ctx: new AotContext(memory),};}@@ -119,10 +123,13 @@ function componentNamed(name: string): AnyComponentDef | undefined {* COMPONENT's address is not among them: `AotDispatch` takes a resolver from the* world once per system rather than asking per row.*/-export function worldAddresses(resources: AotResources): AotAddresses {+export function worldAddresses(resources: AotResources, payloads: AotEvents): AotAddresses {return {componentNamed,resourceAt: (name: string) => resources.addressOf(name),resourceWriteBack: (name: string) => resources.writeBack(name),+ payloadRows: (event, fields) => payloads.rowsFor(event, fields),+ sendEvent: (event, fields, values) => payloads.send(event, fields, values),+ releasePayloads: () => payloads.release(),};}diff --git a/sdk/src/ecs/event.ts b/sdk/src/ecs/event.tsindex 4d19bf94e..357038fcf 100644--- a/sdk/src/ecs/event.ts+++ b/sdk/src/ecs/event.ts@@ -32,10 +32,26 @@ export interface EventDef<T> {* @public*/export function defineEvent<T>(name: string): EventDef<T> {- return {+ const def: EventDef<T> = {_id: Symbol(`Event_${name}`),_name: name,};+ // By name as well, because a compiled module's manifest carries names. The+ // FIRST wins: a second event of the same name is a different event, and+ // quietly rebinding the name would deliver one system's payloads to another.+ if (!byName.has(name)) byName.set(name, def as EventDef<unknown>);+ return def;+}++const byName = new Map<string, EventDef<unknown>>();++/**+ * The event a manifest's NAME refers to, or undefined when nothing declared it.+ *+ * @internal+ */+export function eventNamed(name: string): EventDef<unknown> | undefined {+ return byName.get(name);}// =============================================================================@@ -68,22 +84,34 @@ export class EventBus<T> {export class EventRegistry {private readonly buses_ = new Map<symbol, EventBus<unknown>>();+ /**+ * By NAME as well, because a compiled module's manifest carries names —+ * it cannot know a runtime's symbols. Registered when a bus is first made,+ * which is when a system asks for a reader or a writer.+ */+ private readonly byName_ = new Map<string, EventBus<unknown>>();register<T>(event: EventDef<T>): void {- if (!this.buses_.has(event._id)) {- this.buses_.set(event._id, new EventBus<unknown>());- }+ if (!this.buses_.has(event._id)) this.make_(event);}getBus<T>(event: EventDef<T>): EventBus<T> {- let bus = this.buses_.get(event._id);- if (!bus) {- bus = new EventBus<unknown>();- this.buses_.set(event._id, bus);- }+ const bus = this.buses_.get(event._id) ?? this.make_(event);return bus as EventBus<T>;}+ /** The bus a manifest's name refers to, or undefined if nothing made one. */+ busNamed(name: string): EventBus<unknown> | undefined {+ return this.byName_.get(name);+ }++ private make_<T>(event: EventDef<T>): EventBus<unknown> {+ const bus = new EventBus<unknown>();+ this.buses_.set(event._id, bus);+ if (event._name) this.byName_.set(event._name, bus);+ return bus;+ }+swapAll(): void {for (const bus of this.buses_.values()) {bus.swap();diff --git a/sdk/tests/aot-app.test.ts b/sdk/tests/aot-app.test.tsindex 0952b7beb..b2db130aa 100644--- a/sdk/tests/aot-app.test.ts+++ b/sdk/tests/aot-app.test.ts@@ -12,7 +12,8 @@import { describe, it, expect } from 'vitest';import { bootMockApp } from './helpers/mockApp';import {- buildAotModule, buildFadeModule, fadeManifest, fadeTaggedManifest, keyProbeC, keyProbeManifest,+ buildAotModule, buildFadeModule, eventManifest, fadeManifest, fadeTaggedManifest,+ keyProbeC, keyProbeManifest, EVENT_C,timeScaleManifest, FADE_TAGGED_C,FADE_PROBE_ALPHA, FADE_PROBE_C, TIME_SCALE_C,} from './helpers/aotFade';@@ -20,6 +21,7 @@ import { FakeEngine } from './fakeEngine';import { emccPath } from '../../build-tools/utils/emscripten.js';import { defineComponent, defineTag } from '../src/ecs/component';import { Time } from '../src/ecs/resource';+import { defineEvent, EventReader, EventWriter } from '../src/ecs/event';import { Input } from '../src/input/input';import { defineSystem, Schedule } from '../src/ecs/system';import { Query, Mut } from '../src/ecs/query';@@ -195,6 +197,53 @@ describe('an App told to run its compiled twins', () => {expect(alphas(app, Fade, unlit)).toEqual(unlit.map(() => 1));});+ it.skipIf(!EMCC)('walks the payloads a reader was given', async () => {+ const wasm = buildAotModule(EMCC!, EVENT_C, 'es_sys_Absorb');+ const { app } = bootMockApp();+ const Fade = defineComponent('Fade', { alpha: 1, step: 0.1 }) as AnyComponentDef;+ const Hit = defineEvent<{ amount: number }>('Hit');+ app.addSystemToSchedule(Schedule.Update, defineSystem(+ [EventReader(Hit), Query(Mut(Fade))], () => { /* the twin is the point */ },+ { name: 'Absorb' }));+ await app.useCompiledSystems({ host: new FakeEngine(), manifest: eventManifest('Absorb'), wasm });+ const entities = seed(app, Fade);++ // Sent before a frame, readable during it, gone from the next — and the+ // last half is what says the twin read a buffer, not a list.+ const bus = (app as unknown as { eventRegistry_: { getBus(e: unknown): { send(v: unknown): void } } })+ .eventRegistry_.getBus(Hit);+ bus.send({ amount: 3 });+ bus.send({ amount: 4 });+ await app.tick(1 / 60);+ expect(alphas(app, Fade, entities)).toEqual(entities.map(() => 7));+ await app.tick(1 / 60);+ expect(alphas(app, Fade, entities).every((a) => a === 0)).toBe(true);+ });++ it.skipIf(!EMCC)('and delivers the payloads it appended', async () => {+ const wasm = buildAotModule(EMCC!, EVENT_C, 'es_sys_Emit');+ const { app } = bootMockApp();+ const Fade = defineComponent('Fade', { alpha: 1, step: 0.1 }) as AnyComponentDef;+ const Hit = defineEvent<{ amount: number }>('Sent');+ const seen: number[] = [];+ app.addSystemToSchedule(Schedule.Update, defineSystem(+ [Query(Fade), EventWriter(Hit)], () => { /* the twin is the point */ },+ { name: 'Emit' }));+ // A reader in the same world, interpreted: what the twin sent has to+ // arrive the ordinary way or it went nowhere.+ app.addSystemToSchedule(Schedule.Update, defineSystem(+ [EventReader(Hit)], (hits) => { for (const h of hits) seen.push(h.amount); },+ { name: 'Watch' }));+ await app.useCompiledSystems({ host: new FakeEngine(), manifest: eventManifest('Emit'), wasm });+ const entities = seed(app, Fade);++ await app.tick(1 / 60);+ await app.tick(1 / 60);+ // Sent in the first frame and read in the second, on the same bus an+ // interpreted reader walks — the only way they could arrive.+ expect(seen).toEqual(entities.map((_, i) => (i + 1) * 0.1));+ });+it.skipIf(!EMCC)('refuses a module built for other shapes, and the App keeps interpreting', async () => {const { app, Fade } = fadeApp();await expect(app.useCompiledSystems({diff --git a/sdk/tests/helpers/aotFade.ts b/sdk/tests/helpers/aotFade.tsindex 32aaeea29..e2e09cdf4 100644--- a/sdk/tests/helpers/aotFade.ts+++ b/sdk/tests/helpers/aotFade.ts@@ -141,6 +141,73 @@ export function fadeTaggedManifest(): AotManifest {};}+/**+ * Two halves of one loop: `Absorb` reads a `Hit` payload and writes what it saw+ * onto every Fade; `Emit` sends one `Hit` per Fade. Together they say whether a+ * payload survives the round trip through memory in both directions.+ */+export const EVENT_C = `#include <stdint.h>+#include <string.h>+typedef uint32_t es_addr_t;+#define ES_PTR(a) ((unsigned char *)(a))+typedef struct { es_addr_t rows, count; } EsQueryRows;+typedef struct { es_addr_t buf, cap, count; } EsEventOut;+typedef struct { es_addr_t queries, resources, cmdBuf, cmdCap, cmdCount, events; } EsSysCtx;+static double ld(const unsigned char *p) { double v; memcpy(&v, p, 8); return v; }+static void st(unsigned char *p, double v) { memcpy(p, &v, 8); }++/* [EventReader(Hit), Query(Mut(Fade))] */+void es_sys_Absorb(es_addr_t ctx) {+ const EsSysCtx *c = (const EsSysCtx *)ES_PTR(ctx);+ const EsQueryRows *q = (const EsQueryRows *)ES_PTR(c->queries);+ const es_addr_t *hits = (const es_addr_t *)ES_PTR(q[0].rows);+ double total = 0.0;+ for (es_addr_t i = 0; i < q[0].count; ++i) total += ld(ES_PTR(hits[i * 2u + 1u]));+ const es_addr_t *fades = (const es_addr_t *)ES_PTR(q[1].rows);+ for (es_addr_t j = 0; j < q[1].count; ++j) st(ES_PTR(fades[j * 2u + 1u]), total);+}++/* [Query(Fade), EventWriter(Hit)] — one payload per row, writer slot 0 */+void es_sys_Emit(es_addr_t ctx) {+ const EsSysCtx *c = (const EsSysCtx *)ES_PTR(ctx);+ const EsQueryRows *q = (const EsQueryRows *)ES_PTR(c->queries);+ const es_addr_t *fades = (const es_addr_t *)ES_PTR(q[0].rows);+ const EsEventOut *ev = (const EsEventOut *)ES_PTR(c->events);+ double *buf = (double *)ES_PTR(ev->buf);+ uint32_t *at = (uint32_t *)ES_PTR(ev->count);+ uint32_t n = *at;+ for (es_addr_t j = 0; j < q[0].count; ++j) {+ if (n + 2u > (uint32_t)ev->cap) break;+ buf[n] = 0.0; /* writer slot */+ buf[n + 1u] = ld(ES_PTR(fades[j * 2u + 1u])); /* amount = alpha */+ n += 2u;+ }+ *at = n;+}+`;++/** The manifest for whichever half is being run. */+export function eventManifest(which: 'Absorb' | 'Emit'): AotManifest {+ const shapes = projectShapeDigest([{ name: 'Fade', fields: FADE_FIELDS }]);+ return which === 'Absorb'+ ? {+ engineAbi: engineAbiDigest(4), projectShapes: shapes,+ systems: [{+ name: 'Absorb', symbol: 'es_sys_Absorb', resources: [],+ queries: [[{ comp: 'Hit', mut: false }], [{ comp: 'Fade', mut: true }]],+ readers: [{ slot: 0, event: 'Hit', fields: ['amount'] }],+ }],+ }+ : {+ engineAbi: engineAbiDigest(4), projectShapes: shapes,+ systems: [{+ name: 'Emit', symbol: 'es_sys_Emit', resources: [],+ queries: [[{ comp: 'Fade', mut: false }]],+ writers: [{ slot: 0, event: 'Sent', fields: ['amount'] }],+ }],+ };+}+/** What a build writes for the probe above. */export function keyProbeManifest(): AotManifest {return {diff --git a/src/esengine/aot/estella_abi.h b/src/esengine/aot/estella_abi.hindex 35fc0c71c..7688e2ab6 100644--- a/src/esengine/aot/estella_abi.h+++ b/src/esengine/aot/estella_abi.h@@ -63,6 +63,18 @@ typedef struct EsSysCtx {/* What a host needs in order to CALL a system without glue written by hand.The compiler knows a system's queries and resources -- that is what _paramsis -- so it says so here rather than leaving each host to be told twice. */+/* Where a system APPENDS events: f64 records, because a payload is fields and+ not four words. A record is [writer slot, ...fields], and how long one is+ comes from the manifest — the host declared it.++ Its own queue rather than a wider EsCmd: fixed-width records and+ variable-width ones cannot share a buffer without stride guesswork. */+typedef struct EsEventOut {+ es_addr_t buf; /* double * */+ es_addr_t cap; /* capacity, in doubles */+ es_addr_t count; /* address of the used-doubles word */+} EsEventOut;+typedef struct EsQueryDecl {const char *const *comps; /* component names, in the order the query names them */const unsigned char *mut; /* 1 where the system may write that component */