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 builtins.ts
* @brief Engine component shapes, from EHT's table rather than a second copy.
*
* @details PTR_LAYOUTS is generated from the C++ structs and is what the SDK's
* accessors and the ABI hash already agree on. The compiler consumes it
* for the same reason: a component's fields must have exactly one
* author.
*
* Resources have no such table yet — `Time` is spelled out below and
* marked, because a shape with no generator is exactly the drift this
* file exists to avoid.
*/
import { PTR_LAYOUTS } from '../../sdk/src/wasm/ptrLayouts.generated';
import { RESOURCE_NAMES, RESOURCE_SHAPES, resourceLayout } 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. */
const MEMBERS: Record<string, readonly string[]> = {
vec2: ['x', 'y'],
vec3: ['x', 'y', 'z'],
vec4: ['x', 'y', 'z', 'w'],
quat: ['x', 'y', 'z', 'w'],
color: ['r', 'g', 'b', 'a'],
};
/** EHT's field type -> how those bytes are encoded. */
const ENC: Record<string, LeafEnc> = {
f32: 'f32', bool: 'bool8', i32: 'i32', u32: 'u32', u8: 'u8',
};
function engineLeaf(t: string, offset: number): FieldSpec {
const enc = ENC[t] ?? 'f32';
return { type: enc === 'bool8' ? BOOL : F64, enc, offset };
}
/**
* Every engine component EHT emits a layout for, flattened to leaf paths.
* `Transform` becomes `position.x`, `position.y`, … so a place's path is the
* key, which is what lets a later pass fold it to a constant offset.
*/
export function builtinShapes(): Map<string, CompShape> {
const out = new Map<string, CompShape>();
for (const [name, layout] of Object.entries(PTR_LAYOUTS)) {
const fields = new Map<string, FieldSpec>();
for (const f of layout.fields) {
const members = MEMBERS[f.type];
if (members) {
// A composite is four-byte members laid end to end from the
// field's own offset — the same arithmetic ptrAccessors does.
members.forEach((m, i) => fields.set(`${f.name}.${m}`, engineLeaf('f32', f.offset + i * 4)));
} else if (f.type === 'struct') {
for (const m of f.members ?? []) {
fields.set(`${f.name}.${m.name}`, engineLeaf(m.type, f.offset + m.offset));
}
} else {
fields.set(f.name, engineLeaf(f.type, f.offset));
}
}
// EHT's table IS the engine's flat pools, so everything from it is
// engine-stored. Nothing downstream has to ask by name.
out.set(name, { name, storage: 'engine', fields });
}
for (const name of Object.keys(RESOURCE_SHAPES)) {
out.set(name, resourceShape(name));
}
return out;
}
/**
* 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): CompShape {
const declared = RESOURCE_SHAPES[name]!.fields;
const fields = new Map<string, FieldSpec>();
// Offsets come from the shared layout rather than being repacked here: the
// runtime mirrors a resource at those exact offsets, and a second answer to
// where a field is would be read as a different field.
for (const member of resourceLayout(name) ?? []) {
if (member.kind !== 'scalar') continue;
fields.set(member.name, {
type: typeof declared[member.name] === 'boolean' ? BOOL : F64,
enc: HOST_ENC,
offset: member.offset,
});
}
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 handshake. It stamps the OFFSETS rather
* than importing `ABI_LAYOUT_HASH`: that constant lives in
* `component.generated.ts`, whose imports reach the whole SDK runtime. The raw
* table is more information than a hash of it, and changes for the same reason.
*/
export function ehtStamp(): string {
const parts: string[] = [];
for (const [name, layout] of Object.entries(PTR_LAYOUTS)) {
const fields = layout.fields
.map((f) => `${f.name}:${f.type}@${f.offset}`
+ (f.members ? `{${f.members.map((m) => `${m.name}:${m.type}@${m.offset}`).join(',')}}` : ''))
.join(',');
parts.push(`${name}(${layout.ptrFn})=${fields}`);
}
return parts.join(';');
}