A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(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.tsindex 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.tsindex 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 ratherdiff --git a/compiler/tests/pool-layout.test.ts b/compiler/tests/pool-layout.test.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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([]);});});