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): the artifact says what it needs, so no host writes that list twice
yhh5ef31ea7a898
diff --git a/compiler/src/codegen.ts b/compiler/src/codegen.tsindex 2b248ff83..46e995fdb 100644--- a/compiler/src/codegen.ts+++ b/compiler/src/codegen.ts@@ -82,6 +82,7 @@ export const RUNTIME_H = `/* GENERATED by @estella/compiler — do not edit. */#ifndef ESTELLA_ABI_H#define ESTELLA_ABI_H+#include <stddef.h>#include <stdint.h>#include <string.h>#include <math.h>@@ -138,6 +139,24 @@ typedef struct EsSysCtx {es_addr_t events;} EsSysCtx;+/* §6: what a host needs in order to CALL a system without glue written by hand.+ The compiler knows a system's queries and resources -- that is what _params+ is -- so it says so here rather than leaving each host to be told twice. */+typedef struct EsQueryDecl {+ const char *const *comps; /* component names, in the order the query names them */+ const unsigned char *mut; /* 1 where the system may write that component */+ uint32_t count;+} EsQueryDecl;++typedef struct EsSystemDecl {+ const char *name;+ void (*fn)(es_addr_t);+ const EsQueryDecl *queries;+ const char *const *resources;+ uint32_t queryCount;+ uint32_t resourceCount;+} EsSystemDecl;+/* §6.1 asks that the C and TS sides of these structs have ONE author, and that ahand-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@@ -654,6 +673,7 @@ export function emitC(module: EirModule, layout: AbiLayout, systems: readonly Eibodies.push(e.text);});+ const manifest = emitManifest(systems, plans);const hash = abiHash(layout, plans);const macros = [...offsets].sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `#define ${k} ${v}u`);const offsetsHeader = [@@ -685,6 +705,7 @@ export function emitC(module: EirModule, layout: AbiLayout, systems: readonly Ei` ES_ABI_CONTRACT_HASH ^ (${ADDR_MIX}ULL * (uint64_t)sizeof(es_addr_t));`,'',...bodies,+ ...manifest,].join('\n');return {@@ -696,6 +717,49 @@ export function emitC(module: EirModule, layout: AbiLayout, systems: readonly Ei};}+/**+ * The table a host walks to call these systems: each one's symbol, and the+ * component and resource NAMES its ctx tables have to be filled from. Without it+ * every host writes the same list a second time, and the second list is the one+ * that goes stale.+ */+function emitManifest(systems: readonly EirSystem[], plans: readonly SysPlan[]): string[] {+ const out: string[] = ['/* The systems in this file, and what each one needs filled in. */'];+ const rows: string[] = [];+ systems.forEach((sys, i) => {+ const plan = plans[i]!;+ const tag = cSymbol(sys.name);+ plan.queries.forEach((args, k) => {+ out.push(`static const char *const ${tag}_q${k}_comps[] = { `+ + `${args.map((a) => JSON.stringify(a.comp)).join(', ')} };`);+ out.push(`static const unsigned char ${tag}_q${k}_mut[] = { `+ + `${args.map((a) => (a.mut ? '1u' : '0u')).join(', ')} };`);+ });+ if (plan.queries.length > 0) {+ const entries = plan.queries.map((args, k) =>+ `{ ${tag}_q${k}_comps, ${tag}_q${k}_mut, ${args.length}u }`);+ out.push(`static const EsQueryDecl ${tag}_queries[] = { ${entries.join(', ')} };`);+ }+ if (plan.resources.length > 0) {+ out.push(`static const char *const ${tag}_resources[] = { `+ + `${plan.resources.map((r) => JSON.stringify(r)).join(', ')} };`);+ }+ // C has no zero-length array, so an empty table is a null pointer and a+ // count of zero — which is also what a host would check anyway.+ rows.push(` { ${JSON.stringify(sys.name)}, ${tag}, `+ + `${plan.queries.length > 0 ? `${tag}_queries` : 'NULL'}, `+ + `${plan.resources.length > 0 ? `${tag}_resources` : 'NULL'}, `+ + `${plan.queries.length}u, ${plan.resources.length}u },`);+ });+ out.push('');+ out.push('const EsSystemDecl es_systems[] = {');+ out.push(...rows);+ out.push('};');+ out.push(`const uint32_t es_system_count = ${systems.length}u;`);+ out.push('');+ return out;+}+/** Module functions still called after the inliner ran, in declaration order. */function calledFns(module: EirModule, systems: readonly EirSystem[]): string[] {const want = new Set<string>();diff --git a/src/esengine/aot/AotHost.hpp b/src/esengine/aot/AotHost.hppindex f8762942b..13339e293 100644--- a/src/esengine/aot/AotHost.hpp+++ b/src/esengine/aot/AotHost.hpp@@ -23,6 +23,7 @@#include <cstdint>#include <functional>#include <span>+#include <utility>#include <vector>#include "estella_abi.h"@@ -123,6 +124,63 @@ inline std::span<const EsCmd> run(SystemFn fn,return std::span<const EsCmd>(arena.cmds_.data(), arena.count_);}+/**+ * How a host answers the two questions a declaration asks: where one component+ * is for an entity, and where one resource is. Both by NAME, because names are+ * what the artifact carries — it cannot know this host's type ids.+ */+using ComponentLookup = std::function<ComponentAt(const char*)>;+using ResourceLookup = std::function<void*(const char*)>;++/**+ * A declared system with its resolvers found once. Resources are looked up per+ * call rather than kept, because a host is free to move one between frames and+ * the contract only promises the address for the length of a call.+ */+struct BoundSystem {+ SystemFn fn = nullptr;+ std::vector<QuerySpec> queries;+ std::vector<const char*> resourceNames;+};++/**+ * Resolve `decl` against this host. A component or resource the host cannot+ * name leaves `fn` null: the system is simply not run, which is §3.2's fallback+ * arriving one layer down rather than a crash at the first row.+ */+inline BoundSystem bind(const EsSystemDecl& decl,+ const ComponentLookup& components,+ const ResourceLookup& resources) {+ BoundSystem out;+ out.queries.resize(decl.queryCount);+ for (std::uint32_t q = 0; q < decl.queryCount; ++q) {+ const EsQueryDecl& qd = decl.queries[q];+ for (std::uint32_t c = 0; c < qd.count; ++c) {+ ComponentAt at = components(qd.comps[c]);+ if (!at) return {};+ out.queries[q].comps.push_back(std::move(at));+ }+ }+ for (std::uint32_t r = 0; r < decl.resourceCount; ++r) {+ if (resources(decl.resources[r]) == nullptr) return {};+ out.resourceNames.push_back(decl.resources[r]);+ }+ out.fn = decl.fn;+ return out;+}++/** Run a bound system, resolving its resources for this call. */+inline std::span<const EsCmd> runBound(const BoundSystem& bound,+ std::span<const std::uint32_t> candidates,+ const ResourceLookup& resources,+ CallArena& arena) {+ if (bound.fn == nullptr) return {};+ std::vector<void*> addresses;+ addresses.reserve(bound.resourceNames.size());+ for (const char* name : bound.resourceNames) addresses.push_back(resources(name));+ return run(bound.fn, candidates, bound.queries, addresses, arena);+}+/*** 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 herediff --git a/src/esengine/aot/estella_abi.h b/src/esengine/aot/estella_abi.hindex 96922d88e..ca92c3de5 100644--- a/src/esengine/aot/estella_abi.h+++ b/src/esengine/aot/estella_abi.h@@ -3,6 +3,7 @@#ifndef ESTELLA_ABI_H#define ESTELLA_ABI_H+#include <stddef.h>#include <stdint.h>#include <string.h>#include <math.h>@@ -59,6 +60,24 @@ typedef struct EsSysCtx {es_addr_t events;} EsSysCtx;+/* §6: what a host needs in order to CALL a system without glue written by hand.+ The compiler knows a system's queries and resources -- that is what _params+ is -- so it says so here rather than leaving each host to be told twice. */+typedef struct EsQueryDecl {+ const char *const *comps; /* component names, in the order the query names them */+ const unsigned char *mut; /* 1 where the system may write that component */+ uint32_t count;+} EsQueryDecl;++typedef struct EsSystemDecl {+ const char *name;+ void (*fn)(es_addr_t);+ const EsQueryDecl *queries;+ const char *const *resources;+ uint32_t queryCount;+ uint32_t resourceCount;+} EsSystemDecl;+/* §6.1 asks that the C and TS sides of these structs have ONE author, and that ahand-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 saysdiff --git a/tests/aot/generated/move_system.c b/tests/aot/generated/move_system.cindex 4f9480443..28a954100 100644--- a/tests/aot/generated/move_system.c+++ b/tests/aot/generated/move_system.c@@ -29,3 +29,14 @@ void es_sys_MoveSystem(es_addr_t es_ctx) {}}}++/* The systems in this file, and what each one needs filled in. */+static const char *const es_sys_MoveSystem_q0_comps[] = { "Transform", "Mover" };+static const unsigned char es_sys_MoveSystem_q0_mut[] = { 1u, 0u };+static const EsQueryDecl es_sys_MoveSystem_queries[] = { { es_sys_MoveSystem_q0_comps, es_sys_MoveSystem_q0_mut, 2u } };+static const char *const es_sys_MoveSystem_resources[] = { "Time" };++const EsSystemDecl es_systems[] = {+ { "MoveSystem", es_sys_MoveSystem, es_sys_MoveSystem_queries, es_sys_MoveSystem_resources, 1u, 1u },+};+const uint32_t es_system_count = 1u;diff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cppindex 0d267b41b..7a19eba36 100644--- a/tests/aot/test_aot_host.cpp+++ b/tests/aot/test_aot_host.cpp@@ -27,6 +27,7 @@#include <cstddef>#include <cstdint>+#include <cstring>#include <vector>#include "esengine/aot/AotHost.hpp"@@ -39,6 +40,9 @@ extern "C" {/** 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;+/** The manifest: what the artifact says its systems need filled in. */+extern const EsSystemDecl es_systems[];+extern const std::uint32_t es_system_count;}using namespace esengine;@@ -111,21 +115,47 @@ void moveByHand(World& w) {}}-/** 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];+/**+ * What this host can name. A real one answers from the generated per-component+ * bindings and from ScriptStorage's pools; here `Mover` stands in for a pool,+ * which is the same thing a slot address later becomes.+ */+aot::ComponentLookup componentsOf(World& w) {+ return [&w](const char* name) -> aot::ComponentAt {+ if (std::strcmp(name, "Transform") == 0) {+ return [&w](std::uint32_t e) -> void* {+ return w.registry.tryGet<ecs::Transform>(Entity::fromRaw(e));+ };+ }+ if (std::strcmp(name, "Mover") == 0) {+ return [&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;+ };}return nullptr;- });- void* resources[] = { &w.time };- aot::QuerySpec queries[] = { q };- const auto cmds = aot::run(&es_sys_MoveSystem, w.entities, queries, resources, arena);+ };+}++aot::ResourceLookup resourcesOf(World& w) {+ return [&w](const char* name) -> void* {+ return std::strcmp(name, "Time") == 0 ? &w.time : nullptr;+ };+}++/** The declaration the artifact carries for `name`, or null. */+const EsSystemDecl* declOf(const char* name) {+ for (std::uint32_t i = 0; i < es_system_count; ++i) {+ if (std::strcmp(es_systems[i].name, name) == 0) return &es_systems[i];+ }+ return nullptr;+}++/** One frame through the contract, driven entirely by the manifest. */+void moveByCompiledCode(World& w, const aot::BoundSystem& bound, aot::CallArena& arena) {+ const auto cmds = aot::runBound(bound, w.entities, resourcesOf(w), arena);CHECK(cmds.empty()); // MoveSystem writes no commands}@@ -144,14 +174,49 @@ TEST_CASE("the host and the artifact agree on the handshake") {CHECK(es_abi_hash == aot::abiHash(ES_EXPECTED_CONTRACT_HASH));}+TEST_CASE("the artifact says what it needs, and nobody writes that list twice") {+ const EsSystemDecl* decl = declOf("MoveSystem");+ REQUIRE(decl != nullptr);+ REQUIRE(decl->queryCount == 1u);+ REQUIRE(decl->queries[0].count == 2u);+ // Order is the contract: slot 0 of a row is Transform because the query+ // named it first, and swapping these two swaps every load in the system.+ CHECK(std::strcmp(decl->queries[0].comps[0], "Transform") == 0);+ CHECK(std::strcmp(decl->queries[0].comps[1], "Mover") == 0);+ CHECK(decl->queries[0].mut[0] == 1u); // Mut(Transform)+ CHECK(decl->queries[0].mut[1] == 0u);+ REQUIRE(decl->resourceCount == 1u);+ CHECK(std::strcmp(decl->resources[0], "Time") == 0);+ CHECK(decl->fn == &es_sys_MoveSystem);+}++TEST_CASE("a system naming something this host cannot is simply not bound") {+ World w = makeWorld();+ const EsSystemDecl* decl = declOf("MoveSystem");+ REQUIRE(decl != nullptr);+ // §3.2's fallback, one layer down: a host missing a component does not get+ // a system that reads null, it gets no system.+ const aot::BoundSystem none = aot::bind(+ *decl, [](const char*) { return aot::ComponentAt{}; }, resourcesOf(w));+ CHECK(none.fn == nullptr);++ aot::CallArena arena;+ CHECK(aot::runBound(none, w.entities, resourcesOf(w), arena).empty());+}+TEST_CASE("a compiled system moves a real Registry exactly as C++ does") {World byHand = makeWorld();World byCode = makeWorld();aot::CallArena arena;+ const EsSystemDecl* decl = declOf("MoveSystem");+ REQUIRE(decl != nullptr);+ const aot::BoundSystem bound = aot::bind(*decl, componentsOf(byCode), resourcesOf(byCode));+ REQUIRE(bound.fn != nullptr);+for (int frame = 0; frame < 30; ++frame) {moveByHand(byHand);- moveByCompiledCode(byCode, arena);+ moveByCompiledCode(byCode, bound, 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]));@@ -178,19 +243,8 @@ TEST_CASE("a row the query cannot complete is not a row") {// 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);+ const aot::BoundSystem bound = aot::bind(*declOf("MoveSystem"), componentsOf(w), resourcesOf(w));+ aot::runBound(bound, w.entities, resourcesOf(w), 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.