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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file BuiltinBridge.ts
* @brief C++ Registry integration layer for builtin components
*/
import { Entity } from '../../types';
import { mergeIntoDefaults } from '../component';
import type { BuiltinComponentDef } from '../component';
import type { CppRegistry, ESEngineModule } from '../../wasm';
import { validateComponentData, formatValidationErrors } from '../../util/validation';
import { handleWasmError } from '../../wasm/wasmError';
import { installAbortGuard, throwIfModuleAborted, isModuleAborted, WasmModuleAborted } from '../../wasm/moduleHealth';
import { COMPONENT_META, ABI_LAYOUT_HASH } from '../component.generated';
import { PTR_ACCESSORS } from './ptrAccessors.generated';
import { hasOwn } from '../../util/ownProperties';
import { reorderSetByRank, type RankOf } from '../entityOrder';
import {
type MemoryProvider, type ComponentHeap,
WasmMemoryProvider, resolveWasmPtrFn,
} from './memoryProvider';
// =============================================================================
// Color conversion helpers
// =============================================================================
/**
* Rewrite color-typed fields from the WASM {x,y,z,w} shape into the SDK
* {r,g,b,a} shape. The outer object comes fresh from embind on every
* Registry method call and has no outside aliases, so we mutate it in
* place; the inner color objects are likewise fresh. Setting r/g/b/a
* on the same object leaves ghost x/y/z/w properties, but consumers
* only read r/g/b/a — net zero allocations per get().
*/
export function convertFromWasm(
obj: Record<string, unknown>,
colorKeys: readonly string[],
): Record<string, unknown> {
if (colorKeys.length === 0) return obj;
for (const key of colorKeys) {
const val = obj[key] as { x?: number; y?: number; z?: number; w?: number } & Record<string, unknown> | null | undefined;
if (val && typeof val === 'object') {
(val as { r: unknown }).r = val.x;
(val as { g: unknown }).g = val.y;
(val as { b: unknown }).b = val.z;
(val as { a: unknown }).a = val.w;
}
}
return obj;
}
/**
* The SDK's {r,g,b,a} colour fields in the WASM {x,y,z,w} shape, as a new object:
* @p obj is left as it was. It can be a Mut row, which the game still holds and
* which is written back more than once; rewritten in place, its colour had no `r`
* the second time and every channel crossed as NaN (issue #107).
*/
export function convertForWasm(
obj: Record<string, unknown>,
colorKeys: readonly string[],
): Record<string, unknown> {
if (colorKeys.length === 0) return obj;
const out = { ...obj };
for (const key of colorKeys) {
const val = obj[key] as { r?: number; g?: number; b?: number; a?: number } | null | undefined;
if (val && typeof val === 'object') {
out[key] = { x: val.r, y: val.g, z: val.b, w: val.a };
}
}
return out;
}
/** An embind std::vector, which its owner has to free. */
interface WasmVector { push_back(v: number): void; delete(): void }
/** The read side of one: what a component's list field comes back as. */
interface WasmVectorRead { size(): number; get(i: number): number; delete(): void }
/**
* Replace a LIST of entities with the vector embind expects, returning the ones
* created so the caller can free them — an embind vector is a heap object.
* The boundary the colours above cross: a JS array is what a document stores,
* `std::vector<Entity>` is what the component holds.
*/
export function materializeEntityVectors(
obj: Record<string, unknown>, entityFields: readonly string[],
module: { VectorEntity?: new () => WasmVector } | null,
): WasmVector[] {
const made: WasmVector[] = [];
if (!module?.VectorEntity) return made;
for (const key of entityFields) {
const val = obj[key];
if (!Array.isArray(val)) continue;
const vec = new module.VectorEntity();
for (const e of val) vec.push_back(Number(e) >>> 0);
obj[key] = vec;
made.push(vec);
}
return made;
}
/**
* Replace a list of NUMBERS with the vector embind expects, returning the ones
* created so the caller can free them. The same boundary
* {@link materializeEntityVectors} crosses, for values rather than references.
*/
export function materializeNumberVectors(
obj: Record<string, unknown>, fields: readonly string[],
module: { VectorFloat?: new () => WasmVector } | null,
): WasmVector[] {
const made: WasmVector[] = [];
if (!module?.VectorFloat) return made;
for (const key of fields) {
const val = obj[key];
if (!Array.isArray(val)) continue;
const vec = new module.VectorFloat();
for (const n of val) vec.push_back(Number(n));
obj[key] = vec;
made.push(vec);
}
return made;
}
/**
* Which of a builtin's fields hold a list of numbers. Read off the generated
* metadata rather than carried on the component definition: that definition is
* a public type, and how a field crosses THIS boundary is not part of it.
*/
export function numberListFieldsOf(cppName: string): readonly string[] {
return (COMPONENT_META[cppName]?.numberListFields ?? []) as readonly string[];
}
/**
* A component's list fields — numbers or entities — as JS arrays, the embind
* vectors freed; a non-vector field is left as it is. Here and not at the caller:
* a vector leaks unless freed, and only some emsdk versions make it iterable.
*/
export function snapshotVectors(
obj: Record<string, unknown>, fields: readonly string[],
): Record<string, unknown> {
for (const key of fields) {
const vec = obj[key] as WasmVectorRead | undefined;
if (!vec || typeof vec.size !== 'function') continue;
const out: number[] = [];
for (let i = 0; i < vec.size(); i++) out.push(vec.get(i));
obj[key] = out;
vec.delete();
}
return obj;
}
/** A builtin as embind hands it back, made into what the rest of the SDK reads:
* its lists as arrays (the vectors freed) and its colours converted. */
export function builtinFromWasm(raw: unknown, component: BuiltinComponentDef<any>): unknown {
return convertFromWasm(
snapshotVectors(raw as Record<string, unknown>,
[...numberListFieldsOf(component._cppName), ...component.entityFields]),
component.colorKeys,
);
}
// =============================================================================
// Pointer-based Field Access
// =============================================================================
type PtrFieldType = 'f32' | 'i32' | 'u32' | 'bool' | 'u8' | 'vec2' | 'vec3' | 'vec4' | 'quat' | 'color';
interface PtrFieldDesc {
readonly name: string;
readonly type: PtrFieldType;
readonly offset: number;
}
function fieldByteSize(type: PtrFieldType): number {
switch (type) {
case 'f32': case 'i32': case 'u32': return 4;
case 'bool': case 'u8': return 1;
case 'vec2': return 8;
case 'vec3': return 12;
case 'vec4': case 'quat': case 'color': return 16;
}
}
function assertPtrInBounds(heapByteLength: number, byteOff: number, size: number): void {
if (byteOff < 0 || byteOff + size > heapByteLength) {
throw new RangeError(
`WASM pointer field access out of bounds: offset ${String(byteOff)} + size ${String(size)} ` +
`exceeds heap byteLength ${String(heapByteLength)} (typed-array detached, or C++ returned a stale pointer)`,
);
}
}
export function readPtrField(
f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
ptr: number, field: PtrFieldDesc,
): unknown {
const byteOff = ptr + field.offset;
assertPtrInBounds(u8.byteLength, byteOff, fieldByteSize(field.type));
const idx = byteOff >> 2;
switch (field.type) {
case 'f32': return f32[idx];
case 'i32': return u32[idx] | 0;
case 'u32': return u32[idx];
case 'bool': return u8[byteOff] !== 0;
case 'u8': return u8[byteOff];
case 'vec2': return { x: f32[idx], y: f32[idx + 1] };
case 'vec3': return { x: f32[idx], y: f32[idx + 1], z: f32[idx + 2] };
case 'vec4':
case 'quat': return { x: f32[idx], y: f32[idx + 1], z: f32[idx + 2], w: f32[idx + 3] };
case 'color': return { r: f32[idx], g: f32[idx + 1], b: f32[idx + 2], a: f32[idx + 3] };
}
}
interface XY { x: number; y: number }
interface XYZ { x: number; y: number; z: number }
interface XYZW { x: number; y: number; z: number; w: number }
interface RGBA { r: number; g: number; b: number; a: number }
export function fillPtrFields(
f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
ptr: number, fields: readonly PtrFieldDesc[], target: Record<string, unknown>,
): void {
// One bounds check for the whole struct: compute the maximum byte extent
// across all fields and verify against the heap view once.
let maxEnd = 0;
for (let i = 0; i < fields.length; i++) {
const f = fields[i];
const end = f.offset + fieldByteSize(f.type);
if (end > maxEnd) maxEnd = end;
}
if (maxEnd > 0) assertPtrInBounds(u8.byteLength, ptr, maxEnd);
for (let i = 0; i < fields.length; i++) {
const field = fields[i];
const byteOff = ptr + field.offset;
const idx = byteOff >> 2;
switch (field.type) {
case 'f32': target[field.name] = f32[idx]; break;
case 'i32': target[field.name] = u32[idx] | 0; break;
case 'u32': target[field.name] = u32[idx]; break;
case 'bool': target[field.name] = u8[byteOff] !== 0; break;
case 'u8': target[field.name] = u8[byteOff]; break;
case 'vec2': {
const v = target[field.name] as XY;
v.x = f32[idx]; v.y = f32[idx + 1];
break;
}
case 'vec3': {
const v = target[field.name] as XYZ;
v.x = f32[idx]; v.y = f32[idx + 1]; v.z = f32[idx + 2];
break;
}
case 'vec4':
case 'quat': {
const v = target[field.name] as XYZW;
v.x = f32[idx]; v.y = f32[idx + 1]; v.z = f32[idx + 2]; v.w = f32[idx + 3];
break;
}
case 'color': {
const v = target[field.name] as RGBA;
v.r = f32[idx]; v.g = f32[idx + 1]; v.b = f32[idx + 2]; v.a = f32[idx + 3];
break;
}
}
}
}
export function createPreallocatedResult(fields: readonly PtrFieldDesc[]): Record<string, unknown> {
const obj: Record<string, unknown> = {};
for (const f of fields) {
switch (f.type) {
case 'vec2': obj[f.name] = { x: 0, y: 0 }; break;
case 'vec3': obj[f.name] = { x: 0, y: 0, z: 0 }; break;
case 'vec4':
case 'quat': obj[f.name] = { x: 0, y: 0, z: 0, w: 0 }; break;
case 'color': obj[f.name] = { r: 0, g: 0, b: 0, a: 0 }; break;
default: obj[f.name] = null; break;
}
}
return obj;
}
export type PtrFieldValue = number | boolean | XY | XYZ | XYZW | RGBA;
export function writePtrField(
f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
ptr: number, field: PtrFieldDesc, value: PtrFieldValue | unknown,
): void {
const byteOff = ptr + field.offset;
assertPtrInBounds(u8.byteLength, byteOff, fieldByteSize(field.type));
const idx = byteOff >> 2;
switch (field.type) {
case 'f32': f32[idx] = value as number; break;
case 'i32': u32[idx] = (value as number) | 0; break;
case 'u32': u32[idx] = value as number; break;
case 'bool': u8[byteOff] = value ? 1 : 0; break;
case 'u8': u8[byteOff] = value as number; break;
case 'vec2': { const v = value as XY; f32[idx] = v.x; f32[idx + 1] = v.y; break; }
case 'vec3': { const v = value as XYZ; f32[idx] = v.x; f32[idx + 1] = v.y; f32[idx + 2] = v.z; break; }
case 'vec4':
case 'quat': { const v = value as XYZW; f32[idx] = v.x; f32[idx + 1] = v.y; f32[idx + 2] = v.z; f32[idx + 3] = v.w; break; }
case 'color': { const v = value as RGBA; f32[idx] = v.r; f32[idx + 1] = v.g; f32[idx + 2] = v.b; f32[idx + 3] = v.a; break; }
}
}
// =============================================================================
// BuiltinMethods
// =============================================================================
export interface BuiltinMethods {
add: (e: Entity, d: unknown) => void;
get: (e: Entity) => unknown;
has: (e: Entity) => boolean;
remove: (e: Entity) => void;
}
/** Result of verifying a connected C++ Registry against the generated metadata. */
export interface BridgeVerification {
/** True when every component in COMPONENT_META has all four methods. */
readonly ok: boolean;
/** List of components with missing bindings (empty when ok). */
readonly missing: readonly { readonly name: string; readonly methods: readonly string[] }[];
/**
* Components reported by the WASM module's reflection table
* (`getBuiltinComponentNames`) that are not present in the shipped
* COMPONENT_META — the WASM was built from a newer schema than the SDK
* bundle. Only populated when the module exposes the reflection call.
*/
readonly wasmOnly: readonly string[];
/**
* Components declared in COMPONENT_META that the WASM module's reflection
* table does not list — the SDK was built from a newer schema than the
* WASM. Only populated when the module exposes the reflection call.
*/
readonly sdkOnly: readonly string[];
/**
* Set when the WASM module reports an ABI layout hash
* (`getAbiLayoutHash`) that differs from the SDK bundle's
* {@link ABI_LAYOUT_HASH}. A mismatch means the loaded WASM and this SDK
* were generated from different component schemas, so the byte offsets the
* SDK uses for fast pointer access read the wrong memory. This is always
* fatal — never tolerated even in non-strict mode. Null when the hashes
* match or the module predates the handshake (no `getAbiLayoutHash`).
*/
readonly abiMismatch: { readonly sdk: string; readonly wasm: string } | null;
}
/** Options for {@link BuiltinBridge.connect}. */
export interface BridgeConnectOptions {
/**
* When true (recommended for production), verify every component in
* COMPONENT_META against the registry at connect time and throw a single
* aggregated diagnostic if any bindings are missing. When false (default,
* legacy-compatible), pre-populate the method cache for whatever bindings
* exist and let per-component lookups throw on demand — this keeps
* partial mock registries used in unit tests working unchanged.
*/
readonly strict?: boolean;
/**
* Fast-path memory backend. Omit on web/emscripten: `connect` derives a
* {@link WasmMemoryProvider} from `module`. The native (embedded-Dawn) runtime
* injects a {@link NativeMemoryProvider} here — there is no wasm module, so the
* bridge reaches components through the host's `es_<Component>_buffer` bindings.
*/
readonly memory?: MemoryProvider;
/**
* The world-transform composition seam, for a core with no emscripten module.
* `epoch` is a one-word view over the engine's staleness counter and `ensure`
* composes; the web build reads both off `module`. Without it a producer's
* announcement goes nowhere and nothing ever recomposes.
*/
readonly transformComposition?: TransformComposition;
}
/** The two halves of the composition seam a core has to expose. */
export interface TransformComposition {
readonly epoch: Uint32Array;
ensure(): void;
/** Optional third: what the last composition changed. A core that cannot
* report it leaves every consumer to rebuild, which is a capability
* difference and not a failure. */
setChangeTracking?(on: boolean): void;
compositionChanges?(): NativeComposition;
takeChanges?(): void;
}
/** What a core answers about the compositions since the last acknowledgement. */
export interface NativeComposition {
readonly serial: number;
readonly tracking: boolean;
readonly overflowed: boolean;
readonly count: number;
readonly visited: number;
readonly changed: ArrayBuffer | null;
}
/**
* The pending change set, as a consumer reads it. `overflowed` means it grew
* past the point where reading the world again is cheaper, so it was dropped —
* rebuild rather than apply.
*/
export interface CompositionDelta {
readonly serial: number;
readonly changed: Uint32Array;
readonly visited: number;
readonly overflowed: boolean;
/** Whether anything is asking for the set at all. */
readonly tracking: boolean;
}
/** One allocation for every core's empty answer. */
const EMPTY_CHANGED = new Uint32Array(0);
const METHOD_PREFIXES = ['add', 'get', 'has', 'remove'] as const;
function formatBridgeDiagnostic(v: BridgeVerification): string {
const parts: string[] = [];
if (v.abiMismatch) {
parts.push(
`ABI layout hash mismatch: the WASM module was built from a different ` +
`component schema than this SDK bundle.\n` +
` SDK ABI_LAYOUT_HASH = ${v.abiMismatch.sdk}\n` +
` WASM getAbiLayoutHash() = ${v.abiMismatch.wasm}\n` +
` Fast pointer accessors would read the wrong bytes. This is fatal.`,
);
}
if (v.missing.length > 0) {
const detail = v.missing.map(m => ` - ${m.name}: missing ${m.methods.join(', ')}`).join('\n');
parts.push(`C++ Registry is missing ${String(v.missing.length)} builtin component binding(s):\n${detail}`);
}
if (v.wasmOnly.length > 0) {
parts.push(`WASM exposes components not in the SDK's COMPONENT_META:\n ${v.wasmOnly.join(', ')}`);
}
if (v.sdkOnly.length > 0) {
parts.push(`SDK's COMPONENT_META lists components the WASM does not export:\n ${v.sdkOnly.join(', ')}`);
}
parts.push(
'Likely cause: WebBindings.generated.cpp is out of sync with component.generated.ts. ' +
'Rerun the EHT generator and rebuild the WASM target.',
);
return parts.join('\n\n');
}
// =============================================================================
// BuiltinBridge
// =============================================================================
export class BuiltinBridge {
private cppRegistry_: CppRegistry | null = null;
private module_: ESEngineModule | null = null;
private transformEpochWord_ = -1;
private transformComposition_: TransformComposition | null = null;
private memory_: MemoryProvider | null = null;
private builtinMethodCache_ = new Map<string, BuiltinMethods>();
private extraMethodCache_ = new Map<string, BuiltinMethods>();
private builtinEntitySets_ = new Map<string, Set<Entity>>();
/**
* Bind to a C++ Registry.
*
* Production call sites should pass `{ strict: true }` so the bridge
* verifies that every component declared in COMPONENT_META has its four
* bindings (add/get/has/remove) and throws a single aggregated diagnostic
* if any are missing. This surfaces drift between the WASM build and the
* generated metadata at startup rather than on first component use.
*
* In non-strict mode (default, used by unit tests with partial mock
* registries) the cache is pre-populated for whatever bindings exist and
* individual `getBuiltinMethods()` calls throw lazily on missing ones.
*/
connect(
cppRegistry: CppRegistry,
module?: ESEngineModule,
options: BridgeConnectOptions = {},
): void {
this.cppRegistry_ = cppRegistry;
this.module_ = module ?? null;
// The ADDRESS is stable; the view over it is not. Emscripten replaces
// every HEAP view when memory grows, and a cached one writes nowhere
// while looking like it worked — so only the word offset is kept.
this.transformEpochWord_ = module?.transform_epochAddress
? module.transform_epochAddress() >>> 2
: -1;
// A native core has no module to read either half off, so it hands them
// over: without this the epoch is unreachable from here and a world moved
// only from script never recomposes.
this.transformComposition_ = options.transformComposition ?? null;
// Web derives a wasm-HEAP backend from the module; the native runtime
// injects its own (es_<Component>_buffer). No module and no override => no
// fast path (resolvePtr* return null), exactly as before.
this.memory_ = options.memory
?? (module ? new WasmMemoryProvider(module, cppRegistry) : null);
this.builtinMethodCache_.clear();
this.extraMethodCache_.clear();
this.builtinEntitySets_.clear();
// Install the terminal-abort guard so a C++ abort flips the module-dead
// flag and subsequent boundary calls short-circuit (see moduleHealth.ts).
if (module) {
installAbortGuard(module);
}
const verification = this.verifyAgainst_(cppRegistry, module);
// An ABI hash mismatch is ALWAYS fatal, even in non-strict mode: the
// loaded WASM and this SDK disagree on byte layout, so any fast-path
// pointer access silently corrupts memory. Other drift (missing
// bindings) is only fatal under strict mode so partial mock registries
// in unit tests keep working. Mock registries never expose
// getAbiLayoutHash, so they never hit the fatal path.
if (verification.abiMismatch || (options.strict && !verification.ok)) {
this.cppRegistry_ = null;
this.module_ = null;
this.memory_ = null;
this.builtinMethodCache_.clear();
this.extraMethodCache_.clear();
throw new Error(formatBridgeDiagnostic(verification));
}
}
disconnect(): void {
this.cppRegistry_ = null;
this.module_ = null;
this.memory_ = null;
this.transformComposition_ = null;
this.transformEpochWord_ = -1;
this.builtinMethodCache_.clear();
this.extraMethodCache_.clear();
this.builtinEntitySets_.clear();
}
/**
* Say that composed world transforms are stale. Called for a write to a
* local transform field or to the hierarchy — never for `worldPosition` and
* friends, which are the composition's own output.
*/
invalidateTransformComposition(): void {
const injected = this.transformComposition_;
if (injected) {
injected.epoch[0] = (injected.epoch[0]! + 1) >>> 0;
return;
}
if (this.transformEpochWord_ < 0) return;
const heap = this.module_?.HEAPU32;
if (!heap) return;
heap[this.transformEpochWord_] = (heap[this.transformEpochWord_] + 1) >>> 0;
}
/** Compose if any producer invalidated since the last one; O(1) otherwise. */
ensureTransformsComposed(): void {
if (this.transformComposition_) { this.transformComposition_.ensure(); return; }
if (!this.cppRegistry_) return;
this.module_?.transform_ensureComposed?.(this.cppRegistry_);
}
/**
* Ask composition to record which entities' output changed. Answers whether
* this core can: one that cannot leaves a consumer to rebuild every time.
*/
setTransformChangeTracking(on: boolean): boolean {
const injected = this.transformComposition_;
if (injected) {
if (!injected.setChangeTracking || !injected.compositionChanges) return false;
injected.setChangeTracking(on);
return true;
}
const set = this.module_?.transform_setChangeTracking;
if (!set || !this.module_?.transform_compositionChanges) return false;
set.call(this.module_, on);
return true;
}
/**
* What every composition since the last acknowledgement changed, or null from
* a core that cannot report. The ids VIEW engine memory and the next
* composition may move it, so a consumer reads, applies and acknowledges
* within one turn.
*/
compositionChanges(): CompositionDelta | null {
const injected = this.transformComposition_;
if (injected?.compositionChanges) {
const raw = injected.compositionChanges();
return {
serial: raw.serial,
visited: raw.visited,
overflowed: raw.overflowed,
tracking: raw.tracking,
changed: raw.changed ? new Uint32Array(raw.changed, 0, raw.count) : EMPTY_CHANGED,
};
}
const read = this.module_?.transform_compositionChanges;
if (!read || !this.module_) return null;
const raw = read.call(this.module_);
return {
serial: raw.serial,
visited: raw.visited,
overflowed: raw.overflowed,
tracking: raw.tracking,
// Rebuilt every call: growing the heap detaches the previous view.
changed: raw.count > 0
? new Uint32Array(this.module_.HEAPU32.buffer, raw.ptr, raw.count)
: EMPTY_CHANGED,
};
}
/** Acknowledge the pending set: it starts again. */
takeCompositionChanges(): void {
const injected = this.transformComposition_;
if (injected?.takeChanges) { injected.takeChanges(); return; }
this.module_?.transform_takeChanges?.();
}
/** @internal What the staleness counter reads, for the fixtures that assert
* a producer notified. */
transformEpoch(): number {
if (this.transformComposition_) return this.transformComposition_.epoch[0]!;
const heap = this.module_?.HEAPU32;
return this.transformEpochWord_ < 0 || !heap ? -1 : heap[this.transformEpochWord_];
}
get hasCpp(): boolean {
return this.cppRegistry_ !== null;
}
getCppRegistry(): CppRegistry | null {
return this.cppRegistry_;
}
getWasmModule(): ESEngineModule | null {
return this.module_;
}
/**
* Describe the current binding state without throwing. Useful for
* diagnostics and tests that want to inspect coverage.
*/
verify(): BridgeVerification {
if (!this.cppRegistry_) {
return {
ok: false,
missing: [{ name: '<registry>', methods: ['connect() not called'] }],
wasmOnly: [],
sdkOnly: [],
abiMismatch: null,
};
}
return this.verifyAgainst_(this.cppRegistry_, this.module_ ?? undefined);
}
private verifyAgainst_(reg: CppRegistry, module?: ESEngineModule): BridgeVerification {
const missing: { name: string; methods: string[] }[] = [];
for (const cppName of Object.keys(COMPONENT_META)) {
const missingMethods: string[] = [];
for (const prefix of METHOD_PREFIXES) {
const fn = reg[`${prefix}${cppName}`];
if (typeof fn !== 'function') missingMethods.push(`${prefix}${cppName}`);
}
if (missingMethods.length > 0) {
missing.push({ name: cppName, methods: missingMethods });
continue;
}
this.resolveAndCache_(reg, cppName);
}
// Cross-check against the WASM module's self-reported component list
// (added in the EHT generator as `getBuiltinComponentNames`). Older
// WASM builds may not expose it — those skip this check.
let wasmOnly: string[] = [];
let sdkOnly: string[] = [];
const listFn = (module as unknown as { getBuiltinComponentNames?: () => string[] } | undefined)
?.getBuiltinComponentNames;
if (typeof listFn === 'function') {
let wasmList: string[];
try {
wasmList = listFn();
} catch {
wasmList = [];
}
const sdkSet = new Set(Object.keys(COMPONENT_META));
const wasmSet = new Set(wasmList);
wasmOnly = wasmList.filter(n => !sdkSet.has(n));
sdkOnly = Object.keys(COMPONENT_META).filter(n => !wasmSet.has(n));
}
// ABI layout-hash handshake. The WASM module exposes the digest EHT
// baked into both sides from one schema parse; if it disagrees with the
// SDK's ABI_LAYOUT_HASH, the pointer offsets the SDK ships do not match
// the loaded binary and fast-path reads/writes would corrupt memory.
// Modules built before the handshake (no getAbiLayoutHash) skip it.
let abiMismatch: { sdk: string; wasm: string } | null = null;
const hashFn = (module as unknown as { getAbiLayoutHash?: () => string } | undefined)
?.getAbiLayoutHash;
if (typeof hashFn === 'function') {
let wasmHash = '';
try {
wasmHash = hashFn();
} catch {
wasmHash = '';
}
if (wasmHash && wasmHash !== ABI_LAYOUT_HASH) {
abiMismatch = { sdk: ABI_LAYOUT_HASH, wasm: wasmHash };
}
}
const ok = missing.length === 0 && wasmOnly.length === 0
&& sdkOnly.length === 0 && abiMismatch === null;
return { ok, missing, wasmOnly, sdkOnly, abiMismatch };
}
getBuiltinMethods(cppName: string): BuiltinMethods {
const cached = this.builtinMethodCache_.get(cppName);
if (cached) return cached;
if (!this.cppRegistry_) {
throw new Error(`BuiltinBridge.getBuiltinMethods("${cppName}") called before connect().`);
}
// Fallback for components not declared in COMPONENT_META — user-defined
// builtins and test-only synthetic components. Production components are
// resolved eagerly in verifyAgainst_ and never hit this path.
return this.resolveAndCache_(this.cppRegistry_, cppName);
}
private resolveAndCache_(reg: CppRegistry, cppName: string): BuiltinMethods {
const addFn = reg[`add${cppName}`];
const getFn = reg[`get${cppName}`];
const hasFn = reg[`has${cppName}`];
const removeFn = reg[`remove${cppName}`];
if (typeof addFn !== 'function' || typeof getFn !== 'function' ||
typeof hasFn !== 'function' || typeof removeFn !== 'function') {
throw new Error(
`C++ Registry missing methods for component "${cppName}". ` +
`Expected: add${cppName}, get${cppName}, has${cppName}, remove${cppName}`,
);
}
// Gate every boundary call through the module-abort guard at this single
// chokepoint: refuse to call a dead module (pre-check), and if a call
// itself aborts the module, surface it as a fatal WasmModuleAborted
// rather than letting the corpse return undefined memory.
const guard = <A extends unknown[], R>(op: string, fn: (...a: A) => R): ((...a: A) => R) => {
return (...a: A): R => {
throwIfModuleAborted(this.module_, `${op}${cppName}`);
try {
return fn(...a);
} catch (err) {
if (isModuleAborted(this.module_)) {
throw new WasmModuleAborted(`${op}${cppName}`, undefined, err);
}
throw err;
}
};
};
const methods: BuiltinMethods = {
add: guard('add', (addFn as (e: Entity, d: unknown) => void).bind(reg)),
get: guard('get', (getFn as (e: Entity) => unknown).bind(reg)),
has: guard('has', (hasFn as (e: Entity) => boolean).bind(reg)),
remove: guard('remove', (removeFn as (e: Entity) => void).bind(reg)),
};
this.builtinMethodCache_.set(cppName, methods);
if (!hasOwn(COMPONENT_META, cppName)) this.extraMethodCache_.set(cppName, methods);
return methods;
}
/** @internal One core call for all generated builtin memberships, when supported. */
componentNames(entity: Entity): string[] | null {
const registry = this.cppRegistry_;
if (!registry?.getBuiltinComponentNames) return null;
throwIfModuleAborted(this.module_, 'getBuiltinComponentNames');
try {
const names = registry.getBuiltinComponentNames(entity);
if (typeof names !== 'string') return null;
return names ? names.split('|') : [];
} catch (err) {
if (isModuleAborted(this.module_)) {
throw new WasmModuleAborted('getBuiltinComponentNames', undefined, err);
}
throw err;
}
}
/** @internal Bindings outside the generated membership query. */
getExtraMethodCache(): ReadonlyMap<string, BuiltinMethods> {
return this.extraMethodCache_;
}
getMethodCache(): Map<string, BuiltinMethods> {
return this.builtinMethodCache_;
}
/**
* Every engine pool's version in one number, or null where this build cannot
* be asked (no registry, or an artifact older than the binding). Null means
* "assume everything moved": a holder of addresses must re-resolve rather
* than trust a number it could not read.
*/
layoutEpoch(): number | null {
const registry = this.cppRegistry_;
if (!registry) return null;
// The registry's own where the core binds it there (native), else the
// module's free function (web). One question, two spellings, because the
// two cores expose a Registry differently.
if (typeof registry.layoutEpoch === 'function') return registry.layoutEpoch();
const fn = (this.module_ as unknown as Record<string, unknown> | null)?.['registryLayoutEpoch'];
if (typeof fn !== 'function') return null;
return (fn as (r: CppRegistry) => number)(registry);
}
getEntitySet(cppName: string): Set<Entity> | undefined {
return this.builtinEntitySets_.get(cppName);
}
getOrCreateEntitySet(cppName: string): Set<Entity> {
let set = this.builtinEntitySets_.get(cppName);
if (!set) {
set = new Set();
this.builtinEntitySets_.set(cppName, set);
}
return set;
}
/** Re-order every builtin entity set so queries iterate in rank order
* (the JS half of {@link World.applyEntityOrder}; the engine's own pools are
* permuted by the same call). */
reorderEntitySets(rankOf: RankOf): void {
for (const set of this.builtinEntitySets_.values()) reorderSetByRank(set, rankOf);
}
/** Removes the entity from every builtin set; returns the cppNames it was in. */
deleteFromEntitySets(entity: Entity): string[] {
const removed: string[] = [];
for (const [cppName, set] of this.builtinEntitySets_) {
if (set.delete(entity)) removed.push(cppName);
}
return removed;
}
insert<T>(entity: Entity, component: BuiltinComponentDef<T>, data?: Partial<T>): { merged: T; isNew: boolean } {
const defaults = component._default as Record<string, unknown>;
const filtered: Record<string, unknown> = {};
if (data !== null && data !== undefined && typeof data === 'object') {
for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
if (v === undefined) continue;
if (!hasOwn(defaults, k)) continue;
filtered[k] = v;
}
const errors = validateComponentData(
component._name,
defaults,
filtered,
component.assetFields
);
if (errors.length > 0) {
throw new Error(formatValidationErrors(component._name, errors));
}
}
// Merged one level in, as a script component's `create` is: a builtin whose
// field grew an axis still reads the data written before it did.
const merged = mergeIntoDefaults(component._default as object, filtered) as T;
let isNew = true;
if (this.cppRegistry_) {
try {
const methods = this.getBuiltinMethods(component._cppName);
isNew = !methods.has(entity);
this.replace(entity, component._cppName,
convertForWasm(merged as Record<string, unknown>, component.colorKeys),
component.entityFields ?? []);
} catch (e) {
handleWasmError(e, `insertBuiltin(${component._name}, entity=${entity})`);
}
}
const set = this.getOrCreateEntitySet(component._cppName);
const tracked = set.has(entity);
if (isNew || !tracked) {
if (!tracked) set.add(entity);
}
return { merged, isNew: isNew || !tracked };
}
/**
* Hand a component's whole value to C++, converting the fields embind cannot
* take as a JS array. The write `insert` performs, without its structural
* bookkeeping — so a replace cannot marshal differently from an add.
*/
replace(entity: Entity, cppName: string, payload: Record<string, unknown>,
entityFields: readonly string[] = []): void {
const module = this.module_ as unknown as
{ VectorEntity?: new () => WasmVector; VectorFloat?: new () => WasmVector } | null;
const numberFields = numberListFieldsOf(cppName);
// On a copy: the vectors are freed below, and @p payload can be a Mut row the game still holds.
const out = entityFields.length > 0 || numberFields.length > 0 ? { ...payload } : payload;
const vectors = materializeEntityVectors(out, entityFields, module);
vectors.push(...materializeNumberVectors(out, numberFields, module));
try {
this.getBuiltinMethods(cppName).add(entity, out);
} finally {
for (const v of vectors) v.delete();
}
}
get<T>(entity: Entity, component: BuiltinComponentDef<T>): T {
if (!this.cppRegistry_) {
throw new Error('C++ Registry not connected');
}
try {
return builtinFromWasm(this.getBuiltinMethods(component._cppName).get(entity), component) as T;
} catch (e) {
handleWasmError(e, `getBuiltin(${component._name}, entity=${entity})`);
return { ...component._default } as T;
}
}
has(entity: Entity, component: BuiltinComponentDef<any>): boolean {
if (!this.cppRegistry_) {
return false;
}
try {
return this.getBuiltinMethods(component._cppName).has(entity);
} catch (e) {
handleWasmError(e, `hasBuiltin(${component._name}, entity=${entity})`);
return false;
}
}
remove(entity: Entity, component: BuiltinComponentDef<any>): void {
if (!this.cppRegistry_) {
return;
}
try {
this.getBuiltinMethods(component._cppName).remove(entity);
} catch (e) {
handleWasmError(e, `removeBuiltin(${component._name}, entity=${entity})`);
}
this.builtinEntitySets_.get(component._cppName)?.delete(entity);
}
/**
* Where `cppName`'s bytes are for an entity: what compiled code adds an EHT
* offset to. Through the {@link MemoryProvider}, the seam the fast
* accessors already use — an address resolved a second way can disagree.
* Null where this backend serves no flat memory.
*/
resolveComponentAddress(cppName: string): ((entity: Entity) => number | undefined) | null {
// Where there is a pointer function, ask it: the heap resolver below also
// fills three typed-array views for the accessors to read fields through,
// and a caller that wants only the address pays for them per entity.
const ptrFn = this.resolvePtrFn(cppName);
if (ptrFn) return (e: Entity) => ptrFn(e) || undefined;
const resolveHeap = this.memory_?.resolveComponentHeap(cppName);
if (!resolveHeap) return null;
const heap: ComponentHeap = SCRATCH_HEAP();
return (e: Entity) => (resolveHeap(e, heap) ? heap.ptr : undefined);
}
/**
* The wasm-exported pointer function for `cppName` — `(entity) => byte offset
* of that entity's component in the wasm heap`. Web/emscripten only (there is
* no such numeric address on native); the fast path itself goes through the
* {@link MemoryProvider}, so this is a lower-level convenience.
*/
resolvePtrFn(cppName: string): ((entity: Entity) => number) | null {
return resolveWasmPtrFn(this.module_, this.cppRegistry_, cppName);
}
resolvePtrSetter(cppName: string): ((entity: Entity, data: unknown) => void) | null {
const accessor = PTR_ACCESSORS[cppName];
if (!accessor) return null;
const resolveHeap = this.memory_?.resolveComponentHeap(cppName);
if (!resolveHeap) return null;
const heap: ComponentHeap = SCRATCH_HEAP();
return (e: Entity, data: unknown) => {
if (!resolveHeap(e, heap)) return;
accessor.write(heap.f32, heap.u32, heap.u8, heap.ptr, data);
};
}
/**
* A getter reading C++ component data out of the wasm heap. `borrowed` (the
* default) refills ONE object per call, so the value dies at the next call;
* `retained` fills a fresh one, which is what a caller keeping the value past
* its own step needs — a query row outliving the row after it, above all.
*/
resolvePtrGetter(cppName: string, mode: 'borrowed' | 'retained' = 'borrowed'):
((entity: Entity) => unknown) | null {
const accessor = PTR_ACCESSORS[cppName];
if (!accessor) return null;
const resolveHeap = this.memory_?.resolveComponentHeap(cppName);
if (!resolveHeap) return null;
const heap: ComponentHeap = SCRATCH_HEAP();
if (mode === 'retained') {
return (e: Entity) => {
if (!resolveHeap(e, heap)) return null;
const out = accessor.create();
accessor.fill(heap.f32, heap.u32, heap.u8, heap.ptr, out);
return out;
};
}
const cached = accessor.create();
return (e: Entity) => {
if (!resolveHeap(e, heap)) return null;
accessor.fill(heap.f32, heap.u32, heap.u8, heap.ptr, cached);
return cached;
};
}
}
// A fresh reusable ComponentHeap for one resolver. Its views are overwritten on
// every successful resolve, so the empty initial arrays are never observed.
function SCRATCH_HEAP(): ComponentHeap {
return { f32: EMPTY_F32, u32: EMPTY_U32, u8: EMPTY_U8, ptr: 0 };
}
const EMPTY_F32 = new Float32Array(0);
const EMPTY_U32 = new Uint32Array(0);
const EMPTY_U8 = new Uint8Array(0);