Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(aot): events compile, in both directions

esengine04279e131824
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 to
have 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 are
running compiled and how many twin calls have happened (both
diff --git a/compiler/src/abi.ts b/compiler/src/abi.ts
index 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.ts
index 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 _params
is -- 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.ts
index 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.ts
index 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 | null
return { 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<str
if (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<str
if (!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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
index d41ec17f9..17fde38b9 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -521,8 +521,10 @@ systems: readonly AotSystemDecl[]
```
name: string
queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined
resources: 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> | undefined
getBus: <T>(event: EventDef<T>) => EventBus<T>
register: <T>(event: EventDef<T>) => void
swapAll: () => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: string
queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined
resources: 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> | undefined
getBus: <T>(event: EventDef<T>) => EventBus<T>
register: <T>(event: EventDef<T>) => void
swapAll: () => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: string
queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined
resources: 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> | undefined
getBus: <T>(event: EventDef<T>) => EventBus<T>
register: <T>(event: EventDef<T>) => void
swapAll: () => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 005de4315..f588e5734 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -516,8 +516,10 @@ systems: readonly AotSystemDecl[]
```
name: string
queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined
resources: 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> | undefined
getBus: <T>(event: EventDef<T>) => EventBus<T>
register: <T>(event: EventDef<T>) => void
swapAll: () => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e659edac0..38ba1a2dc 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -516,8 +516,10 @@ systems: readonly AotSystemDecl[]
```
name: string
queries: readonly (readonly { comp: string; mut: boolean; }[])[]
+readers: readonly { slot: number; event: string; fields: readonly string[]; }[] | undefined
resources: 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> | undefined
getBus: <T>(event: EventDef<T>) => EventBus<T>
register: <T>(event: EventDef<T>) => void
swapAll: () => void
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 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 } fr
import { 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 materialised
diff --git a/sdk/src/ecs/aot/AotContext.ts b/sdk/src/ecs/aot/AotContext.ts
index 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 words
this.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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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'>): Promi
return {
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.ts
index 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.ts
index 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.ts
index 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.h
index 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 _params
is -- 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 */