Skip to content

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

feat(ecs): a resource has one layout, and an address to read it at

yhh10853b92dbd8
diff --git a/compiler/src/abi.ts b/compiler/src/abi.ts
index a86408e35..0735360a6 100644
--- a/compiler/src/abi.ts
+++ b/compiler/src/abi.ts
@@ -18,7 +18,7 @@
* Field offsets come from PTR_LAYOUTS via builtins.ts — the same EHT
* table the engine and the SDK's accessors already agree on.
*/
-import { ehtStamp } from './builtins';
+import { ehtStamp, resourceNames } from './builtins';
import { encBytes, type CompShape, type EirSystem, type EirType, type LeafEnc, type QueryArg } from './eir';
import { runSystemOn, type EirHost, type Fns } from './interp';
@@ -449,8 +449,7 @@ export function packLayout(shapes: ReadonlyMap<string, CompShape>): AbiLayout {
}
/**
- * Which host-stored shapes are RESOURCES rather than components. This is the one
- * thing the shape cannot yet say, because resources have no generator — see the
- * note in builtins.ts. It goes away when they get one.
+ * Which host-stored shapes are RESOURCES rather than components — the SDK's own
+ * declarations, so this list has no second author to drift from.
*/
-const RESOURCES = new Set(['Time', 'Input']);
+const RESOURCES = new Set(resourceNames());
diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.ts
index 1b55f2c96..5fd4b4f7d 100644
--- a/compiler/src/builtins.ts
+++ b/compiler/src/builtins.ts
@@ -14,6 +14,7 @@
* file exists to avoid.
*/
import { PTR_LAYOUTS } from '../../sdk/src/wasm/ptrLayouts.generated';
+import { RESOURCE_NAMES, RESOURCE_SHAPES } from '../../sdk/src/ecs/resourceShapes';
import { BOOL, F64, HOST_ENC, type CompShape, type FieldSpec, type LeafEnc } from './eir';
/** Leaf member names per composite field, in memory order. Every one is f32. */
@@ -62,20 +63,33 @@ export function builtinShapes(): Map<string, CompShape> {
// engine-stored. Nothing downstream has to ask by name.
out.set(name, { name, storage: 'engine', fields });
}
- out.set('Time', TIME);
+ for (const [name, shape] of Object.entries(RESOURCE_SHAPES)) {
+ out.set(name, resourceShape(name, shape));
+ }
return out;
}
-// NOT generated. Resources have no EHT table, so this is a hand-written shape and
-// will drift the moment Time gains a field. Generating it is owed before the
-// compiler reads any resource beyond this one.
-const TIME: CompShape = {
- name: 'Time',
- storage: 'host',
- fields: new Map<string, FieldSpec>(
- ['delta', 'elapsed', 'frameCount', 'fixedDelta', 'fixedAlpha', 'fixedTick', 'scale', 'unscaledDelta']
- .map((k) => [k, { type: F64, enc: HOST_ENC, offset: null }] as const)),
-};
+/**
+ * A resource's shape, from the SDK's own declaration: a host record, so f64
+ * throughout and laid out by the ABI rather than by EHT. The field ORDER is the
+ * declaration order, and it IS the layout.
+ */
+function resourceShape(name: string, shape: Readonly<Record<string, number | boolean>>): CompShape {
+ const fields = new Map<string, FieldSpec>();
+ for (const [field, value] of Object.entries(shape)) {
+ fields.set(field, {
+ type: typeof value === 'boolean' ? BOOL : F64,
+ enc: HOST_ENC,
+ offset: null,
+ });
+ }
+ return { name, storage: 'host', fields };
+}
+
+/** Which host-stored shapes are resources; see `abi.ts`, which asks. */
+export function resourceNames(): readonly string[] {
+ return RESOURCE_NAMES;
+}
/**
* EHT's table, flattened for the §2.5 handshake. It stamps the OFFSETS rather
diff --git a/compiler/tests/pool-layout.test.ts b/compiler/tests/pool-layout.test.ts
index d82b43f9b..dd1fcd714 100644
--- a/compiler/tests/pool-layout.test.ts
+++ b/compiler/tests/pool-layout.test.ts
@@ -24,6 +24,7 @@ import { packLayout } from '../src/abi';
import { encBytes } from '../src/eir';
import { ScriptPool, poolShape, POOL_SLOT_BYTES } from '../../sdk/src/ecs/ScriptPool';
import * as sdkAbi from '../../sdk/src/ecs/aot/AotContext';
+import { RESOURCE_NAMES, resourceFields } from '../../sdk/src/ecs/resourceShapes';
import { CMD_DESPAWN, CMD_REMOVE, CMD_WORDS, QUERYROWS_WORDS, SYSCTX_WORDS } from '../src/abi';
const FIXTURE = resolve(fileURLToPath(new URL('./fixtures/in-subset.ts', import.meta.url)));
@@ -89,3 +90,27 @@ describe('the SDK and the compiler count the same words', () => {
expect(sdkAbi.CMD_REMOVE).toBe(CMD_REMOVE);
});
});
+
+/**
+ * A resource is laid out from the SAME declaration on both sides: the compiler
+ * derives its shape from it, and the SDK mirrors its values into that layout.
+ */
+describe('a resource has one layout too', () => {
+ it('the compiler knows exactly the resources the SDK declares', () => {
+ expect([...layout.resources.keys()].sort()).toEqual([...RESOURCE_NAMES].sort());
+ });
+
+ it('and lays their fields out in the order the SDK declares', () => {
+ for (const name of RESOURCE_NAMES) {
+ const fields = resourceFields(name)!;
+ const shape = layout.resources.get(name)!;
+ expect([...shape.leaves.keys()], `${name} field order`).toEqual([...fields]);
+ fields.forEach((field, i) => {
+ // The mirror writes field i at slot i; anything else and a system
+ // reading `delta` would get `elapsed`.
+ expect(shape.leaves.get(field)!.byteOffset, `${name}.${field}`)
+ .toBe(i * POOL_SLOT_BYTES);
+ });
+ }
+ });
+});
diff --git a/sdk/src/ecs/aot/AotResources.ts b/sdk/src/ecs/aot/AotResources.ts
new file mode 100644
index 000000000..6df22123d
--- /dev/null
+++ b/sdk/src/ecs/aot/AotResources.ts
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AotResources.ts
+ * @brief A resource's bytes, for code that reaches it by address.
+ *
+ * @details A resource is a host record — a JS object with no address — and a
+ * compiled system reads one at `base + offset` like anything else. So
+ * each resource a twin declares gets a block in the engine's memory and
+ * its values are written there before the call.
+ *
+ * That IS a copy, and it is the one copy this design keeps. The reason
+ * it is affordable is the shape of it: one small record per resource
+ * per system call, not one per component per entity per frame, which is
+ * the per-row cost AOT exists to delete.
+ *
+ * The layout is `resourceShapes.ts`, which is also what the compiler
+ * reads. Order is the layout, so a second list here would be a second
+ * answer — `pool-layout.test.ts` holds the two together.
+ */
+
+import { POOL_SLOT_BYTES, type PoolBlock, type PoolMemory } from '../ScriptPool';
+import { resourceFields } from '../resourceShapes';
+
+/** Reads the live value of a named resource, or undefined if the world has none. */
+export type ResourceReader = (name: string) => Readonly<Record<string, unknown>> | undefined;
+
+/**
+ * Blocks for the resources compiled systems read, refreshed on demand. One per
+ * world; a resource with no declared shape simply has no address, and a system
+ * naming it did not compile.
+ */
+export class AotResources {
+ private readonly blocks = new Map<string, PoolBlock>();
+ private readonly views = new Map<string, Float64Array>();
+
+ constructor(private readonly memory: PoolMemory, private readonly read: ResourceReader) {}
+
+ /**
+ * The address of `name`'s bytes, with this frame's values in them, or
+ * undefined when the resource has no layout or the world has no value.
+ */
+ addressOf(name: string): number | undefined {
+ const fields = resourceFields(name);
+ if (!fields) return undefined;
+ const value = this.read(name);
+ if (!value) return undefined;
+
+ let block = this.blocks.get(name);
+ if (!block) {
+ block = this.memory.alloc(fields.length * POOL_SLOT_BYTES);
+ this.blocks.set(name, block);
+ }
+ // Re-viewed rather than held: allocating anything may have grown the
+ // heap, and a grown heap detaches every view of it.
+ const buffer = this.memory.current?.(block) ?? block.buffer;
+ let view = this.views.get(name);
+ if (!view || view.buffer !== buffer) {
+ view = new Float64Array(buffer, block.byteOffset, fields.length);
+ this.views.set(name, view);
+ }
+ fields.forEach((field, i) => {
+ const v = value[field];
+ view![i] = typeof v === 'boolean' ? (v ? 1 : 0) : (typeof v === 'number' ? v : 0);
+ });
+ return block.byteOffset;
+ }
+
+ dispose(): void {
+ for (const block of this.blocks.values()) this.memory.release(block);
+ this.blocks.clear();
+ this.views.clear();
+ }
+}
diff --git a/sdk/src/ecs/resource.ts b/sdk/src/ecs/resource.ts
index 481f864a7..71ffbb6da 100644
--- a/sdk/src/ecs/resource.ts
+++ b/sdk/src/ecs/resource.ts
@@ -6,6 +6,7 @@
*/
import { deepClone } from '../util/deepClone';
+import { RESOURCE_SHAPES } from './resourceShapes';
// =============================================================================
// Resource Definition
@@ -276,14 +277,5 @@ export interface TimeData {
*
* @public
*/
-export const Time = defineResource<TimeData>({
- delta: 0,
- elapsed: 0,
- frameCount: 0,
- fixedDelta: 1 / 60,
- fixedAlpha: 0,
- fixedTick: 0,
- scale: 1,
- unscaledDelta: 0,
-}, 'Time');
+export const Time = defineResource<TimeData>({ ...RESOURCE_SHAPES.Time }, 'Time');
diff --git a/sdk/src/ecs/resourceShapes.ts b/sdk/src/ecs/resourceShapes.ts
new file mode 100644
index 000000000..6f6023072
--- /dev/null
+++ b/sdk/src/ecs/resourceShapes.ts
@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file resourceShapes.ts
+ * @brief The built-in resources a compiled system can read, and their fields.
+ *
+ * @details A compiled system reaches a resource by ADDRESS, so its fields need a
+ * layout, and a layout needs exactly one author. This is that author:
+ * `resource.ts` builds the resource from it, and the AOT compiler reads
+ * it for the offsets (docs/REARCH_AOT_ABI.md §2.4).
+ *
+ * A resource belongs here when every field is a number or a boolean —
+ * the same bar `defineComponent` shapes meet, and for the same reason:
+ * anything else has no fixed width. `Input` is deliberately absent; it
+ * is a class with methods, so there is nothing to lay out.
+ *
+ * Order is the layout. Adding a field in the middle moves every field
+ * after it, which is why this list is the thing that changes and not a
+ * copy of it somewhere else.
+ *
+ * NO IMPORTS. A build tool reads this without pulling in the engine.
+ */
+
+/** Field defaults per resource, in declaration order. */
+export const RESOURCE_SHAPES = {
+ Time: {
+ delta: 0,
+ elapsed: 0,
+ frameCount: 0,
+ fixedDelta: 1 / 60,
+ fixedAlpha: 0,
+ fixedTick: 0,
+ scale: 1,
+ unscaledDelta: 0,
+ },
+} as const satisfies Record<string, Readonly<Record<string, number | boolean>>>;
+
+/** Names of the resources with a layout — what tells a host shape from a component. */
+export const RESOURCE_NAMES: readonly string[] = Object.keys(RESOURCE_SHAPES);
+
+/** The fields of `name`, in layout order, or null if it has no layout. */
+export function resourceFields(name: string): readonly string[] | null {
+ const shape = (RESOURCE_SHAPES as Record<string, Record<string, unknown>>)[name];
+ return shape ? Object.keys(shape) : null;
+}
diff --git a/sdk/tests/aot-context.test.ts b/sdk/tests/aot-context.test.ts
index ce9bb717e..c30139db5 100644
--- a/sdk/tests/aot-context.test.ts
+++ b/sdk/tests/aot-context.test.ts
@@ -26,6 +26,7 @@ import { fileURLToPath } from 'node:url';
import { ScriptPool, poolShape } from '../src/ecs/ScriptPool';
import { WasmPoolMemory, type WasmHeap } from '../src/ecs/WasmPoolMemory';
import { AotContext, CMD_DESPAWN } from '../src/ecs/aot/AotContext';
+import { AotResources } from '../src/ecs/aot/AotResources';
import type { Entity } from '../src/types';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
@@ -150,15 +151,18 @@ describe('a compiled system, called by the SDK', () => {
live.push(i);
}
- // Time is a host record too, so it needs an address like anything else.
- const timeBlock = memory.alloc(8);
+ // Time is a host record too, so it needs an address like anything else —
+ // and the mirror is what gives it one, in the layout both sides derive
+ // from the SDK's own declaration.
const delta = 1 / 30;
- new Float64Array(engine.memory.buffer, timeBlock.byteOffset, 1)[0] = delta;
+ const time = { delta, elapsed: 0, frameCount: 0, fixedDelta: 1 / 60,
+ fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 };
+ const resources = new AotResources(memory, (name) => (name === 'Time' ? time : undefined));
const ctx = new AotContext(memory);
for (let f = 0; f < FRAMES; f++) {
const rows = live.map((id) => [id, pool.address(e(id))!] as const);
- const at = ctx.build([rows], [timeBlock.byteOffset]);
+ const at = ctx.build([rows], [resources.addressOf('Time')!]);
decay(at);
// The same loop, in TypeScript, over the plain objects.
@@ -202,12 +206,11 @@ describe('a compiled system, called by the SDK', () => {
const api = instance.exports as unknown as Record<string, unknown>;
(api['_initialize'] as (() => void) | undefined)?.();
- const timeBlock = memory.alloc(8);
- new Float64Array(engine.memory.buffer, timeBlock.byteOffset, 1)[0] = 1 / 30;
+ const resources = new AotResources(memory, () => ({ delta: 1 / 30 }));
const ctx = new AotContext(memory);
// An empty query still needs a well-formed table: `count` is zero and
// `rows` must point somewhere the code will not read.
- (api['es_sys_Decay'] as (c: number) => void)(ctx.build([[]], [timeBlock.byteOffset]));
+ (api['es_sys_Decay'] as (c: number) => void)(ctx.build([[]], [resources.addressOf('Time')!]));
expect(ctx.commands()).toEqual([]);
});
});