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(aot): compiled TypeScript moves a real Registry
yhh73837a67de22
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 1c0aa0943..363c3b161 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -31,7 +31,7 @@ env:test_compressed_format test_batch_builder test_boundary_span test_webgpu_devicetest_clip_depth test_shadow_atlastest_text_edit test_render_graph test_device_loss test_physics_interpolation- test_bitmap_font test_texture_cache+ test_bitmap_font test_texture_cache test_aot_hostjobs:build-emscripten:diff --git a/compiler/src/codegen.ts b/compiler/src/codegen.tsindex 515b5943a..2b248ff83 100644--- a/compiler/src/codegen.ts+++ b/compiler/src/codegen.ts@@ -53,7 +53,14 @@ export const ADDR_MIX = '0x9e3779b97f4a7c15';export interface CModule {/** `estella_abi.h` — the contract's C side, and the only thing the code calls. */readonly header: string;- /** The translation unit: offsets, module functions, systems. */+ /**+ * `estella_offsets.h` — where each field this program touches lives, from+ * EHT. Its own header rather than part of the source, because the engine+ * side has to assert against the SAME numbers: an `offsetof` that disagrees+ * with one of these is a read of a different field.+ */+ readonly offsets: string;+ /** The translation unit: module functions and systems. */readonly source: string;/** Exported symbols, one per compiled system. */readonly symbols: readonly string[];@@ -649,10 +656,24 @@ export function emitC(module: EirModule, layout: AbiLayout, systems: readonly Eiconst hash = abiHash(layout, plans);const macros = [...offsets].sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `#define ${k} ${v}u`);+ const offsetsHeader = [+ '/* GENERATED by @estella/compiler — do not edit. */',+ '/* Field offsets from EHT, for the systems this program compiled. The',+ ' engine side asserts its own offsetof against these: a disagreement is',+ ' a read of a DIFFERENT FIELD, not an error. */',+ '#ifndef ESTELLA_OFFSETS_H',+ '#define ESTELLA_OFFSETS_H',+ '',+ ...macros,+ '',+ '#endif /* ESTELLA_OFFSETS_H */',+ '',+ ].join('\n');const source = ['/* GENERATED by @estella/compiler — do not edit. */','/* docs/REARCH_AOT_ABI.md: this file calls the engine zero times. */','#include "estella_abi.h"',+ '#include "estella_offsets.h"','','/* §2.5: the loader compares this before it maps anything. A mismatch is',' not a wrong answer, it is a read of a different field.',@@ -663,13 +684,16 @@ export function emitC(module: EirModule, layout: AbiLayout, systems: readonly Ei'const uint64_t es_abi_hash =',` ES_ABI_CONTRACT_HASH ^ (${ADDR_MIX}ULL * (uint64_t)sizeof(es_addr_t));`,'',- '/* Component and resource field offsets, from EHT. */',- ...macros,- '',...bodies,].join('\n');- return { header: RUNTIME_H, source, symbols: systems.map((s) => cSymbol(s.name)), hash };+ return {+ header: RUNTIME_H,+ offsets: offsetsHeader,+ source,+ symbols: systems.map((s) => cSymbol(s.name)),+ hash,+ };}/** Module functions still called after the inliner ran, in declaration order. */diff --git a/compiler/tests/codegen.test.ts b/compiler/tests/codegen.test.tsindex c3f9ff9f5..69709bbdf 100644--- a/compiler/tests/codegen.test.ts+++ b/compiler/tests/codegen.test.ts@@ -180,6 +180,7 @@ type Addressing = 'offset' | 'pointer';function build(dir: string, cModule: CModule, symbol: string, how: Addressing = 'offset'): string {mkdirSync(dir, { recursive: true });writeFileSync(join(dir, 'estella_abi.h'), cModule.header);+ writeFileSync(join(dir, 'estella_offsets.h'), cModule.offsets);writeFileSync(join(dir, 'systems.c'), cModule.source);writeFileSync(join(dir, 'main.c'), MAIN_C);const exe = join(dir, `${symbol}${process.platform === 'win32' ? '.exe' : ''}`);@@ -444,7 +445,8 @@ describe('the emitted C says what the interpreter says', () => {expect(cam.leaves.get('priority')!.enc).toBe('i32');const { source } = emitC(fixtures.module, layout, [systemOf(fixtures, 'FixtureCamera')]);- expect(source).toContain('#define ES_OFF_Camera_isActive 24u');+ expect(emitC(fixtures.module, layout, [systemOf(fixtures, 'FixtureCamera')]).offsets)+ .toContain('#define ES_OFF_Camera_isActive 24u');// One byte. Read as a float it would take three bytes of `priority` with// it, and produce a number rather than an error.expect(source).toMatch(/es_bool\(\w+ \+ ES_OFF_Camera_isActive\)/);@@ -477,6 +479,7 @@ describe('the emitted C says what the interpreter says', () => {const dir = join(tmp, 'imports');mkdirSync(dir, { recursive: true });writeFileSync(join(dir, 'estella_abi.h'), cModule.header);+ writeFileSync(join(dir, 'estella_offsets.h'), cModule.offsets);writeFileSync(join(dir, 'systems.c'), cModule.source);const obj = join(dir, 'systems.o');const out = spawnSync(CC!, [...CFLAGS, '-Wall', '-Wextra', '-c',@@ -522,6 +525,7 @@ describe('the emitted C says what the interpreter says', () => {const dir = join(tmp, 'handshake');mkdirSync(dir, { recursive: true });writeFileSync(join(dir, 'estella_abi.h'), c.header);+ writeFileSync(join(dir, 'estella_offsets.h'), c.offsets);writeFileSync(join(dir, 'systems.c'), c.source);writeFileSync(join(dir, 'main.c'), ['#include <stdio.h>',@@ -555,7 +559,8 @@ describe('the emitted C says what the interpreter says', () => {const { source } = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);// §4.2's whole reason for existing, readable in the output itself.expect(source).toMatch(/es_f32\(\w+ \+ ES_OFF_Transform_position_x\)/);- expect(source).toMatch(/#define ES_OFF_Transform_position_x \d+u/);+ expect(emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]).offsets)+ .toMatch(/#define ES_OFF_Transform_position_x \d+u/);// And the thing v0 had that v1 does not: a call back across the boundary.expect(source).not.toMatch(/\bes_abi_\w+\(/);});diff --git a/compiler/tests/generated.test.ts b/compiler/tests/generated.test.tsnew file mode 100644index 000000000..918054706--- /dev/null+++ b/compiler/tests/generated.test.ts@@ -0,0 +1,81 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file generated.test.ts+ * @brief The C artifacts the engine builds against, and their freshness.+ *+ * @details The C++ side has to compile without running this compiler, so the+ * contract header and one compiled system are checked in. Checked-in+ * generated files drift, so this regenerates them and compares — the+ * same bargain EHT's outputs already make.+ *+ * To refresh after changing the code generator:+ *+ * ESTELLA_AOT_WRITE=1 pnpm --filter @estella/compiler test+ */+import { describe, it, expect } from 'vitest';+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++import { lowerProgram, brokenPromises } from '../src/frontend';+import { verifySystem } from '../src/verify';+import { inlineSystem } from '../src/inline';+import { builtinShapes } from '../src/builtins';+import { packLayout } from '../src/abi';+import { emitC } from '../src/codegen';++const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));+const WRITE = process.env['ESTELLA_AOT_WRITE'] === '1';++/** The one system the corpus marks `@compiled`, which is what makes it a fixture+ * worth checking in: it is shipped code, not something written for a test. */+const result = lowerProgram([+ resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),+ resolve(ROOT, 'examples/ecs-basics/src/components.ts'),+], builtinShapes());++function artifact(path: string, want: string): void {+ if (WRITE) {+ mkdirSync(dirname(path), { recursive: true });+ writeFileSync(path, want);+ return;+ }+ const rel = path.slice(ROOT.length + 1);+ expect(existsSync(path), `${rel} is missing — regenerate with ESTELLA_AOT_WRITE=1`).toBe(true);+ // Normalised: git may have handed the working tree CRLF, and the difference+ // is not one anybody wants a diff about.+ const have = readFileSync(path, 'utf8').replace(/\r\n/g, '\n');+ expect(have, `${rel} is stale — regenerate with ESTELLA_AOT_WRITE=1`).toBe(want);+}++describe('the C artifacts the engine builds against', () => {+ const move = result.module.systems.find((s) => s.name === 'MoveSystem');++ it('lowers the promised system', () => {+ expect(brokenPromises(result)).toEqual([]);+ expect(move).toBeDefined();+ expect(verifySystem(move!, result.module.comps, result.module.fns)).toEqual([]);+ });++ const layout = packLayout(result.module.comps);+ const c = emitC(result.module, layout, [inlineSystem(move!, result.module.fns)]);++ it('the contract header, where the engine can include it', () => {+ artifact(join(ROOT, 'src/esengine/aot/estella_abi.h'), c.header);+ });++ it('the offsets and the system, where the harness can build them', () => {+ artifact(join(ROOT, 'tests/aot/generated/estella_offsets.h'), c.offsets);+ artifact(join(ROOT, 'tests/aot/generated/move_system.c'), c.source);+ });++ it('and the hash the harness compares, so it is not a second copy', () => {+ artifact(join(ROOT, 'tests/aot/generated/move_system_hash.h'), [+ '/* GENERATED by @estella/compiler — do not edit. */',+ '/* The contract half of the handshake. The width half is the harness. */',+ `#define ES_EXPECTED_CONTRACT_HASH 0x${c.hash}ULL`,+ '',+ ].join('\n'));+ });+});diff --git a/src/esengine/aot/AotHost.hpp b/src/esengine/aot/AotHost.hppnew file mode 100644index 000000000..f8762942b--- /dev/null+++ b/src/esengine/aot/AotHost.hpp@@ -0,0 +1,135 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file AotHost.hpp+ * @brief The host half of the Estella ABI (docs/REARCH_AOT_ABI.md §2.1).+ *+ * @details A compiled system calls the engine ZERO times, which means everything+ * it reads has to be in memory before the call. This puts it there:+ * pack the rows, resolve the resource addresses, zero the count, fill+ * the SysCtx, call, and hand back what the system wrote.+ *+ * It does not know about Registry. A component is reached through a+ * resolver the caller supplies, because the caller is where the+ * component's TYPE is known — and that is also what lets this be tested+ * without linking the engine.+ *+ * The arena is reused across calls and rebuilt in each one, because+ * §2.2 gives a row array a one-call lifetime. Nothing here allocates+ * per row after the first frame at a given size.+ */+#pragma once++#include <cstdint>+#include <functional>+#include <span>+#include <vector>++#include "estella_abi.h"++namespace esengine::aot {++/** What a compiled system is: one exported symbol, taking the ctx. */+using SystemFn = void (*)(es_addr_t);++/**+ * Where one component's bytes are for an entity, or `nullptr` if it has none.+ * Supplied per component by the layer that knows its type — a generated binding,+ * or a test.+ */+using ComponentAt = std::function<void*(std::uint32_t)>;++/** One declared `Query`: its components, in the order the query names them. */+struct QuerySpec {+ std::vector<ComponentAt> comps;+};++/**+ * The scratch a call needs. Held by the caller so the vectors keep their+ * capacity between frames; every `run` overwrites it and nothing survives.+ */+class CallArena {+public:+ explicit CallArena(std::uint32_t cmdCap = 256) : cmds_(cmdCap) {}++ /** How many command records the system may write before it must stop. */+ std::uint32_t commandCapacity() const { return static_cast<std::uint32_t>(cmds_.size()); }++private:+ friend std::span<const EsCmd> run(SystemFn, std::span<const std::uint32_t>,+ std::span<const QuerySpec>, std::span<void* const>, CallArena&);+ std::vector<es_addr_t> rows_;+ std::vector<EsQueryRows> queries_;+ std::vector<es_addr_t> resources_;+ std::vector<EsCmd> cmds_;+ std::uint32_t count_ = 0;+ EsSysCtx ctx_{};+};++/**+ * Materialise, call, and return the commands the system produced. A row is kept+ * only when every component resolves for it — `View.hpp`'s strategy exposed, so+ * the caller passes the smallest pool it has. Applying the commands is the+ * CALLER's job: a despawn here invalidates the rows just handed over.+ */+inline std::span<const EsCmd> run(SystemFn fn,+ std::span<const std::uint32_t> candidates,+ std::span<const QuerySpec> queries,+ std::span<void* const> resources,+ CallArena& arena) {+ arena.rows_.clear();+ arena.queries_.assign(queries.size(), EsQueryRows{});+ arena.resources_.assign(resources.size(), es_addr_t{});++ // Offsets first, addresses after: one vector holding every query's rows+ // moves under the first query's pointer as the second grows, and the ctx+ // has to point at something that will still be there during the call.+ std::vector<std::size_t> starts(queries.size());+ std::vector<std::uint32_t> counts(queries.size(), 0);+ for (std::size_t q = 0; q < queries.size(); ++q) {+ starts[q] = arena.rows_.size();+ const auto& comps = queries[q].comps;+ for (std::uint32_t e : candidates) {+ const std::size_t mark = arena.rows_.size();+ arena.rows_.push_back(static_cast<es_addr_t>(e));+ bool complete = true;+ for (const auto& at : comps) {+ void* p = at(e);+ if (p == nullptr) { complete = false; break; }+ arena.rows_.push_back(reinterpret_cast<es_addr_t>(p));+ }+ if (complete) ++counts[q];+ else arena.rows_.resize(mark);+ }+ }+ for (std::size_t q = 0; q < queries.size(); ++q) {+ arena.queries_[q].rows = reinterpret_cast<es_addr_t>(arena.rows_.data() + starts[q]);+ arena.queries_[q].count = counts[q];+ }+ for (std::size_t r = 0; r < resources.size(); ++r) {+ arena.resources_[r] = reinterpret_cast<es_addr_t>(resources[r]);+ }++ arena.count_ = 0;+ arena.ctx_.queries = reinterpret_cast<es_addr_t>(arena.queries_.data());+ arena.ctx_.resources = reinterpret_cast<es_addr_t>(arena.resources_.data());+ arena.ctx_.cmdBuf = reinterpret_cast<es_addr_t>(arena.cmds_.data());+ arena.ctx_.cmdCap = arena.commandCapacity();+ arena.ctx_.cmdCount = reinterpret_cast<es_addr_t>(&arena.count_);+ arena.ctx_.events = 0;++ fn(reinterpret_cast<es_addr_t>(&arena.ctx_));++ return std::span<const EsCmd>(arena.cmds_.data(), arena.count_);+}++/**+ * The constant a compiled artifact exports, as this host computes it. The+ * contract half comes from the artifact; the width is ours, and mixing it here+ * is what stops a 32-bit artifact loading into a 64-bit host (§2.5).+ */+inline std::uint64_t abiHash(std::uint64_t contract) {+ return contract ^ (0x9e3779b97f4a7c15ULL * sizeof(es_addr_t));+}++} // namespace esengine::aotdiff --git a/src/esengine/aot/estella_abi.h b/src/esengine/aot/estella_abi.hnew file mode 100644index 000000000..96922d88e--- /dev/null+++ b/src/esengine/aot/estella_abi.h@@ -0,0 +1,130 @@+/* GENERATED by @estella/compiler — do not edit. */+/* The Estella ABI, C side. docs/REARCH_AOT_ABI.md */+#ifndef ESTELLA_ABI_H+#define ESTELLA_ABI_H++#include <stdint.h>+#include <string.h>+#include <math.h>++/* A fused multiply-add is MORE accurate than the double rounding JS does, and+ more accurate is still a different number. GCC does not implement this pragma+ and warns about it, so the flag in CFLAGS is the one that has to be there. */+#if defined(__clang__)+#pragma STDC FP_CONTRACT OFF+#endif++/* An address is a POINTER, and on wasm32 a pointer IS a 32-bit offset into+ linear memory — which is why one emitted source serves both back ends. The+ OFFSETS below are the contract; the address width is the machine, and it is+ mixed into the handshake so a 32-bit artifact cannot load into a 64-bit host.++ ES_ADDR_BASE is the other model: a host that owns one block and addresses it+ by offset. A wasm2c deployment (§5) is one, and so is the differential+ harness. Same structs, same offsets, one word wider or narrower. */+#if defined(ES_ADDR_BASE)+typedef uint32_t es_addr_t;+extern unsigned char *es_memory;+#define ES_PTR(a) (es_memory + (a))+#else+typedef uintptr_t es_addr_t;+#define ES_PTR(a) ((unsigned char *)(a))+#endif++/* §2.2 — the packed rows the host materialised: for each row, the entity and+ then one base address per component the query named, in that order. */+typedef struct EsQueryRows {+ es_addr_t rows;+ es_addr_t count;+} EsQueryRows;++/* §2.3 — four u32, sixteen bytes, at every address width. */+typedef struct EsCmd {+ uint32_t kind;+ uint32_t a;+ uint32_t b;+ uint32_t c;+} EsCmd;++#define ES_CMD_DESPAWN 1u+#define ES_CMD_REMOVE 2u++/* §2.1 — 6 addresses. §6.3 makes that a number needing a reason to grow. */+typedef struct EsSysCtx {+ es_addr_t queries;+ es_addr_t resources;+ es_addr_t cmdBuf;+ es_addr_t cmdCap;+ es_addr_t cmdCount;+ es_addr_t events;+} EsSysCtx;++/* §6.1 asks that the C and TS sides of these structs have ONE author, and that a+ hand-written side fail to compile. The numbers below are written by that author+ (compiler/src/abi.ts) into this file; these three declarations are how C says+ no if a struct above ever stops matching them. */+typedef char es_check_sysctx[sizeof(EsSysCtx) == 6 * sizeof(es_addr_t) ? 1 : -1];+typedef char es_check_rows[sizeof(EsQueryRows) == 2 * sizeof(es_addr_t) ? 1 : -1];+typedef char es_check_cmd[sizeof(EsCmd) == 4 * 4 ? 1 : -1];++/* memcpy, not a cast through a typed pointer: a component base is whatever the+ host handed over, and a wider load through an under-aligned pointer is+ undefined even where the hardware would have allowed it. */+static inline double es_f32(const unsigned char *p) { float v; memcpy(&v, p, 4); return (double)v; }+static inline void es_set_f32(unsigned char *p, double v) { float f = (float)v; memcpy(p, &f, 4); }+static inline double es_f64(const unsigned char *p) { double v; memcpy(&v, p, 8); return v; }+static inline void es_set_f64(unsigned char *p, double v) { memcpy(p, &v, 8); }++/* A bool in the C++ structs is ONE byte. Reading it as a float would read three+ bytes of whatever follows it, which is a value rather than an error. */+static inline int es_bool(const unsigned char *p) { return *p != 0; }+static inline void es_set_bool(unsigned char *p, int v) { *p = (unsigned char)(v ? 1 : 0); }++/* ---------------------------------------------------------------------------+ Math. Only the operations ECMAScript specifies EXACTLY are in the subset, but+ "exactly specified" is not the same as "what libm does" — three of them+ differ, and each difference is one bit of one pixel that would take a day to+ find. So each is written out rather than forwarded.+ --------------------------------------------------------------------------- */+static inline double es_abs(double x) { return fabs(x); }+static inline double es_floor(double x) { return floor(x); }+static inline double es_ceil(double x) { return ceil(x); }+static inline double es_trunc(double x) { return trunc(x); }+static inline double es_sqrt(double x) { return sqrt(x); }++/* Math.sign returns x itself for NaN and for both zeroes, so the sign of zero+ survives — and the sign of zero is a distinct bit pattern in the image. */+static inline double es_sign(double x) {+ if (isnan(x) || x == 0.0) return x;+ return x > 0.0 ? 1.0 : -1.0;+}++/* C's round() breaks ties AWAY from zero; ECMAScript breaks them toward +Inf.+ And floor(x + 0.5) — the usual fix — is wrong for the double just below 0.5,+ where the addition itself rounds up to 1. Subtracting the floor is exact for+ every finite x, so the comparison sees the true fraction. */+static inline double es_round(double x) {+ if (!isfinite(x) || x == 0.0) return x;+ double f = floor(x);+ double r = (x - f) < 0.5 ? f : f + 1.0;+ /* Math.round(-0.2) is -0, and -0 is not the same bytes as +0. */+ return (r == 0.0 && x < 0.0) ? -0.0 : r;+}++/* fmin/fmax return the non-NaN operand and are free to pick either zero;+ Math.min/max propagate NaN and distinguish -0 from +0. */+static inline double es_min(double a, double b) {+ if (isnan(a) || isnan(b)) return (double)NAN;+ if (a == b) return signbit(a) ? a : b;+ return a < b ? a : b;+}+static inline double es_max(double a, double b) {+ if (isnan(a) || isnan(b)) return (double)NAN;+ if (a == b) return signbit(a) ? b : a;+ return a > b ? a : b;+}++/* JS % on doubles is the truncated remainder, which is fmod. */+static inline double es_rem(double a, double b) { return fmod(a, b); }++#endif /* ESTELLA_ABI_H */diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txtindex 6624c5d6b..b286df7ed 100644--- a/tests/CMakeLists.txt+++ b/tests/CMakeLists.txt@@ -31,6 +31,32 @@ add_executable(test_tilemaptarget_link_libraries(test_tilemap PRIVATE esengine)add_test(NAME test_tilemap COMMAND test_tilemap)+# AOT: compiled TypeScript against a real Registry. The .c is generated by+# @estella/compiler and checked in (compiler/tests/generated.test.ts keeps it+# fresh); this harness is what holds the generated OFFSETS against the C+++# structs they are claims about. Header-only ECS + Log.cpp, so it builds without+# linking esengine and therefore without emscripten.+add_executable(test_aot_host+ aot/test_aot_host.cpp+ aot/generated/move_system.c+ ${CMAKE_SOURCE_DIR}/src/esengine/core/Log.cpp+)+target_include_directories(test_aot_host PRIVATE+ ${CMAKE_SOURCE_DIR}/src+ ${CMAKE_SOURCE_DIR}/src/esengine/aot+ ${CMAKE_SOURCE_DIR}/tests/aot+ ${CMAKE_SOURCE_DIR}/third_party/glm+)+# -ffp-contract=off is part of the contract, not a preference: a fused+# multiply-add is more accurate than the two roundings JS does, and more+# accurate is still a different number (compiler/src/codegen.ts CFLAGS).+target_compile_options(test_aot_host PRIVATE+ $<$<C_COMPILER_ID:GNU,Clang,AppleClang>:-ffp-contract=off>+ $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-ffp-contract=off>+ $<$<CXX_COMPILER_ID:MSVC>:/fp:precise>+)+add_test(NAME test_aot_host COMMAND test_aot_host)+# SparseSet testsadd_executable(test_sparse_setecs/test_sparse_set.cppdiff --git a/tests/aot/generated/estella_offsets.h b/tests/aot/generated/estella_offsets.hnew file mode 100644index 000000000..9bcc492b0--- /dev/null+++ b/tests/aot/generated/estella_offsets.h@@ -0,0 +1,15 @@+/* GENERATED by @estella/compiler — do not edit. */+/* Field offsets from EHT, for the systems this program compiled. The+ engine side asserts its own offsetof against these: a disagreement is+ a read of a DIFFERENT FIELD, not an error. */+#ifndef ESTELLA_OFFSETS_H+#define ESTELLA_OFFSETS_H++#define ES_OFF_Mover_directionX 8u+#define ES_OFF_Mover_directionY 16u+#define ES_OFF_Mover_speed 0u+#define ES_OFF_Time_delta 0u+#define ES_OFF_Transform_position_x 0u+#define ES_OFF_Transform_position_y 4u++#endif /* ESTELLA_OFFSETS_H */diff --git a/tests/aot/generated/move_system.c b/tests/aot/generated/move_system.cnew file mode 100644index 000000000..4f9480443--- /dev/null+++ b/tests/aot/generated/move_system.c@@ -0,0 +1,31 @@+/* GENERATED by @estella/compiler — do not edit. */+/* docs/REARCH_AOT_ABI.md: this file calls the engine zero times. */+#include "estella_abi.h"+#include "estella_offsets.h"++/* §2.5: the loader compares this before it maps anything. A mismatch is+ not a wrong answer, it is a read of a different field.+ The address width belongs to the MACHINE, not to the contract, so it+ mixes in here rather than in the compiler: one hash per (contract,+ width) pair, and a 32-bit artifact cannot load into a 64-bit host. */+#define ES_ABI_CONTRACT_HASH 0x52ced52de3f13ce2ULL+const uint64_t es_abi_hash =+ ES_ABI_CONTRACT_HASH ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));++void es_sys_MoveSystem(es_addr_t es_ctx) {+ const EsSysCtx *es_c = (const EsSysCtx *)ES_PTR(es_ctx);+ const EsQueryRows *es_queries = (const EsQueryRows *)ES_PTR(es_c->queries);+ const es_addr_t *es_resources = (const es_addr_t *)ES_PTR(es_c->resources);+ unsigned char *time_1 = ES_PTR(es_resources[0]);+ {+ const es_addr_t *es_rows0 = (const es_addr_t *)ES_PTR(es_queries[0].rows);+ const es_addr_t es_n0 = es_queries[0].count;+ for (es_addr_t es_i0 = 0; es_i0 < es_n0; ++es_i0) {+ const es_addr_t *es_row0 = es_rows0 + es_i0 * 3u;+ unsigned char *transform_3 = ES_PTR(es_row0[1]);+ unsigned char *mover_4 = ES_PTR(es_row0[2]);+ es_set_f32(transform_3 + ES_OFF_Transform_position_x, (es_f32(transform_3 + ES_OFF_Transform_position_x) + ((es_f64(mover_4 + ES_OFF_Mover_directionX) * es_f64(mover_4 + ES_OFF_Mover_speed)) * es_f64(time_1 + ES_OFF_Time_delta))));+ es_set_f32(transform_3 + ES_OFF_Transform_position_y, (es_f32(transform_3 + ES_OFF_Transform_position_y) + ((es_f64(mover_4 + ES_OFF_Mover_directionY) * es_f64(mover_4 + ES_OFF_Mover_speed)) * es_f64(time_1 + ES_OFF_Time_delta))));+ }+ }+}diff --git a/tests/aot/generated/move_system_hash.h b/tests/aot/generated/move_system_hash.hnew file mode 100644index 000000000..1cbc4e9ab--- /dev/null+++ b/tests/aot/generated/move_system_hash.h@@ -0,0 +1,3 @@+/* GENERATED by @estella/compiler — do not edit. */+/* The contract half of the handshake. The width half is the harness. */+#define ES_EXPECTED_CONTRACT_HASH 0x52ced52de3f13ce2ULLdiff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cppnew file mode 100644index 000000000..0d267b41b--- /dev/null+++ b/tests/aot/test_aot_host.cpp@@ -0,0 +1,206 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file test_aot_host.cpp+ * @brief Compiled TypeScript, run against a real Registry.+ *+ * @details Everything before this ran the emitted C over an image a JS test had+ * laid out, which meant the offsets only ever had to agree with the+ * compiler's own idea of them. Here they have to agree with the C+++ * structs, and `Transform` is a real `ecs::Transform` out of a real+ * `ecs::Registry` — the thing the offsets were always claims ABOUT.+ *+ * What it asks:+ * 1. the generated offsets ARE the struct's, checked against the+ * address of the field itself rather than against a second table;+ * 2. the compiled system moves the registry the way the same loop+ * written in C++ moves it, to the bit;+ * 3. the host and the artifact agree on the handshake constant.+ *+ * `Mover` and `Time` have no C++ struct — they are a ScriptStorage+ * record and a host resource — so the host lays them out, and the+ * structs below are that layout. Those static_asserts are the check+ * that it has not moved under them.+ */+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN+#include <doctest.h>++#include <cstddef>+#include <cstdint>+#include <vector>++#include "esengine/aot/AotHost.hpp"+#include "esengine/ecs/Registry.hpp"+#include "esengine/ecs/components/Transform.hpp"++extern "C" {+#include "generated/estella_offsets.h"+#include "generated/move_system_hash.h"+/** The compiled system. One symbol, and it calls nothing. */+void es_sys_MoveSystem(es_addr_t ctx);+extern const std::uint64_t es_abi_hash;+}++using namespace esengine;++namespace {++/** `defineComponent('Mover', …)` lands in ScriptStorage, so the ABI lays it out:+ * declaration order, f64 each, because a JS record has no narrower number. */+struct MoverRow {+ double speed;+ double directionX;+ double directionY;+};+static_assert(offsetof(MoverRow, speed) == ES_OFF_Mover_speed, "Mover.speed moved");+static_assert(offsetof(MoverRow, directionX) == ES_OFF_Mover_directionX, "Mover.directionX moved");+static_assert(offsetof(MoverRow, directionY) == ES_OFF_Mover_directionY, "Mover.directionY moved");++/** The resource, likewise host-side. Only `delta` is reached here. */+struct TimeRow {+ double delta;+};+static_assert(offsetof(TimeRow, delta) == ES_OFF_Time_delta, "Time.delta moved");++/** Byte distance from a component's base to one of its fields. Taken from the+ * live object rather than with offsetof, because glm's vectors are not types+ * offsetof is defined for. */+template <typename C, typename F>+std::size_t fieldOffset(const C& obj, const F& field) {+ return static_cast<std::size_t>(reinterpret_cast<const unsigned char*>(&field)+ - reinterpret_cast<const unsigned char*>(&obj));+}++struct World {+ ecs::Registry registry;+ std::vector<std::uint32_t> entities;+ std::vector<MoverRow> movers; // index-parallel with `entities`+ TimeRow time{1.0 / 30.0};+};++constexpr int ENTITY_COUNT = 24;++/** The same starting world every time, spread over signs and magnitudes. */+World makeWorld() {+ World w;+ for (int i = 1; i <= ENTITY_COUNT; ++i) {+ Entity e = w.registry.create();+ auto& t = w.registry.emplace<ecs::Transform>(e);+ t.position.x = static_cast<float>((i % 7) * 13 - 40);+ t.position.y = static_cast<float>((i % 5) * 9 - 20);+ w.entities.push_back(e.id());+ w.movers.push_back(MoverRow{+ 40.0 + (i % 6) * 15.0,+ static_cast<double>((i % 3) - 1),+ ((i % 4) - 2) / 2.0,+ });+ }+ return w;+}++/** What move.ts says, written out in C++. The oracle: if the compiled system+ * disagrees with this, one of them is wrong about the struct. */+void moveByHand(World& w) {+ for (std::size_t i = 0; i < w.entities.size(); ++i) {+ auto* t = w.registry.tryGet<ecs::Transform>(Entity::fromRaw(w.entities[i]));+ const MoverRow& m = w.movers[i];+ t->position.x = static_cast<float>(static_cast<double>(t->position.x)+ + m.directionX * m.speed * w.time.delta);+ t->position.y = static_cast<float>(static_cast<double>(t->position.y)+ + m.directionY * m.speed * w.time.delta);+ }+}++/** One frame through the contract. */+void moveByCompiledCode(World& w, aot::CallArena& arena) {+ aot::QuerySpec q;+ q.comps.push_back([&w](std::uint32_t e) -> void* {+ return w.registry.tryGet<ecs::Transform>(Entity::fromRaw(e));+ });+ q.comps.push_back([&w](std::uint32_t e) -> void* {+ for (std::size_t i = 0; i < w.entities.size(); ++i) {+ if (w.entities[i] == e) return &w.movers[i];+ }+ return nullptr;+ });+ void* resources[] = { &w.time };+ aot::QuerySpec queries[] = { q };+ const auto cmds = aot::run(&es_sys_MoveSystem, w.entities, queries, resources, arena);+ CHECK(cmds.empty()); // MoveSystem writes no commands+}++} // namespace++TEST_CASE("the generated offsets are the C++ struct's, not a second table") {+ ecs::Transform t;+ CHECK(fieldOffset(t, t.position.x) == ES_OFF_Transform_position_x);+ CHECK(fieldOffset(t, t.position.y) == ES_OFF_Transform_position_y);+ // The point of asking: reading position.y at the wrong offset returns a+ // number rather than an error, and every frame after it is quietly wrong.+ CHECK(ES_OFF_Transform_position_y - ES_OFF_Transform_position_x == sizeof(float));+}++TEST_CASE("the host and the artifact agree on the handshake") {+ CHECK(es_abi_hash == aot::abiHash(ES_EXPECTED_CONTRACT_HASH));+}++TEST_CASE("a compiled system moves a real Registry exactly as C++ does") {+ World byHand = makeWorld();+ World byCode = makeWorld();+ aot::CallArena arena;++ for (int frame = 0; frame < 30; ++frame) {+ moveByHand(byHand);+ moveByCompiledCode(byCode, arena);++ for (std::size_t i = 0; i < byHand.entities.size(); ++i) {+ const auto* want = byHand.registry.tryGet<ecs::Transform>(Entity::fromRaw(byHand.entities[i]));+ const auto* got = byCode.registry.tryGet<ecs::Transform>(Entity::fromRaw(byCode.entities[i]));+ REQUIRE(want != nullptr);+ REQUIRE(got != nullptr);+ // Both sides round through float on every store, so this is exact.+ CHECK(got->position.x == want->position.x);+ CHECK(got->position.y == want->position.y);+ }+ }++ // A world nothing moved would pass the comparison above trivially.+ const World fresh = makeWorld();+ const auto* moved = byCode.registry.tryGet<ecs::Transform>(Entity::fromRaw(byCode.entities[1]));+ const auto* start = fresh.registry.tryGet<ecs::Transform>(Entity::fromRaw(fresh.entities[1]));+ CHECK(moved->position.x != start->position.x);+}++TEST_CASE("a row the query cannot complete is not a row") {+ World w = makeWorld();+ aot::CallArena arena;+ // Take Transform away from one entity: it has a Mover, so only the filter+ // keeps it out of the walk.+ w.registry.remove<ecs::Transform>(Entity::fromRaw(w.entities[3]));++ aot::QuerySpec q;+ q.comps.push_back([&w](std::uint32_t e) -> void* {+ return w.registry.tryGet<ecs::Transform>(Entity::fromRaw(e));+ });+ q.comps.push_back([&w](std::uint32_t e) -> void* {+ for (std::size_t i = 0; i < w.entities.size(); ++i) {+ if (w.entities[i] == e) return &w.movers[i];+ }+ return nullptr;+ });+ void* resources[] = { &w.time };+ aot::QuerySpec queries[] = { q };+ aot::run(&es_sys_MoveSystem, w.entities, queries, resources, arena);++ // The incomplete entity is still gone, and the complete ones still moved:+ // a filter that dropped everything would pass a "did not crash" check.+ CHECK(w.registry.tryGet<ecs::Transform>(Entity::fromRaw(w.entities[3])) == nullptr);+ const World fresh = makeWorld();+ int moved = 0;+ for (std::size_t i = 0; i < w.entities.size(); ++i) {+ const auto* got = w.registry.tryGet<ecs::Transform>(Entity::fromRaw(w.entities[i]));+ const auto* start = fresh.registry.tryGet<ecs::Transform>(Entity::fromRaw(fresh.entities[i]));+ if (got != nullptr && got->position.x != start->position.x) ++moved;+ }+ CHECK(moved > 0);+}