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(abi): single-source-of-truth boundary contract (RC1 keystone)
esenginecd9d9a3fa5f8
diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.mdnew file mode 100644index 000000000..3fda43847--- /dev/null+++ b/docs/REARCHITECTURE.md@@ -0,0 +1,126 @@+# Estella 根治方案(Re-architecture Plan)++> 目标读者:引擎维护者 / AI 协作代理。+> 本文是**架构权威文档(architecture-of-record)**,描述目标架构与根治路径,而非现状。+> 现状审计见各小节"病灶"引用的 `file:line`。++## 0. 核心诊断:同一事实的多个独立来源++对全仓(C++ ~34K 行、TS SDK ~35K 行)的深度审计后,几乎所有"脆弱 / 不完整 / 不清晰"的症状都可以归到**两类结构性病根**:++1. **多源真相(multiple sources of truth)**:同一个事实——内存布局、类型 ID、组件存储、枚举值——在 C++ 侧和 TS 侧、或在多个子系统里被**各自独立地定义/计算**,没有任何机制保证它们一致。它们会悄悄漂移,漂移后是**静默的内存损坏**,不是报错。+2. **可绕过的抽象(bypassable abstractions)**:`GfxDevice`、ECS 存储、WASM 桥接等抽象不是唯一通道,调用方可以绕过它直达底层。于是抽象只覆盖了一半,缓存/不变量被悄悄破坏。++**根治原则**:把每一处"多源"坍缩成**单一权威来源**,并由编译期断言 + 运行时握手强制一致;把每一个抽象做成**唯一通道**(绕过即编译不过)。下面五个根因,每个对应一个要建立的"单一权威来源"。++止血式修单点 bug 不在本方案范围内——因为只要多源结构还在,同类 bug 会无限再生。++---++## 根因 1(keystone):边界不是单一事实来源 → 契约优先的边界++### 病灶+- TS 侧内存偏移由 EHT 的 Python **手写打包模型**算出(`tools/eht/.../ptr_layout.py`),C++ 侧由编译器实际布局决定——**同一事实算了两遍**。一致性只靠 `WebSDKEntry.cpp:248-372` 里**手写、仅覆盖 8 个组件**的 `static_assert(offsetof)`。EHT 模型还是近似的(`i8` 当 `u8`、假设 enum 恒 1 字节)。+- `wasm.ts` 里 ~400 行 `ESEngineModule` 接口是**手工镜像**,与散落在 12 个 `bindings/*.cpp` 的真实导出无任何交叉校验;能生成权威 d.ts 的 `--emit-tsd` 因"binding mismatch"被关掉(`Emscripten.cmake:201`)。+- 必须与 C++ 对齐的枚举(`Tween`/`Easing`/`BodyType`)、跨模块 physics 结构体(`PHYSICS_BODY_BYTES=16` 只活在一句 TS 注释里)、material uniform wire format——全是**两侧手维护**。+- 漂移检测存在但**默认关闭**(`strict:false`),且只比组件名集合,不比偏移/类型/枚举宽度;**无 ABI 版本握手**。++### 目标架构+1. **C++ 组件结构体是唯一权威**(保留 `ES_COMPONENT/ES_PROPERTY` 注解)。+2. **编译器是偏移的唯一权威**。EHT 不再自己算 packing:改为生成一个"布局反射"翻译单元,由编译器吐出每个组件每个字段的 `offsetof/sizeof/alignof`(constexpr 数据,从模块导出或在构建期产出)。TS 偏移从**这份编译器产物**派生,不再独立计算。+3. **一份 spec 生成边界全部内容**:embind、指针访问器、TS 类型、`ESEngineModule` 接口(恢复/替代 `--emit-tsd`)、所有跨界枚举、跨模块结构体、所有 `_malloc` wire format。两侧都生成,**零手工镜像**。+4. **全组件编译期断言**:EHT 为**每个**组件每个字段生成 `static_assert(offsetof==N)`。不一致 = **编译失败**,而非运行时静默损坏。+5. **运行时 ABI 握手**:同一次 EHT 产出一个布局哈希,注入 C++(`getAbiHash()`)和 TS 常量;`connect()` 时比对,不一致直接拒绝启动。**握手默认且唯一**,删掉 `strict` 开关。++> 这一步是 keystone:它一次性坍缩掉偏移双算、手镜像模块、手维护枚举、physics 结构体注释、`--emit-tsd` 关闭、可选漂移检测;并且**它生成的 static_assert + 握手,正是后续每一步重构的安全验证机制**。++---++## 根因 2:四套并行的组件存储 → 单一存储核心++### 病灶+稀疏集逻辑被实现了 **4 遍**:`SparseSet<T>`(编译期 typed)、`SchemaComponentPool`(给 JS 的裸字节,`SchemaComponent.hpp`)、`DynamicComponentPool`(`emscripten::val`/`std::any`)、`Registry` 的 128-bit mask。三者销毁路径不统一——**动态组件在实体销毁时根本不被清理**(`Registry` 不持有 `DynamicComponentRegistry`,`Registry.hpp:138-170`)→ 泄漏。SDK 侧还另有 JS-storage 组件 vs C++-storage builtin 的二分。++### 目标架构+- **一个稀疏集核心**(分页稀疏数组 + 稠密数组,写一遍)。typed 访问、JS 裸指针访问、dynamic 访问都是它之上的**视图/访问器**,不是各自的实现。+- 规范存储用 **flat-byte 布局**——因为零拷贝跨界本来就要求扁平字节,所以它天然是 RC1 生成的访问器的目标。typed C++ 组件即"对这块字节的类型化视图"。+- **同一个注册表、同一个成员 mask、同一条销毁路径**覆盖全部三类。坍缩掉动态组件泄漏与 4x 重复。++---++## 根因 3:无连贯的错误/生命周期模型 → 端到端单一契约++### 病灶+- C++ 用 `-fno-exceptions` 编译,出错 `abort()` **整个模块**;TS 却用 try/catch 兜底**继续调用这具尸体**(`BuiltinBridge.ts:471-527`)。无 `onAbort`、无健康标志、无错误通道——最坏组合。+- `get...Ptr` 返回**借用指针**,指向会随 ECS 池重分配而移动、随 `ALLOW_MEMORY_GROWTH` 而失效的存储;已有 `registry_getSchemaPoolVersion` 守卫但**没接进任何调用点**。+- `_malloc/_free` 无 try/finally,抛异常即永久泄漏 WASM 堆。+- 不变量检查全是 `ES_ASSERT`,**release 构建编译成空操作**(`Log.hpp:313`)→ 出货版里所有来自 JS 的 `get/emplace/destroy` **零越界检查**。++### 目标架构+- **错误**:边界函数返回**显式状态/optional**;边界校验**始终开启**(独立于 `ES_ASSERT`,不被 release 剥离);安装致命 `onAbort` 翻"模块已死"标志,之后所有调用短路抛 `WasmModuleAborted`,**不再调用尸体**。+- **内存**:跨界裸指针只经**版本校验访问器**(接通 `getSchemaPoolVersion`,每次重取 HEAP 视图);`_malloc` 只经 RAII `withScratch()` 作用域;跨界句柄 RAII。+- 坍缩掉 UAF、抛异常泄漏、abort-into-corpse、release 剥离检查。++> 岔路(需拍板):是否改用 `-fwasm-exceptions` 让 C++ 失败变成可捕获的 JS 异常(体积/性能略增,TS 现有 try/catch 立刻有意义)vs 保持 `-fno-exceptions` + 显式状态码。**推荐后者**:保住体积/速度,把错误显式化而非依赖异常。++---++## 根因 4:全局 TypeId → 按域 + 按实例的确定性身份++### 病灶+单个全局 `getTypeId<T>()` 计数器被 **ECS / 事件 / 服务三套系统共享**,并直接当 `pools_` 下标(`Types.hpp:186`、`Registry.hpp:581`、`Dispatcher.hpp:229`、`ServiceRegistry.hpp:62`)。ID 按首次使用顺序分配 → **链接顺序相关、不确定**;某组件 ID 偶然很大就撑出一个全是 null 的超大 `pools_`;热重载/多模块下静默错位。++### 目标架构+- **按域独立的类型序列** `TypeIndex<Domain>`(Component / Event / Service 各一套)。+- 组件用**注册表局部的 dense id**(`std::type_index → 局部 id` 映射,或启动时按固定顺序显式注册),作为池下标。+- 坍缩掉链接顺序不确定、超大 pools、热重载错位、三系统耦合;这也是任何多模块/热重载故事的前置。++---++## 根因 5:抽象可绕过 → 抽象成为唯一通道++### 病灶+- `Texture/Shader/Buffer/Framebuffer` 全部直接调原始 `glXxx`,绕过 `GfxDevice`,使 `StateTracker` 缓存悄悄失效;`Texture` 仅 `ES_PLATFORM_WEB` 下有实现,native 构建里贴图是死的。+- **两套渲染器并存**:遗留 `Renderer/BatchRenderer2D` vs `RenderFrame`,批 shader 初始化等逻辑复制粘贴。+- 渲染 plugin **反向钻进**内容系统读/改运行时状态(`TilemapRenderPlugin.cpp:177` 在 const collect 里改 `dirty`)。+- SDK 有**五套互不相同的 WASM 桥接写法**;per-App 状态归属不统一(Tween/Audio/Scene 是 per-App,Camera/Timeline/SpriteAnimator/postprocess 仍是进程级全局)。+- 批渲染 EBO 全局累加,`baseVertex` 强转 `u16`,超 65535 顶点**静默回绕、GPU 读垃圾**(遍布所有批 plugin)。++### 目标架构+- **渲染唯一路径**:保留 `RenderFrame`,退役 `Renderer/BatchRenderer2D`。`GfxDevice` 成为**唯一 GPU 入口**——`Texture/Shader/Buffer` 接受 `GfxDevice&`,所有 bind 经 `StateTracker`。索引 `u16→u32`(或每帧到顶就 flush),让渲染路径**正确**而非打补丁。+- **内容系统写"渲染就绪快照",plugin 只读**,renderer 不再依赖内容系统头文件/生命周期。+- **SDK 单一 `WasmBridge` 基类**:一个 loader、一个 ready promise、一个"缺绑定"策略、一条错误路径;五套写法全部继承它。+- **单一状态归属**:所有子系统状态改为 per-App/per-World 资源。++---++## 执行顺序(根因序,全程保持构建常绿)++每一步都由 RC1 生成的 `static_assert` + ABI 握手 + 可跑的边界测试守护。**验证机制不是"安全网目的",而是验证根治是否成立的手段**——它本身就是 keystone 的一部分。++1. **建立验证机制 + keystone(RC1)**:让 WASM 边界测试在本仓库内可跑(当前指向不存在的 `desktop/`);EHT 生成全组件 `static_assert` + 布局哈希握手 + 完整边界 codegen。完成后,任何边界漂移都变成编译/启动失败。+2. **RC4 身份**:拆分全局 TypeId 为按域序列 + 注册表局部 id。改动局部、风险低、解锁热重载。+3. **RC2 存储**:四套存储收敛到单一核心,统一销毁/mask 路径。由 RC1 的字节布局契约护航。+4. **RC3 错误/生命周期**:显式状态 + 始终开启的边界校验 + onAbort + 版本校验指针 + RAII `_malloc`。+5. **RC5 抽象唯一化**:退役遗留渲染器、GfxDevice 唯一入口、u16→u32、统一 WasmBridge、状态全 per-App。++> 注:仓库目前是从 monorepo 拆出的半成品(CI/测试/docs 仍引用不存在的 `desktop/`+`editor/`,无 PR 门禁,`docs/ARCHITECTURE.md` 描述的类名与代码不符)。这不是"安全网策略",而是**根治的前置条件**:没有可跑的构建+边界测试,就无法验证上述任何一步是否真的成立。故第 1 步内含"让仓库自洽可建可测"。++## 需要拍板的两个架构岔路++| 岔路 | 选项 A | 选项 B(推荐) |+|---|---|---|+| **错误模型(RC3)** | `-fwasm-exceptions`:C++ 失败变可捕获 JS 异常,TS 现有 try/catch 立即有效;体积/性能略增 | 保持 `-fno-exceptions` + 边界函数显式状态码 + 致命 onAbort。保住体积/速度,错误显式化 |+| **规范存储(RC2)** | 保留 typed pool 为主、schema 为投影 | 以 flat-byte schema pool 为唯一核心。零拷贝跨界天然契合,与 RC1 的生成访问器同一目标 |++## 实现进度(living status)++### RC1 keystone — ✅ 已落地(第一批)+- **编译器成为偏移权威**:EHT 为**全部**组件的每个指针字段生成 `static_assert(offsetof==N)`(`tools/eht/generators/ptr_layout.py::generate_layout_asserts`),注入 `WebBindings.generated.cpp`。任何 EHT 模型与真实编译器布局的分歧 = 构建失败。已删除 `WebSDKEntry.cpp` 中手写、仅覆盖 8 个组件的断言。生成的 8 个组件偏移与原手写(经编译器验证)值逐字节一致,证明模型正确。+- **运行时 ABI 哈希握手**:`tools/eht/abi.py` 从单次 schema 解析计算布局哈希,同时注入 C++(`getAbiLayoutHash()`)与 TS(`ABI_LAYOUT_HASH`,在 `component.generated.ts`)。`BuiltinBridge.connect()` 比对,不一致**无条件致命**(即使非 strict 模式),因为 mock registry 不暴露该函数所以测试不受影响。当前哈希:`f5d18743d00de675`。+- **EHT 路径健壮性**:修复了 `--ts-output sdk/src` 会静默跳过 `component.generated.ts` / ptrLayouts / ptrAccessors 的潜在 bug(之前它们只在非默认 `--ts-output sdk` 下才重新生成)。现在标准构建会让全部生成的 TS 保持同步。+- **边界测试可在仓库内运行**:`sdk/tests/helpers/loadWasm.ts` 成为 WASM 路径单一来源(`$ESENGINE_WASM_DIR` → `build/wasm/web` → 旧 `desktop/public/wasm`),8 个集成测试文件不再各自硬编码不存在的 `desktop/public/wasm`。+- 验证:SDK typecheck 通过;2012 个测试通过(含 3 个新握手测试,证明 mismatch 在非 strict 下也致命);EHT 幂等。**待补**:C++ 侧 `static_assert` + `getAbiLayoutHash` 的实际编译验证需要 emsdk(随 CI web 构建门禁一起闭环)。++### RC2 / RC3 / RC4 / RC5 — 未开始+按执行顺序依次推进,全程在 RC1 的 `static_assert` + 握手护栏内进行。diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex dc9263f2b..eb43d39e1 100644--- a/sdk/src/component.generated.ts+++ b/sdk/src/component.generated.ts@@ -6,6 +6,14 @@import type { AssetFieldType } from './scene';+/**+ * Single-source-of-truth hash of the C++/TS boundary ABI (component+ * schema + pointer layouts). The WASM module exposes the same digest via+ * getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to+ * run on mismatch, because mismatched offsets read the wrong heap bytes.+ */+export const ABI_LAYOUT_HASH = 'f5d18743d00de675';+export interface AssetFieldMeta {field: string;type: AssetFieldType;diff --git a/sdk/src/ecs/BuiltinBridge.ts b/sdk/src/ecs/BuiltinBridge.tsindex bcce66eaa..96a5b0f4e 100644--- a/sdk/src/ecs/BuiltinBridge.ts+++ b/sdk/src/ecs/BuiltinBridge.ts@@ -8,7 +8,7 @@ import type { BuiltinComponentDef } from '../component';import type { CppRegistry, ESEngineModule } from '../wasm';import { validateComponentData, formatValidationErrors } from '../validation';import { handleWasmError } from '../wasmError';-import { COMPONENT_META } from '../component.generated';+import { COMPONENT_META, ABI_LAYOUT_HASH } from '../component.generated';import { PTR_LAYOUTS } from '../ptrLayouts.generated';import { PTR_ACCESSORS } from './ptrAccessors.generated';@@ -236,6 +236,16 @@ export interface BridgeVerification {* 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}. */@@ -255,6 +265,15 @@ 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}`);@@ -306,7 +325,13 @@ export class BuiltinBridge {this.builtinEntitySets_.clear();const verification = this.verifyAgainst_(cppRegistry, module);- if (options.strict && !verification.ok) {+ // 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.builtinMethodCache_.clear();@@ -344,6 +369,7 @@ export class BuiltinBridge {missing: [{ name: '<registry>', methods: ['connect() not called'] }],wasmOnly: [],sdkOnly: [],+ abiMismatch: null,};}return this.verifyAgainst_(this.cppRegistry_, this.module_ ?? undefined);@@ -384,8 +410,29 @@ export class BuiltinBridge {sdkOnly = Object.keys(COMPONENT_META).filter(n => !wasmSet.has(n));}- const ok = missing.length === 0 && wasmOnly.length === 0 && sdkOnly.length === 0;- return { ok, missing, wasmOnly, sdkOnly };+ // 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 {diff --git a/sdk/tests/builtin-bridge.test.ts b/sdk/tests/builtin-bridge.test.tsindex 5bf12bd10..6cf9a9417 100644--- a/sdk/tests/builtin-bridge.test.ts+++ b/sdk/tests/builtin-bridge.test.ts@@ -6,7 +6,7 @@*/import { describe, expect, it } from 'vitest';import { BuiltinBridge } from '../src/ecs/BuiltinBridge';-import { COMPONENT_META } from '../src/component.generated';+import { COMPONENT_META, ABI_LAYOUT_HASH } from '../src/component.generated';import type { CppRegistry, ESEngineModule } from '../src/wasm';function stubMethod() { return undefined; }@@ -195,4 +195,59 @@ describe('BuiltinBridge', () => {expect(v.wasmOnly).toEqual([]);expect(v.sdkOnly).toEqual([]);});++ // -------------------------------------------------------------------------+ // ABI layout-hash handshake. The WASM module exposes getAbiLayoutHash();+ // a mismatch means the loaded binary and this SDK were generated from+ // different component schemas, so pointer offsets read the wrong bytes.+ // This is ALWAYS fatal — even in non-strict mode.+ // -------------------------------------------------------------------------++ it('connects when the module ABI hash matches the SDK bundle', () => {+ const bridge = new BuiltinBridge();+ const reg = makeCompleteRegistry() as unknown as CppRegistry;+ const module = {+ getBuiltinComponentNames: () => Object.keys(COMPONENT_META),+ getAbiLayoutHash: () => ABI_LAYOUT_HASH,+ } as unknown as ESEngineModule;++ expect(() => { bridge.connect(reg, module, { strict: true }); }).not.toThrow();+ expect(bridge.verify().abiMismatch).toBeNull();+ });++ it('refuses to connect on ABI hash mismatch even in non-strict mode', () => {+ const bridge = new BuiltinBridge();+ const reg = makeCompleteRegistry() as unknown as CppRegistry;+ const module = {+ getBuiltinComponentNames: () => Object.keys(COMPONENT_META),+ getAbiLayoutHash: () => 'deadbeefdeadbeef',+ } as unknown as ESEngineModule;++ let caught: Error | null = null;+ try {+ // No { strict: true } — a hash mismatch must be fatal regardless.+ bridge.connect(reg, module);+ } catch (e) {+ caught = e as Error;+ }++ expect(caught).not.toBeNull();+ expect(caught!.message).toContain('ABI layout hash mismatch');+ expect(caught!.message).toContain(ABI_LAYOUT_HASH);+ expect(caught!.message).toContain('deadbeefdeadbeef');+ // Fatal connect must leave the bridge disconnected.+ expect(bridge.hasCpp).toBe(false);+ });++ it('skips the hash handshake when the module lacks getAbiLayoutHash', () => {+ // Older WASM builds predate the handshake — connect must still succeed.+ const bridge = new BuiltinBridge();+ const reg = makeCompleteRegistry() as unknown as CppRegistry;+ const module = {+ getBuiltinComponentNames: () => Object.keys(COMPONENT_META),+ } as unknown as ESEngineModule;++ expect(() => { bridge.connect(reg, module, { strict: true }); }).not.toThrow();+ expect(bridge.verify().abiMismatch).toBeNull();+ });});diff --git a/sdk/tests/emscripten-wrapper.test.ts b/sdk/tests/emscripten-wrapper.test.tsindex 3107b6632..5b0d02265 100644--- a/sdk/tests/emscripten-wrapper.test.ts+++ b/sdk/tests/emscripten-wrapper.test.ts@@ -2,17 +2,12 @@* Diagnostic test: verify Object.entries behavior with Emscripten reference wrappers*/import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { App } from '../src/app';import { Transform } from '../src/component';import { UIRect } from '../src/ui/core/ui-rect';import type { UIRectData } from '../src/ui/core/ui-rect';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';--const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';describe.skipIf(!HAS_WASM)('Emscripten wrapper diagnostics', () => {let module: ESEngineModule;diff --git a/sdk/tests/entity-hierarchy.test.ts b/sdk/tests/entity-hierarchy.test.tsindex 0635c02f3..46bf861b6 100644--- a/sdk/tests/entity-hierarchy.test.ts+++ b/sdk/tests/entity-hierarchy.test.ts@@ -5,15 +5,10 @@* Run `node build-tools/cli.js build -t web` first if missing.*/import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { World } from '../src/world';import { Transform, Sprite, Parent, Children } from '../src/component';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';--const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';describe.skipIf(!HAS_WASM)('Entity Hierarchy (WASM integration)', () => {let module: ESEngineModule;diff --git a/sdk/tests/helpers/loadWasm.ts b/sdk/tests/helpers/loadWasm.tsindex 7b1cc899b..e78bf4aad 100644--- a/sdk/tests/helpers/loadWasm.ts+++ b/sdk/tests/helpers/loadWasm.ts@@ -1,14 +1,49 @@-import { readFileSync } from 'fs';+import { existsSync, readFileSync } from 'fs';import { resolve } from 'path';import type { ESEngineModule } from '../../src/wasm';-const WASM_DIR = resolve(__dirname, '../../../desktop/public/wasm');+/**+ * Single source of truth for where the boundary integration tests find the+ * built WASM SDK (esengine.js + esengine.wasm). Resolution order:+ * 1. $ESENGINE_WASM_DIR — explicit override (CI passes the build dir)+ * 2. <repo>/build/wasm/web — the in-repo CMake/Emscripten output+ * 3. <repo>/desktop/public/wasm — legacy path when built inside the editor repo+ *+ * The first candidate that actually contains esengine.wasm wins. If none do,+ * {@link HAS_WASM} is false and the integration suites skip themselves via+ * `describe.skipIf(!HAS_WASM)` rather than throwing. Previously every test+ * hard-coded the (nonexistent in this repo) desktop path, so the entire+ * C++/TS boundary was never exercised here.+ */+function resolveWasmDir(): string {+ const candidates = [+ process.env.ESENGINE_WASM_DIR,+ resolve(__dirname, '../../../build/wasm/web'),+ resolve(__dirname, '../../../desktop/public/wasm'),+ ].filter((c): c is string => Boolean(c));++ for (const dir of candidates) {+ if (existsSync(resolve(dir, 'esengine.wasm'))) return dir;+ }+ // None found — return the canonical in-repo build output so HAS_WASM and+ // any diagnostics point at where the WASM is expected to be built.+ return resolve(__dirname, '../../../build/wasm/web');+}++/** Directory containing the built WASM SDK, per {@link resolveWasmDir}. */+export const WASM_DIR = resolveWasmDir();++/** Absolute path to the built esengine.wasm binary. */+export const WASM_FILE = resolve(WASM_DIR, 'esengine.wasm');++/** True when a built WASM SDK is available to run boundary integration tests. */+export const HAS_WASM = existsSync(WASM_FILE);let cachedModule: ESEngineModule | null = null;export async function loadWasmModule(): Promise<ESEngineModule> {if (cachedModule) return cachedModule;- const wasmBinary = readFileSync(resolve(WASM_DIR, 'esengine.wasm'));+ const wasmBinary = readFileSync(WASM_FILE);const factory = (await import(resolve(WASM_DIR, 'esengine.js'))).default;cachedModule = await factory({ wasmBinary }) as ESEngineModule;return cachedModule;diff --git a/sdk/tests/nested-text.test.ts b/sdk/tests/nested-text.test.tsindex eae9a23da..e32856b33 100644--- a/sdk/tests/nested-text.test.ts+++ b/sdk/tests/nested-text.test.ts@@ -6,8 +6,6 @@* only one text renders visually.*/import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { App } from '../src/app';import { Transform, Sprite, Canvas } from '../src/component';import type { SpriteData } from '../src/component';@@ -23,10 +21,7 @@ import type { TextData } from '../src/ui/core/text';import { textPlugin } from '../src/ui/TextPlugin';import { INVALID_TEXTURE } from '../src/types';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';--const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';describe.skipIf(!HAS_WASM)('Nested Text Entities (WASM integration)', () => {let module: ESEngineModule;diff --git a/sdk/tests/scrollview.test.ts b/sdk/tests/scrollview.test.tsindex af873e619..8816ddc6d 100644--- a/sdk/tests/scrollview.test.ts+++ b/sdk/tests/scrollview.test.ts@@ -1,6 +1,4 @@import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { App } from '../src/app';import { Transform, Sprite, Canvas } from '../src/component';import type { TransformData } from '../src/component';@@ -17,10 +15,7 @@ import type { ScrollViewData } from '../src/ui/ScrollView';import { UIInteraction } from '../src/ui/behavior/interactable';import { Interactable } from '../src/ui/behavior/interactable';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';--const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';describe.skipIf(!HAS_WASM)('ScrollView (WASM)', () => {let module: ESEngineModule;diff --git a/sdk/tests/text-multi-render.test.ts b/sdk/tests/text-multi-render.test.tsindex 986a816ef..4caa658bc 100644--- a/sdk/tests/text-multi-render.test.ts+++ b/sdk/tests/text-multi-render.test.ts@@ -4,8 +4,6 @@* in the editor, implying earlier textures are lost or overwritten.*/import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { App } from '../src/app';import { Transform, Sprite, Canvas } from '../src/component';import type { SpriteData } from '../src/component';@@ -19,10 +17,7 @@ import { textPlugin } from '../src/ui/TextPlugin';import { Text } from '../src/ui/core/text';import { INVALID_TEXTURE } from '../src/types';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';--const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';describe.skipIf(!HAS_WASM)('Multiple Text Entities (WASM)', () => {let module: ESEngineModule;diff --git a/sdk/tests/timeline-wasm-integration.test.ts b/sdk/tests/timeline-wasm-integration.test.tsindex 45c400a02..dfdf1c5e3 100644--- a/sdk/tests/timeline-wasm-integration.test.ts+++ b/sdk/tests/timeline-wasm-integration.test.ts@@ -5,13 +5,11 @@* Run `node build-tools/cli.js build -t web` first if missing.*/import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { World } from '../src/world';import { Transform, Children, Name, getComponent } from '../src/component';import { UIRect, type UIRectData } from '../src/ui/core/ui-rect';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';import {WrapMode,TrackType,@@ -20,9 +18,6 @@ import {} from '../src/timeline/TimelineTypes';import { setNestedProperty } from '../src/timeline/TimelinePlugin';-const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);-describe.skipIf(!HAS_WASM)('Timeline WASM Integration', () => {let module: ESEngineModule;diff --git a/sdk/tests/ui-components.test.ts b/sdk/tests/ui-components.test.tsindex bdcdbe6f8..995f53cb3 100644--- a/sdk/tests/ui-components.test.ts+++ b/sdk/tests/ui-components.test.ts@@ -6,8 +6,6 @@* Run `node build-tools/cli.js build -t web` first if missing.*/import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { App } from '../src/app';import { World } from '../src/world';import { Transform, Sprite, Canvas } from '../src/component';@@ -21,10 +19,7 @@ import { UICameraInfo, type UICameraData } from '../src/ui/UICameraInfo';import { uiLayoutPlugin } from '../src/ui/UILayoutPlugin';import { uiRenderOrderPlugin } from '../src/ui/UIRenderOrderPlugin';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';--const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';describe.skipIf(!HAS_WASM)('UI Components (WASM integration)', () => {let module: ESEngineModule;diff --git a/sdk/tests/ui-layout-integration.test.ts b/sdk/tests/ui-layout-integration.test.tsindex dcde04611..890e5aee4 100644--- a/sdk/tests/ui-layout-integration.test.ts+++ b/sdk/tests/ui-layout-integration.test.ts@@ -5,8 +5,6 @@* Run `node build-tools/cli.js build -t web` first if missing.*/import { describe, it, expect, beforeAll } from 'vitest';-import { existsSync } from 'fs';-import { resolve } from 'path';import { App } from '../src/app';import { World } from '../src/world';import { UIRect, type UIRectData } from '../src/ui/core/ui-rect';@@ -16,10 +14,7 @@ import { uiLayoutPlugin } from '../src/ui/UILayoutPlugin';import { uiRenderOrderPlugin } from '../src/ui/UIRenderOrderPlugin';import { Transform, Sprite } from '../src/component';import type { ESEngineModule, CppRegistry } from '../src/wasm';-import { loadWasmModule } from './helpers/loadWasm';--const WASM_PATH = resolve(__dirname, '../../desktop/public/wasm/esengine.wasm');-const HAS_WASM = existsSync(WASM_PATH);+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';describe.skipIf(!HAS_WASM)('UI Layout via App.tick() (WASM integration)', () => {let module: ESEngineModule;diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 0d9842e8f..c43e3cb94 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -7,6 +7,8 @@#ifdef ES_PLATFORM_WEB#include <emscripten/bind.h>+#include <cstddef>+#include <string>#include "../ecs/Registry.hpp"#include "../math/Math.hpp"#include "../core/UITypes.hpp"@@ -1791,4 +1793,251 @@ EMSCRIPTEN_BINDINGS(esengine_reflection) {emscripten::function("getBuiltinComponentNames", &esengineGetBuiltinComponentNames);}+// =============================================================================+// ABI Layout Asserts -- the compiler is the offset authority+// =============================================================================+// EHT computes each pointer-field offset; the asserts below prove the real+// compiler layout matches. A failure here means the TS pointer accessors would+// read the wrong bytes -- fix the struct or regenerate EHT. DO NOT EDIT.++static_assert(offsetof(esengine::ecs::BitmapText, color) == 0, "ABI offset drift: esengine::ecs::BitmapText.color (EHT expected 0)");+static_assert(offsetof(esengine::ecs::BitmapText, fontSize) == 16, "ABI offset drift: esengine::ecs::BitmapText.fontSize (EHT expected 16)");+static_assert(offsetof(esengine::ecs::BitmapText, align) == 20, "ABI offset drift: esengine::ecs::BitmapText.align (EHT expected 20)");+static_assert(offsetof(esengine::ecs::BitmapText, spacing) == 24, "ABI offset drift: esengine::ecs::BitmapText.spacing (EHT expected 24)");+static_assert(offsetof(esengine::ecs::BitmapText, layer) == 28, "ABI offset drift: esengine::ecs::BitmapText.layer (EHT expected 28)");+static_assert(offsetof(esengine::ecs::BitmapText, font) == 32, "ABI offset drift: esengine::ecs::BitmapText.font (EHT expected 32)");+static_assert(offsetof(esengine::ecs::BitmapText, enabled) == 36, "ABI offset drift: esengine::ecs::BitmapText.enabled (EHT expected 36)");+static_assert(offsetof(esengine::ecs::Camera, projectionType) == 0, "ABI offset drift: esengine::ecs::Camera.projectionType (EHT expected 0)");+static_assert(offsetof(esengine::ecs::Camera, fov) == 4, "ABI offset drift: esengine::ecs::Camera.fov (EHT expected 4)");+static_assert(offsetof(esengine::ecs::Camera, orthoSize) == 8, "ABI offset drift: esengine::ecs::Camera.orthoSize (EHT expected 8)");+static_assert(offsetof(esengine::ecs::Camera, nearPlane) == 12, "ABI offset drift: esengine::ecs::Camera.nearPlane (EHT expected 12)");+static_assert(offsetof(esengine::ecs::Camera, farPlane) == 16, "ABI offset drift: esengine::ecs::Camera.farPlane (EHT expected 16)");+static_assert(offsetof(esengine::ecs::Camera, aspectRatio) == 20, "ABI offset drift: esengine::ecs::Camera.aspectRatio (EHT expected 20)");+static_assert(offsetof(esengine::ecs::Camera, isActive) == 24, "ABI offset drift: esengine::ecs::Camera.isActive (EHT expected 24)");+static_assert(offsetof(esengine::ecs::Camera, priority) == 28, "ABI offset drift: esengine::ecs::Camera.priority (EHT expected 28)");+static_assert(offsetof(esengine::ecs::Camera, viewport) == 32, "ABI offset drift: esengine::ecs::Camera.viewport (EHT expected 32)");+static_assert(offsetof(esengine::ecs::Camera, clearFlags) == 48, "ABI offset drift: esengine::ecs::Camera.clearFlags (EHT expected 48)");+static_assert(offsetof(esengine::ecs::Canvas, designResolution) == 0, "ABI offset drift: esengine::ecs::Canvas.designResolution (EHT expected 0)");+static_assert(offsetof(esengine::ecs::Canvas, pixelsPerUnit) == 8, "ABI offset drift: esengine::ecs::Canvas.pixelsPerUnit (EHT expected 8)");+static_assert(offsetof(esengine::ecs::Canvas, scaleMode) == 12, "ABI offset drift: esengine::ecs::Canvas.scaleMode (EHT expected 12)");+static_assert(offsetof(esengine::ecs::Canvas, matchWidthOrHeight) == 16, "ABI offset drift: esengine::ecs::Canvas.matchWidthOrHeight (EHT expected 16)");+static_assert(offsetof(esengine::ecs::Canvas, backgroundColor) == 20, "ABI offset drift: esengine::ecs::Canvas.backgroundColor (EHT expected 20)");+static_assert(offsetof(esengine::ecs::BoxCollider, halfExtents) == 0, "ABI offset drift: esengine::ecs::BoxCollider.halfExtents (EHT expected 0)");+static_assert(offsetof(esengine::ecs::BoxCollider, offset) == 8, "ABI offset drift: esengine::ecs::BoxCollider.offset (EHT expected 8)");+static_assert(offsetof(esengine::ecs::BoxCollider, density) == 16, "ABI offset drift: esengine::ecs::BoxCollider.density (EHT expected 16)");+static_assert(offsetof(esengine::ecs::BoxCollider, friction) == 20, "ABI offset drift: esengine::ecs::BoxCollider.friction (EHT expected 20)");+static_assert(offsetof(esengine::ecs::BoxCollider, restitution) == 24, "ABI offset drift: esengine::ecs::BoxCollider.restitution (EHT expected 24)");+static_assert(offsetof(esengine::ecs::BoxCollider, isSensor) == 28, "ABI offset drift: esengine::ecs::BoxCollider.isSensor (EHT expected 28)");+static_assert(offsetof(esengine::ecs::BoxCollider, enabled) == 29, "ABI offset drift: esengine::ecs::BoxCollider.enabled (EHT expected 29)");+static_assert(offsetof(esengine::ecs::BoxCollider, categoryBits) == 32, "ABI offset drift: esengine::ecs::BoxCollider.categoryBits (EHT expected 32)");+static_assert(offsetof(esengine::ecs::BoxCollider, maskBits) == 36, "ABI offset drift: esengine::ecs::BoxCollider.maskBits (EHT expected 36)");+static_assert(offsetof(esengine::ecs::CircleCollider, radius) == 0, "ABI offset drift: esengine::ecs::CircleCollider.radius (EHT expected 0)");+static_assert(offsetof(esengine::ecs::CircleCollider, offset) == 4, "ABI offset drift: esengine::ecs::CircleCollider.offset (EHT expected 4)");+static_assert(offsetof(esengine::ecs::CircleCollider, density) == 12, "ABI offset drift: esengine::ecs::CircleCollider.density (EHT expected 12)");+static_assert(offsetof(esengine::ecs::CircleCollider, friction) == 16, "ABI offset drift: esengine::ecs::CircleCollider.friction (EHT expected 16)");+static_assert(offsetof(esengine::ecs::CircleCollider, restitution) == 20, "ABI offset drift: esengine::ecs::CircleCollider.restitution (EHT expected 20)");+static_assert(offsetof(esengine::ecs::CircleCollider, isSensor) == 24, "ABI offset drift: esengine::ecs::CircleCollider.isSensor (EHT expected 24)");+static_assert(offsetof(esengine::ecs::CircleCollider, enabled) == 25, "ABI offset drift: esengine::ecs::CircleCollider.enabled (EHT expected 25)");+static_assert(offsetof(esengine::ecs::CircleCollider, categoryBits) == 28, "ABI offset drift: esengine::ecs::CircleCollider.categoryBits (EHT expected 28)");+static_assert(offsetof(esengine::ecs::CircleCollider, maskBits) == 32, "ABI offset drift: esengine::ecs::CircleCollider.maskBits (EHT expected 32)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, radius) == 0, "ABI offset drift: esengine::ecs::CapsuleCollider.radius (EHT expected 0)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, halfHeight) == 4, "ABI offset drift: esengine::ecs::CapsuleCollider.halfHeight (EHT expected 4)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, offset) == 8, "ABI offset drift: esengine::ecs::CapsuleCollider.offset (EHT expected 8)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, density) == 16, "ABI offset drift: esengine::ecs::CapsuleCollider.density (EHT expected 16)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, friction) == 20, "ABI offset drift: esengine::ecs::CapsuleCollider.friction (EHT expected 20)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, restitution) == 24, "ABI offset drift: esengine::ecs::CapsuleCollider.restitution (EHT expected 24)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, isSensor) == 28, "ABI offset drift: esengine::ecs::CapsuleCollider.isSensor (EHT expected 28)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, enabled) == 29, "ABI offset drift: esengine::ecs::CapsuleCollider.enabled (EHT expected 29)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, categoryBits) == 32, "ABI offset drift: esengine::ecs::CapsuleCollider.categoryBits (EHT expected 32)");+static_assert(offsetof(esengine::ecs::CapsuleCollider, maskBits) == 36, "ABI offset drift: esengine::ecs::CapsuleCollider.maskBits (EHT expected 36)");+static_assert(offsetof(esengine::ecs::SegmentCollider, point1) == 0, "ABI offset drift: esengine::ecs::SegmentCollider.point1 (EHT expected 0)");+static_assert(offsetof(esengine::ecs::SegmentCollider, point2) == 8, "ABI offset drift: esengine::ecs::SegmentCollider.point2 (EHT expected 8)");+static_assert(offsetof(esengine::ecs::SegmentCollider, density) == 16, "ABI offset drift: esengine::ecs::SegmentCollider.density (EHT expected 16)");+static_assert(offsetof(esengine::ecs::SegmentCollider, friction) == 20, "ABI offset drift: esengine::ecs::SegmentCollider.friction (EHT expected 20)");+static_assert(offsetof(esengine::ecs::SegmentCollider, restitution) == 24, "ABI offset drift: esengine::ecs::SegmentCollider.restitution (EHT expected 24)");+static_assert(offsetof(esengine::ecs::SegmentCollider, isSensor) == 28, "ABI offset drift: esengine::ecs::SegmentCollider.isSensor (EHT expected 28)");+static_assert(offsetof(esengine::ecs::SegmentCollider, enabled) == 29, "ABI offset drift: esengine::ecs::SegmentCollider.enabled (EHT expected 29)");+static_assert(offsetof(esengine::ecs::SegmentCollider, categoryBits) == 32, "ABI offset drift: esengine::ecs::SegmentCollider.categoryBits (EHT expected 32)");+static_assert(offsetof(esengine::ecs::SegmentCollider, maskBits) == 36, "ABI offset drift: esengine::ecs::SegmentCollider.maskBits (EHT expected 36)");+static_assert(offsetof(esengine::ecs::FlexContainer, direction) == 0, "ABI offset drift: esengine::ecs::FlexContainer.direction (EHT expected 0)");+static_assert(offsetof(esengine::ecs::FlexContainer, wrap) == 1, "ABI offset drift: esengine::ecs::FlexContainer.wrap (EHT expected 1)");+static_assert(offsetof(esengine::ecs::FlexContainer, justifyContent) == 2, "ABI offset drift: esengine::ecs::FlexContainer.justifyContent (EHT expected 2)");+static_assert(offsetof(esengine::ecs::FlexContainer, alignItems) == 3, "ABI offset drift: esengine::ecs::FlexContainer.alignItems (EHT expected 3)");+static_assert(offsetof(esengine::ecs::FlexContainer, alignContent) == 4, "ABI offset drift: esengine::ecs::FlexContainer.alignContent (EHT expected 4)");+static_assert(offsetof(esengine::ecs::FlexContainer, gap) == 8, "ABI offset drift: esengine::ecs::FlexContainer.gap (EHT expected 8)");+static_assert(offsetof(esengine::ecs::FlexItem, flexGrow) == 0, "ABI offset drift: esengine::ecs::FlexItem.flexGrow (EHT expected 0)");+static_assert(offsetof(esengine::ecs::FlexItem, flexShrink) == 4, "ABI offset drift: esengine::ecs::FlexItem.flexShrink (EHT expected 4)");+static_assert(offsetof(esengine::ecs::FlexItem, flexBasis) == 8, "ABI offset drift: esengine::ecs::FlexItem.flexBasis (EHT expected 8)");+static_assert(offsetof(esengine::ecs::FlexItem, order) == 12, "ABI offset drift: esengine::ecs::FlexItem.order (EHT expected 12)");+static_assert(offsetof(esengine::ecs::FlexItem, alignSelf) == 16, "ABI offset drift: esengine::ecs::FlexItem.alignSelf (EHT expected 16)");+static_assert(offsetof(esengine::ecs::FlexItem, minWidth) == 20, "ABI offset drift: esengine::ecs::FlexItem.minWidth (EHT expected 20)");+static_assert(offsetof(esengine::ecs::FlexItem, minHeight) == 24, "ABI offset drift: esengine::ecs::FlexItem.minHeight (EHT expected 24)");+static_assert(offsetof(esengine::ecs::FlexItem, maxWidth) == 28, "ABI offset drift: esengine::ecs::FlexItem.maxWidth (EHT expected 28)");+static_assert(offsetof(esengine::ecs::FlexItem, maxHeight) == 32, "ABI offset drift: esengine::ecs::FlexItem.maxHeight (EHT expected 32)");+static_assert(offsetof(esengine::ecs::FlexItem, widthPercent) == 36, "ABI offset drift: esengine::ecs::FlexItem.widthPercent (EHT expected 36)");+static_assert(offsetof(esengine::ecs::FlexItem, heightPercent) == 40, "ABI offset drift: esengine::ecs::FlexItem.heightPercent (EHT expected 40)");+static_assert(offsetof(esengine::ecs::GridLayout, direction) == 0, "ABI offset drift: esengine::ecs::GridLayout.direction (EHT expected 0)");+static_assert(offsetof(esengine::ecs::GridLayout, crossAxisCount) == 4, "ABI offset drift: esengine::ecs::GridLayout.crossAxisCount (EHT expected 4)");+static_assert(offsetof(esengine::ecs::GridLayout, itemSize) == 8, "ABI offset drift: esengine::ecs::GridLayout.itemSize (EHT expected 8)");+static_assert(offsetof(esengine::ecs::GridLayout, spacing) == 16, "ABI offset drift: esengine::ecs::GridLayout.spacing (EHT expected 16)");+static_assert(offsetof(esengine::ecs::Interactable, enabled) == 0, "ABI offset drift: esengine::ecs::Interactable.enabled (EHT expected 0)");+static_assert(offsetof(esengine::ecs::Interactable, blockRaycast) == 1, "ABI offset drift: esengine::ecs::Interactable.blockRaycast (EHT expected 1)");+static_assert(offsetof(esengine::ecs::Interactable, raycastTarget) == 2, "ABI offset drift: esengine::ecs::Interactable.raycastTarget (EHT expected 2)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, rate) == 0, "ABI offset drift: esengine::ecs::ParticleEmitter.rate (EHT expected 0)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, burstCount) == 4, "ABI offset drift: esengine::ecs::ParticleEmitter.burstCount (EHT expected 4)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, burstInterval) == 8, "ABI offset drift: esengine::ecs::ParticleEmitter.burstInterval (EHT expected 8)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, duration) == 12, "ABI offset drift: esengine::ecs::ParticleEmitter.duration (EHT expected 12)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, looping) == 16, "ABI offset drift: esengine::ecs::ParticleEmitter.looping (EHT expected 16)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, playOnStart) == 17, "ABI offset drift: esengine::ecs::ParticleEmitter.playOnStart (EHT expected 17)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, maxParticles) == 20, "ABI offset drift: esengine::ecs::ParticleEmitter.maxParticles (EHT expected 20)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMin) == 24, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMin (EHT expected 24)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMax) == 28, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMax (EHT expected 28)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, shape) == 32, "ABI offset drift: esengine::ecs::ParticleEmitter.shape (EHT expected 32)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeRadius) == 36, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeRadius (EHT expected 36)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeSize) == 40, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeSize (EHT expected 40)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeAngle) == 48, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeAngle (EHT expected 48)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMin) == 52, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMin (EHT expected 52)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMax) == 56, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMax (EHT expected 56)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMin) == 60, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMin (EHT expected 60)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMax) == 64, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMax (EHT expected 64)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMin) == 68, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMin (EHT expected 68)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMax) == 72, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMax (EHT expected 72)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMin) == 76, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMin (EHT expected 76)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMax) == 80, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMax (EHT expected 80)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, sizeEasing) == 84, "ABI offset drift: esengine::ecs::ParticleEmitter.sizeEasing (EHT expected 84)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, startColor) == 88, "ABI offset drift: esengine::ecs::ParticleEmitter.startColor (EHT expected 88)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, endColor) == 104, "ABI offset drift: esengine::ecs::ParticleEmitter.endColor (EHT expected 104)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, colorEasing) == 120, "ABI offset drift: esengine::ecs::ParticleEmitter.colorEasing (EHT expected 120)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMin) == 124, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMin (EHT expected 124)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMax) == 128, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMax (EHT expected 128)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMin) == 132, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMin (EHT expected 132)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMax) == 136, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMax (EHT expected 136)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, gravity) == 140, "ABI offset drift: esengine::ecs::ParticleEmitter.gravity (EHT expected 140)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, damping) == 148, "ABI offset drift: esengine::ecs::ParticleEmitter.damping (EHT expected 148)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 152, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 152)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 156, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 156)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 160)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 164)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 168)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 172)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 176)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 180)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 184)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 188)");+static_assert(offsetof(esengine::ecs::RigidBody, bodyType) == 0, "ABI offset drift: esengine::ecs::RigidBody.bodyType (EHT expected 0)");+static_assert(offsetof(esengine::ecs::RigidBody, gravityScale) == 4, "ABI offset drift: esengine::ecs::RigidBody.gravityScale (EHT expected 4)");+static_assert(offsetof(esengine::ecs::RigidBody, linearDamping) == 8, "ABI offset drift: esengine::ecs::RigidBody.linearDamping (EHT expected 8)");+static_assert(offsetof(esengine::ecs::RigidBody, angularDamping) == 12, "ABI offset drift: esengine::ecs::RigidBody.angularDamping (EHT expected 12)");+static_assert(offsetof(esengine::ecs::RigidBody, fixedRotation) == 16, "ABI offset drift: esengine::ecs::RigidBody.fixedRotation (EHT expected 16)");+static_assert(offsetof(esengine::ecs::RigidBody, bullet) == 17, "ABI offset drift: esengine::ecs::RigidBody.bullet (EHT expected 17)");+static_assert(offsetof(esengine::ecs::RigidBody, enabled) == 18, "ABI offset drift: esengine::ecs::RigidBody.enabled (EHT expected 18)");+static_assert(offsetof(esengine::ecs::ShapeRenderer, shapeType) == 0, "ABI offset drift: esengine::ecs::ShapeRenderer.shapeType (EHT expected 0)");+static_assert(offsetof(esengine::ecs::ShapeRenderer, color) == 4, "ABI offset drift: esengine::ecs::ShapeRenderer.color (EHT expected 4)");+static_assert(offsetof(esengine::ecs::ShapeRenderer, size) == 20, "ABI offset drift: esengine::ecs::ShapeRenderer.size (EHT expected 20)");+static_assert(offsetof(esengine::ecs::ShapeRenderer, cornerRadius) == 28, "ABI offset drift: esengine::ecs::ShapeRenderer.cornerRadius (EHT expected 28)");+static_assert(offsetof(esengine::ecs::ShapeRenderer, layer) == 32, "ABI offset drift: esengine::ecs::ShapeRenderer.layer (EHT expected 32)");+static_assert(offsetof(esengine::ecs::ShapeRenderer, enabled) == 36, "ABI offset drift: esengine::ecs::ShapeRenderer.enabled (EHT expected 36)");+static_assert(offsetof(esengine::ecs::SpineAnimation, timeScale) == 0, "ABI offset drift: esengine::ecs::SpineAnimation.timeScale (EHT expected 0)");+static_assert(offsetof(esengine::ecs::SpineAnimation, loop) == 4, "ABI offset drift: esengine::ecs::SpineAnimation.loop (EHT expected 4)");+static_assert(offsetof(esengine::ecs::SpineAnimation, playing) == 5, "ABI offset drift: esengine::ecs::SpineAnimation.playing (EHT expected 5)");+static_assert(offsetof(esengine::ecs::SpineAnimation, flipX) == 6, "ABI offset drift: esengine::ecs::SpineAnimation.flipX (EHT expected 6)");+static_assert(offsetof(esengine::ecs::SpineAnimation, flipY) == 7, "ABI offset drift: esengine::ecs::SpineAnimation.flipY (EHT expected 7)");+static_assert(offsetof(esengine::ecs::SpineAnimation, color) == 8, "ABI offset drift: esengine::ecs::SpineAnimation.color (EHT expected 8)");+static_assert(offsetof(esengine::ecs::SpineAnimation, layer) == 24, "ABI offset drift: esengine::ecs::SpineAnimation.layer (EHT expected 24)");+static_assert(offsetof(esengine::ecs::SpineAnimation, skeletonScale) == 28, "ABI offset drift: esengine::ecs::SpineAnimation.skeletonScale (EHT expected 28)");+static_assert(offsetof(esengine::ecs::SpineAnimation, material) == 32, "ABI offset drift: esengine::ecs::SpineAnimation.material (EHT expected 32)");+static_assert(offsetof(esengine::ecs::SpineAnimation, enabled) == 36, "ABI offset drift: esengine::ecs::SpineAnimation.enabled (EHT expected 36)");+static_assert(offsetof(esengine::ecs::Sprite, texture) == 0, "ABI offset drift: esengine::ecs::Sprite.texture (EHT expected 0)");+static_assert(offsetof(esengine::ecs::Sprite, color) == 4, "ABI offset drift: esengine::ecs::Sprite.color (EHT expected 4)");+static_assert(offsetof(esengine::ecs::Sprite, size) == 20, "ABI offset drift: esengine::ecs::Sprite.size (EHT expected 20)");+static_assert(offsetof(esengine::ecs::Sprite, pivot) == 28, "ABI offset drift: esengine::ecs::Sprite.pivot (EHT expected 28)");+static_assert(offsetof(esengine::ecs::Sprite, uvOffset) == 36, "ABI offset drift: esengine::ecs::Sprite.uvOffset (EHT expected 36)");+static_assert(offsetof(esengine::ecs::Sprite, uvScale) == 44, "ABI offset drift: esengine::ecs::Sprite.uvScale (EHT expected 44)");+static_assert(offsetof(esengine::ecs::Sprite, layer) == 52, "ABI offset drift: esengine::ecs::Sprite.layer (EHT expected 52)");+static_assert(offsetof(esengine::ecs::Sprite, flipX) == 56, "ABI offset drift: esengine::ecs::Sprite.flipX (EHT expected 56)");+static_assert(offsetof(esengine::ecs::Sprite, flipY) == 57, "ABI offset drift: esengine::ecs::Sprite.flipY (EHT expected 57)");+static_assert(offsetof(esengine::ecs::Sprite, tileSize) == 60, "ABI offset drift: esengine::ecs::Sprite.tileSize (EHT expected 60)");+static_assert(offsetof(esengine::ecs::Sprite, tileSpacing) == 68, "ABI offset drift: esengine::ecs::Sprite.tileSpacing (EHT expected 68)");+static_assert(offsetof(esengine::ecs::Sprite, material) == 76, "ABI offset drift: esengine::ecs::Sprite.material (EHT expected 76)");+static_assert(offsetof(esengine::ecs::Sprite, enabled) == 80, "ABI offset drift: esengine::ecs::Sprite.enabled (EHT expected 80)");+static_assert(offsetof(esengine::ecs::StateVisuals, transitionFlags) == 0, "ABI offset drift: esengine::ecs::StateVisuals.transitionFlags (EHT expected 0)");+static_assert(offsetof(esengine::ecs::StateVisuals, fadeDuration) == 4, "ABI offset drift: esengine::ecs::StateVisuals.fadeDuration (EHT expected 4)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot0Color) == 8, "ABI offset drift: esengine::ecs::StateVisuals.slot0Color (EHT expected 8)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot0Sprite) == 24, "ABI offset drift: esengine::ecs::StateVisuals.slot0Sprite (EHT expected 24)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot0Scale) == 28, "ABI offset drift: esengine::ecs::StateVisuals.slot0Scale (EHT expected 28)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot1Color) == 32, "ABI offset drift: esengine::ecs::StateVisuals.slot1Color (EHT expected 32)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot1Sprite) == 48, "ABI offset drift: esengine::ecs::StateVisuals.slot1Sprite (EHT expected 48)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot1Scale) == 52, "ABI offset drift: esengine::ecs::StateVisuals.slot1Scale (EHT expected 52)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot2Color) == 56, "ABI offset drift: esengine::ecs::StateVisuals.slot2Color (EHT expected 56)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot2Sprite) == 72, "ABI offset drift: esengine::ecs::StateVisuals.slot2Sprite (EHT expected 72)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot2Scale) == 76, "ABI offset drift: esengine::ecs::StateVisuals.slot2Scale (EHT expected 76)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot3Color) == 80, "ABI offset drift: esengine::ecs::StateVisuals.slot3Color (EHT expected 80)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot3Sprite) == 96, "ABI offset drift: esengine::ecs::StateVisuals.slot3Sprite (EHT expected 96)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot3Scale) == 100, "ABI offset drift: esengine::ecs::StateVisuals.slot3Scale (EHT expected 100)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot4Color) == 104, "ABI offset drift: esengine::ecs::StateVisuals.slot4Color (EHT expected 104)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot4Sprite) == 120, "ABI offset drift: esengine::ecs::StateVisuals.slot4Sprite (EHT expected 120)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot4Scale) == 124, "ABI offset drift: esengine::ecs::StateVisuals.slot4Scale (EHT expected 124)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot5Color) == 128, "ABI offset drift: esengine::ecs::StateVisuals.slot5Color (EHT expected 128)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot5Sprite) == 144, "ABI offset drift: esengine::ecs::StateVisuals.slot5Sprite (EHT expected 144)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot5Scale) == 148, "ABI offset drift: esengine::ecs::StateVisuals.slot5Scale (EHT expected 148)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot6Color) == 152, "ABI offset drift: esengine::ecs::StateVisuals.slot6Color (EHT expected 152)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot6Sprite) == 168, "ABI offset drift: esengine::ecs::StateVisuals.slot6Sprite (EHT expected 168)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot6Scale) == 172, "ABI offset drift: esengine::ecs::StateVisuals.slot6Scale (EHT expected 172)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot7Color) == 176, "ABI offset drift: esengine::ecs::StateVisuals.slot7Color (EHT expected 176)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot7Sprite) == 192, "ABI offset drift: esengine::ecs::StateVisuals.slot7Sprite (EHT expected 192)");+static_assert(offsetof(esengine::ecs::StateVisuals, slot7Scale) == 196, "ABI offset drift: esengine::ecs::StateVisuals.slot7Scale (EHT expected 196)");+static_assert(offsetof(esengine::ecs::TilemapLayer, cellSize) == 0, "ABI offset drift: esengine::ecs::TilemapLayer.cellSize (EHT expected 0)");+static_assert(offsetof(esengine::ecs::TilemapLayer, originOffset) == 8, "ABI offset drift: esengine::ecs::TilemapLayer.originOffset (EHT expected 8)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tileset) == 16, "ABI offset drift: esengine::ecs::TilemapLayer.tileset (EHT expected 16)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetColumns) == 20, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetColumns (EHT expected 20)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tilesetRows) == 24, "ABI offset drift: esengine::ecs::TilemapLayer.tilesetRows (EHT expected 24)");+static_assert(offsetof(esengine::ecs::TilemapLayer, renderLayer) == 28, "ABI offset drift: esengine::ecs::TilemapLayer.renderLayer (EHT expected 28)");+static_assert(offsetof(esengine::ecs::TilemapLayer, tintColor) == 32, "ABI offset drift: esengine::ecs::TilemapLayer.tintColor (EHT expected 32)");+static_assert(offsetof(esengine::ecs::TilemapLayer, opacity) == 48, "ABI offset drift: esengine::ecs::TilemapLayer.opacity (EHT expected 48)");+static_assert(offsetof(esengine::ecs::TilemapLayer, parallaxFactor) == 52, "ABI offset drift: esengine::ecs::TilemapLayer.parallaxFactor (EHT expected 52)");+static_assert(offsetof(esengine::ecs::TilemapLayer, visible) == 60, "ABI offset drift: esengine::ecs::TilemapLayer.visible (EHT expected 60)");+static_assert(offsetof(esengine::ecs::Transform, position) == 0, "ABI offset drift: esengine::ecs::Transform.position (EHT expected 0)");+static_assert(offsetof(esengine::ecs::Transform, rotation) == 12, "ABI offset drift: esengine::ecs::Transform.rotation (EHT expected 12)");+static_assert(offsetof(esengine::ecs::Transform, scale) == 28, "ABI offset drift: esengine::ecs::Transform.scale (EHT expected 28)");+static_assert(offsetof(esengine::ecs::Transform, worldPosition) == 40, "ABI offset drift: esengine::ecs::Transform.worldPosition (EHT expected 40)");+static_assert(offsetof(esengine::ecs::Transform, worldRotation) == 52, "ABI offset drift: esengine::ecs::Transform.worldRotation (EHT expected 52)");+static_assert(offsetof(esengine::ecs::Transform, worldScale) == 68, "ABI offset drift: esengine::ecs::Transform.worldScale (EHT expected 68)");+static_assert(offsetof(esengine::ecs::UIInteraction, hovered) == 0, "ABI offset drift: esengine::ecs::UIInteraction.hovered (EHT expected 0)");+static_assert(offsetof(esengine::ecs::UIInteraction, pressed) == 1, "ABI offset drift: esengine::ecs::UIInteraction.pressed (EHT expected 1)");+static_assert(offsetof(esengine::ecs::UIInteraction, justPressed) == 2, "ABI offset drift: esengine::ecs::UIInteraction.justPressed (EHT expected 2)");+static_assert(offsetof(esengine::ecs::UIInteraction, justReleased) == 3, "ABI offset drift: esengine::ecs::UIInteraction.justReleased (EHT expected 3)");+static_assert(offsetof(esengine::ecs::UIMask, enabled) == 0, "ABI offset drift: esengine::ecs::UIMask.enabled (EHT expected 0)");+static_assert(offsetof(esengine::ecs::UIMask, mode) == 1, "ABI offset drift: esengine::ecs::UIMask.mode (EHT expected 1)");+static_assert(offsetof(esengine::ecs::UIRect, anchorMin) == 0, "ABI offset drift: esengine::ecs::UIRect.anchorMin (EHT expected 0)");+static_assert(offsetof(esengine::ecs::UIRect, anchorMax) == 8, "ABI offset drift: esengine::ecs::UIRect.anchorMax (EHT expected 8)");+static_assert(offsetof(esengine::ecs::UIRect, offsetMin) == 16, "ABI offset drift: esengine::ecs::UIRect.offsetMin (EHT expected 16)");+static_assert(offsetof(esengine::ecs::UIRect, offsetMax) == 24, "ABI offset drift: esengine::ecs::UIRect.offsetMax (EHT expected 24)");+static_assert(offsetof(esengine::ecs::UIRect, size) == 32, "ABI offset drift: esengine::ecs::UIRect.size (EHT expected 32)");+static_assert(offsetof(esengine::ecs::UIRect, pivot) == 40, "ABI offset drift: esengine::ecs::UIRect.pivot (EHT expected 40)");+static_assert(offsetof(esengine::ecs::UIRenderer, visualType) == 0, "ABI offset drift: esengine::ecs::UIRenderer.visualType (EHT expected 0)");+static_assert(offsetof(esengine::ecs::UIRenderer, texture) == 4, "ABI offset drift: esengine::ecs::UIRenderer.texture (EHT expected 4)");+static_assert(offsetof(esengine::ecs::UIRenderer, color) == 8, "ABI offset drift: esengine::ecs::UIRenderer.color (EHT expected 8)");+static_assert(offsetof(esengine::ecs::UIRenderer, uvOffset) == 24, "ABI offset drift: esengine::ecs::UIRenderer.uvOffset (EHT expected 24)");+static_assert(offsetof(esengine::ecs::UIRenderer, uvScale) == 32, "ABI offset drift: esengine::ecs::UIRenderer.uvScale (EHT expected 32)");+static_assert(offsetof(esengine::ecs::UIRenderer, sliceBorder) == 40, "ABI offset drift: esengine::ecs::UIRenderer.sliceBorder (EHT expected 40)");+static_assert(offsetof(esengine::ecs::UIRenderer, material) == 56, "ABI offset drift: esengine::ecs::UIRenderer.material (EHT expected 56)");+static_assert(offsetof(esengine::ecs::UIRenderer, enabled) == 60, "ABI offset drift: esengine::ecs::UIRenderer.enabled (EHT expected 60)");+static_assert(offsetof(esengine::ecs::Velocity, linear) == 0, "ABI offset drift: esengine::ecs::Velocity.linear (EHT expected 0)");+static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drift: esengine::ecs::Velocity.angular (EHT expected 12)");+++// =============================================================================+// ABI Hash -- runtime handshake against the SDK bundle+// =============================================================================++static const char* kEsAbiLayoutHash = "f5d18743d00de675";++std::string esengineGetAbiLayoutHash() {+ return std::string(kEsAbiLayoutHash);+}++EMSCRIPTEN_BINDINGS(esengine_abi) {+ emscripten::function("getAbiLayoutHash", &esengineGetAbiLayoutHash);+}+#endif // ES_PLATFORM_WEBdiff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 55902edcb..6af3ede14 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -245,26 +245,11 @@ resource::ResourceManager* getResourceManager() {// Pointer-based Component Access// =============================================================================-static_assert(offsetof(ecs::Transform, position) == 0);-static_assert(offsetof(ecs::Transform, rotation) == 12);-static_assert(offsetof(ecs::Transform, scale) == 28);-static_assert(offsetof(ecs::Transform, worldPosition) == 40);-static_assert(offsetof(ecs::Transform, worldRotation) == 52);-static_assert(offsetof(ecs::Transform, worldScale) == 68);--static_assert(offsetof(ecs::Sprite, texture) == 0);-static_assert(offsetof(ecs::Sprite, color) == 4);-static_assert(offsetof(ecs::Sprite, size) == 20);-static_assert(offsetof(ecs::Sprite, pivot) == 28);-static_assert(offsetof(ecs::Sprite, uvOffset) == 36);-static_assert(offsetof(ecs::Sprite, uvScale) == 44);-static_assert(offsetof(ecs::Sprite, layer) == 52);-static_assert(offsetof(ecs::Sprite, flipX) == 56);-static_assert(offsetof(ecs::Sprite, flipY) == 57);-static_assert(offsetof(ecs::Sprite, tileSize) == 60);-static_assert(offsetof(ecs::Sprite, tileSpacing) == 68);-static_assert(offsetof(ecs::Sprite, material) == 76);-static_assert(offsetof(ecs::Sprite, enabled) == 80);+// NOTE: Per-field component layout offsets are asserted for ALL components in+// WebBindings.generated.cpp (generated by EHT's PtrLayoutGenerator), which is+// the single source of truth for the pointer ABI. Do not hand-maintain+// static_assert(offsetof(...)) here — they drifted and only covered 8 of N+// components. See docs/REARCHITECTURE.md (root cause 1).int getTransformPtr(ecs::Registry& r, u32 e) {auto* t = r.tryGet<ecs::Transform>(Entity::fromRaw(e));@@ -279,92 +264,36 @@ int getSpritePtr(ecs::Registry& r, u32 e) {return static_cast<int>(reinterpret_cast<uintptr_t>(s));}-// Velocity: 2x vec3 = 24 bytes pure float-static_assert(offsetof(ecs::Velocity, linear) == 0);-static_assert(offsetof(ecs::Velocity, angular) == 12);-int getVelocityPtr(ecs::Registry& r, u32 e) {auto* v = r.tryGet<ecs::Velocity>(Entity::fromRaw(e));if (!v) return 0;return static_cast<int>(reinterpret_cast<uintptr_t>(v));}-// Camera: enum u8 + padding + floats + bool + i32-static_assert(offsetof(ecs::Camera, projectionType) == 0);-static_assert(offsetof(ecs::Camera, fov) == 4);-static_assert(offsetof(ecs::Camera, orthoSize) == 8);-static_assert(offsetof(ecs::Camera, nearPlane) == 12);-static_assert(offsetof(ecs::Camera, farPlane) == 16);-static_assert(offsetof(ecs::Camera, aspectRatio) == 20);-static_assert(offsetof(ecs::Camera, isActive) == 24);-static_assert(offsetof(ecs::Camera, priority) == 28);-static_assert(offsetof(ecs::Camera, viewport) == 32);-static_assert(offsetof(ecs::Camera, clearFlags) == 48);-int getCameraPtr(ecs::Registry& r, u32 e) {auto* c = r.tryGet<ecs::Camera>(Entity::fromRaw(e));if (!c) return 0;return static_cast<int>(reinterpret_cast<uintptr_t>(c));}-// UIRect: 6x vec2 (48 bytes) + computed fields-static_assert(offsetof(ecs::UIRect, anchorMin) == 0);-static_assert(offsetof(ecs::UIRect, anchorMax) == 8);-static_assert(offsetof(ecs::UIRect, offsetMin) == 16);-static_assert(offsetof(ecs::UIRect, offsetMax) == 24);-static_assert(offsetof(ecs::UIRect, size) == 32);-static_assert(offsetof(ecs::UIRect, pivot) == 40);-static_assert(offsetof(ecs::UIRect, computed_size_) == 48);-int getUIRectPtr(ecs::Registry& r, u32 e) {auto* rect = r.tryGet<ecs::UIRect>(Entity::fromRaw(e));if (!rect) return 0;return static_cast<int>(reinterpret_cast<uintptr_t>(rect));}-// RigidBody: enum u8 + padding + floats + bools-static_assert(offsetof(ecs::RigidBody, bodyType) == 0);-static_assert(offsetof(ecs::RigidBody, gravityScale) == 4);-static_assert(offsetof(ecs::RigidBody, linearDamping) == 8);-static_assert(offsetof(ecs::RigidBody, angularDamping) == 12);-static_assert(offsetof(ecs::RigidBody, fixedRotation) == 16);-static_assert(offsetof(ecs::RigidBody, bullet) == 17);-static_assert(offsetof(ecs::RigidBody, enabled) == 18);-int getRigidBodyPtr(ecs::Registry& r, u32 e) {auto* rb = r.tryGet<ecs::RigidBody>(Entity::fromRaw(e));if (!rb) return 0;return static_cast<int>(reinterpret_cast<uintptr_t>(rb));}-// BoxCollider: vec2 + vec2 + floats + bools + u32s-static_assert(offsetof(ecs::BoxCollider, halfExtents) == 0);-static_assert(offsetof(ecs::BoxCollider, offset) == 8);-static_assert(offsetof(ecs::BoxCollider, density) == 16);-static_assert(offsetof(ecs::BoxCollider, friction) == 20);-static_assert(offsetof(ecs::BoxCollider, restitution) == 24);-static_assert(offsetof(ecs::BoxCollider, isSensor) == 28);-static_assert(offsetof(ecs::BoxCollider, enabled) == 29);-static_assert(offsetof(ecs::BoxCollider, categoryBits) == 32);-static_assert(offsetof(ecs::BoxCollider, maskBits) == 36);-int getBoxColliderPtr(ecs::Registry& r, u32 e) {auto* bc = r.tryGet<ecs::BoxCollider>(Entity::fromRaw(e));if (!bc) return 0;return static_cast<int>(reinterpret_cast<uintptr_t>(bc));}-// CircleCollider: f32 + vec2 + floats + bools + u32s-static_assert(offsetof(ecs::CircleCollider, radius) == 0);-static_assert(offsetof(ecs::CircleCollider, offset) == 4);-static_assert(offsetof(ecs::CircleCollider, density) == 12);-static_assert(offsetof(ecs::CircleCollider, friction) == 16);-static_assert(offsetof(ecs::CircleCollider, restitution) == 20);-static_assert(offsetof(ecs::CircleCollider, isSensor) == 24);-static_assert(offsetof(ecs::CircleCollider, enabled) == 25);-static_assert(offsetof(ecs::CircleCollider, categoryBits) == 28);-static_assert(offsetof(ecs::CircleCollider, maskBits) == 32);-int getCircleColliderPtr(ecs::Registry& r, u32 e) {auto* cc = r.tryGet<ecs::CircleCollider>(Entity::fromRaw(e));if (!cc) return 0;diff --git a/tools/eht/__main__.py b/tools/eht/__main__.pyindex 656bc2116..005d7c70c 100644--- a/tools/eht/__main__.py+++ b/tools/eht/__main__.py@@ -5,6 +5,7 @@ import argparsefrom pathlib import Pathfrom .parser import CppParser+from .abi import compute_abi_hashfrom .generators import (EmbindGenerator, TypeScriptGenerator, MetadataGenerator,AnimTargetGenerator, PtrLayoutGenerator, EditorAPIGenerator,@@ -44,6 +45,15 @@ def main() -> int:print("Warning: No components found!")return 1+ # ── Boundary ABI: single source of truth ──+ # Compute pointer layouts and the ABI hash first; both the C++ bindings and+ # the TS metadata embed the same hash so connect() can verify they match.+ ptr_gen = PtrLayoutGenerator(cpp_parser.components, cpp_parser.enums)+ abi_hash = compute_abi_hash(+ cpp_parser.components, cpp_parser.enums, ptr_gen.layouts+ )+ print(f"ABI layout hash: {abi_hash}")+# ── C++ Editor API ──editor_api_path = args.output / 'EditorAPI.generated.cpp'print(f"Generating: {editor_api_path}")@@ -54,31 +64,40 @@ def main() -> int:args.output.mkdir(parents=True, exist_ok=True)embind_path = args.output / 'WebBindings.generated.cpp'print(f"Generating: {embind_path}")- embind_gen = EmbindGenerator(cpp_parser.components, cpp_parser.enums)+ embind_gen = EmbindGenerator(+ cpp_parser.components, cpp_parser.enums,+ layout_asserts=ptr_gen.generate_layout_asserts(),+ abi_hash=abi_hash,+ )embind_path.write_text(embind_gen.generate(), encoding='utf-8')+ # Resolve the TS source directory robustly. Callers historically pass either+ # the package root (`sdk`) or the source dir (`sdk/src`); detect which by+ # looking for the `ecs/` subfolder. Previously a `sdk/src` argument made every+ # `/ 'src' /` path resolve to a non-existent `sdk/src/src`, silently skipping+ # component.generated.ts / ptrLayouts / ptrAccessors. Generation must never+ # silently no-op a file.+ ts_root = args.ts_output+ if (ts_root / 'ecs').is_dir():+ ts_src_dir = ts_root+ else:+ ts_src_dir = ts_root / 'src'+ ts_src_dir.mkdir(parents=True, exist_ok=True)++ def write_ts(rel: str, content: str) -> None:+ out = ts_src_dir / rel+ out.parent.mkdir(parents=True, exist_ok=True)+ print(f"Generating: {out}")+ out.write_text(content, encoding='utf-8')+# ── TypeScript Definitions ──ts_gen = TypeScriptGenerator(cpp_parser.components, cpp_parser.enums)ts_content = ts_gen.generate()-- args.ts_output.mkdir(parents=True, exist_ok=True)- ts_path = args.ts_output / 'wasm.generated.ts'- print(f"Generating: {ts_path}")- ts_path.write_text(ts_content, encoding='utf-8')-- ts_src_path = args.ts_output / 'src' / 'wasm.generated.ts'- if ts_src_path.parent.exists():- print(f"Generating: {ts_src_path}")- ts_src_path.write_text(ts_content, encoding='utf-8')+ write_ts('wasm.generated.ts', ts_content)# ── Component Metadata ──- meta_gen = MetadataGenerator(cpp_parser.components, cpp_parser.enums)- meta_content = meta_gen.generate()-- meta_path = args.ts_output / 'src' / 'component.generated.ts'- if meta_path.parent.exists():- print(f"Generating: {meta_path}")- meta_path.write_text(meta_content, encoding='utf-8')+ meta_gen = MetadataGenerator(cpp_parser.components, cpp_parser.enums, abi_hash=abi_hash)+ write_ts('component.generated.ts', meta_gen.generate())# ── Animation Targets ──anim_gen = AnimTargetGenerator(cpp_parser.components, cpp_parser.enums)@@ -87,22 +106,11 @@ def main() -> int:print(f"Generating: {anim_hpp_path}")anim_hpp_path.write_text(anim_gen.generate_hpp(), encoding='utf-8')- anim_ts_path = args.ts_output / 'src' / 'timeline' / 'animTargets.generated.ts'- if anim_ts_path.parent.exists():- print(f"Generating: {anim_ts_path}")- anim_ts_path.write_text(anim_gen.generate_ts(), encoding='utf-8')+ write_ts('timeline/animTargets.generated.ts', anim_gen.generate_ts())# ── Pointer Layouts & Accessors ──- ptr_gen = PtrLayoutGenerator(cpp_parser.components, cpp_parser.enums)- ptr_path = args.ts_output / 'src' / 'ptrLayouts.generated.ts'- if ptr_path.parent.exists():- print(f"Generating: {ptr_path}")- ptr_path.write_text(ptr_gen.generate(), encoding='utf-8')-- accessor_path = args.ts_output / 'src' / 'ecs' / 'ptrAccessors.generated.ts'- if accessor_path.parent.exists():- print(f"Generating: {accessor_path}")- accessor_path.write_text(ptr_gen.generate_accessors(), encoding='utf-8')+ write_ts('ptrLayouts.generated.ts', ptr_gen.generate())+ write_ts('ecs/ptrAccessors.generated.ts', ptr_gen.generate_accessors())print("[OK] Done!")return 0diff --git a/tools/eht/abi.py b/tools/eht/abi.pynew file mode 100644index 000000000..ef4cc4115--- /dev/null+++ b/tools/eht/abi.py@@ -0,0 +1,52 @@+"""ABI layout hashing — single source of truth for the C++/TS boundary contract.++The hash is computed ONCE here (in Python) from the parsed component schema and+the computed pointer layouts, then emitted verbatim into BOTH the C++ binding+(`getAbiLayoutHash()`) and the TS bundle (`ABI_LAYOUT_HASH`). At `connect()` the+SDK compares the two: a mismatch means the loaded WASM binary and the shipped SDK+were generated from different schemas, so the pointer offsets the SDK uses would+read the wrong bytes. Refusing to run is the only safe response.++This is the runtime half of the keystone. The compile-time half is the generated+`static_assert(offsetof(...))` block, which proves EHT's computed offsets equal+the real compiler layout. Together: TS offset == EHT offset == compiler offset,+and the loaded WASM's schema == the SDK's schema.+"""++import hashlib+from typing import Dict, List++from .data import Component, Enum+++def _canonical(components: List[Component], enums: List[Enum],+ layouts: List[Dict]) -> str:+ """Build an order-independent canonical description of the boundary ABI.++ Components/enums/layouts are sorted by name so the hash is stable regardless+ of filesystem glob order (which is not guaranteed across machines).+ """+ parts: List[str] = []++ for enum in sorted(enums, key=lambda e: e.name):+ vals = ','.join(enum.values)+ parts.append(f'ENUM {enum.name}:{enum.underlying_type}={vals}')++ for comp in sorted(components, key=lambda c: c.name):+ fields = ';'.join(f'{p.name}:{p.cpp_type}' for p in comp.properties)+ parts.append(f'COMP {comp.name}|{fields}')++ for layout in sorted(layouts, key=lambda l: l['name']):+ flds = ';'.join(+ f"{f['name']}:{f['type']}@{f['offset']}" for f in layout['fields']+ )+ parts.append(f"PTR {layout['name']}|{flds}")++ return '\n'.join(parts)+++def compute_abi_hash(components: List[Component], enums: List[Enum],+ layouts: List[Dict]) -> str:+ """Return a stable 16-hex-char digest of the boundary ABI."""+ canonical = _canonical(components, enums, layouts)+ return hashlib.sha1(canonical.encode('utf-8')).hexdigest()[:16]diff --git a/tools/eht/generators/embind.py b/tools/eht/generators/embind.pyindex 712246d42..a6bf57c1a 100644--- a/tools/eht/generators/embind.py+++ b/tools/eht/generators/embind.py@@ -6,10 +6,16 @@ from ..type_system import TypeSystemclass EmbindGenerator:- def __init__(self, components: List[Component], enums: List[Enum]):+ def __init__(self, components: List[Component], enums: List[Enum],+ layout_asserts: str = '', abi_hash: str = ''):self.components = componentsself.enums = enumsself.types = TypeSystem(enums)+ # C++ static_assert(offsetof) block from PtrLayoutGenerator, and the+ # single-source-of-truth ABI hash. Both injected so the boundary+ # contract lives in one generated TU. See tools/eht/abi.py.+ self.layout_asserts = layout_asserts+ self.abi_hash = abi_hashdef generate(self) -> str:lines = self._gen_header()@@ -19,11 +25,40 @@ class EmbindGenerator:lines.extend(self._gen_components())lines.extend(self._gen_registry())lines.extend(self._gen_reflection())+ lines.extend(self._gen_layout_asserts())+ lines.extend(self._gen_abi_hash())lines.append('')lines.append('#endif // ES_PLATFORM_WEB')lines.append('')return '\n'.join(lines)+ def _gen_layout_asserts(self) -> List[str]:+ if not self.layout_asserts:+ return []+ return ['', self.layout_asserts]++ def _gen_abi_hash(self) -> List[str]:+ """Emit getAbiLayoutHash() — the runtime half of the boundary contract.++ Returns the same digest EHT baked into the TS bundle as ABI_LAYOUT_HASH.+ The SDK compares them at connect() and refuses to run on mismatch."""+ return [+ '',+ '// =============================================================================',+ '// ABI Hash -- runtime handshake against the SDK bundle',+ '// =============================================================================',+ '',+ f'static const char* kEsAbiLayoutHash = "{self.abi_hash}";',+ '',+ 'std::string esengineGetAbiLayoutHash() {',+ ' return std::string(kEsAbiLayoutHash);',+ '}',+ '',+ 'EMSCRIPTEN_BINDINGS(esengine_abi) {',+ ' emscripten::function("getAbiLayoutHash", &esengineGetAbiLayoutHash);',+ '}',+ ]+def _gen_header(self) -> List[str]:return ['/**',@@ -35,6 +70,8 @@ class EmbindGenerator:'#ifdef ES_PLATFORM_WEB','','#include <emscripten/bind.h>',+ '#include <cstddef>',+ '#include <string>','#include "../ecs/Registry.hpp"','#include "../math/Math.hpp"','#include "../core/UITypes.hpp"',diff --git a/tools/eht/generators/metadata.py b/tools/eht/generators/metadata.pyindex c42b1d9d6..1840d0abf 100644--- a/tools/eht/generators/metadata.py+++ b/tools/eht/generators/metadata.py@@ -11,11 +11,13 @@ from ..field_utils import (class MetadataGenerator:"""Generates component.generated.ts with defaults and metadata."""- def __init__(self, components: List[Component], enums: List[Enum]):+ def __init__(self, components: List[Component], enums: List[Enum],+ abi_hash: str = ''):self.components = componentsself.enums = enumsself.types = TypeSystem(enums)self._enum_values = build_enum_value_map(enums)+ self.abi_hash = abi_hashdef _get_asset_fields(self, comp: Component) -> List[Dict[str, str]]:fields = []@@ -74,6 +76,14 @@ class MetadataGenerator:'',"import type { AssetFieldType } from './scene';",'',+ '/**',+ ' * Single-source-of-truth hash of the C++/TS boundary ABI (component',+ ' * schema + pointer layouts). The WASM module exposes the same digest via',+ ' * getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to',+ ' * run on mismatch, because mismatched offsets read the wrong heap bytes.',+ ' */',+ f"export const ABI_LAYOUT_HASH = '{self.abi_hash}';",+ '','export interface AssetFieldMeta {',' field: string;',' type: AssetFieldType;',diff --git a/tools/eht/generators/ptr_layout.py b/tools/eht/generators/ptr_layout.pyindex 1f3de6ee8..33250bcf6 100644--- a/tools/eht/generators/ptr_layout.py+++ b/tools/eht/generators/ptr_layout.py@@ -99,12 +99,43 @@ class PtrLayoutGenerator:offset += sizeif fields:+ full = f'{comp.namespace}::{comp.name}' if comp.namespace else comp.nameself.layouts.append({'name': comp.name,+ 'cpp_full': full,'ptrFn': f'get{comp.name}Ptr','fields': fields,})+ def generate_layout_asserts(self) -> str:+ """Emit a C++ static_assert(offsetof) for every pointer-accessed field.++ This makes the *compiler* the authority on struct layout: EHT computes+ each offset, and these asserts prove the real compiler layout agrees.+ Any divergence (a reordered/retyped field, a packing surprise EHT's+ model doesn't capture) becomes a BUILD ERROR rather than a silent+ cross-boundary heap-corruption at runtime. Injected into the web-only+ WebBindings.generated.cpp, which already includes every component header.+ """+ lines = [+ '// =============================================================================',+ '// ABI Layout Asserts -- the compiler is the offset authority',+ '// =============================================================================',+ '// EHT computes each pointer-field offset; the asserts below prove the real',+ '// compiler layout matches. A failure here means the TS pointer accessors would',+ '// read the wrong bytes -- fix the struct or regenerate EHT. DO NOT EDIT.',+ '',+ ]+ for layout in self.layouts:+ full = layout['cpp_full']+ for f in layout['fields']:+ msg = f'ABI offset drift: {full}.{f["name"]} (EHT expected {f["offset"]})'+ lines.append(+ f'static_assert(offsetof({full}, {f["name"]}) == {f["offset"]}, "{msg}");'+ )+ lines.append('')+ return '\n'.join(lines)+def generate(self) -> str:lines = ['/**',