Skip to content

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.

feat(aot): compiled TypeScript moves a real Registry

yhh73837a67de22
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 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_device
test_clip_depth test_shadow_atlas
test_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_host
jobs:
build-emscripten:
diff --git a/compiler/src/codegen.ts b/compiler/src/codegen.ts
index 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 Ei
const 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.ts
index 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.ts
new file mode 100644
index 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.hpp
new file mode 100644
index 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::aot
diff --git a/src/esengine/aot/estella_abi.h b/src/esengine/aot/estella_abi.h
new file mode 100644
index 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.txt
index 6624c5d6b..b286df7ed 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -31,6 +31,32 @@ add_executable(test_tilemap
target_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 tests
add_executable(test_sparse_set
ecs/test_sparse_set.cpp
diff --git a/tests/aot/generated/estella_offsets.h b/tests/aot/generated/estella_offsets.h
new file mode 100644
index 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.c
new file mode 100644
index 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.h
new file mode 100644
index 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 0x52ced52de3f13ce2ULL
diff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cpp
new file mode 100644
index 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);
+}