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): 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.ts
index 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 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
@@ -654,6 +673,7 @@ export function emitC(module: EirModule, layout: AbiLayout, systems: readonly Ei
bodies.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.hpp
index 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 here
diff --git a/src/esengine/aot/estella_abi.h b/src/esengine/aot/estella_abi.h
index 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 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
diff --git a/tests/aot/generated/move_system.c b/tests/aot/generated/move_system.c
index 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.cpp
index 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.