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): a module's systems, bound once and called by index

yhh635d50942663
diff --git a/src/esengine/aot/AotDispatcher.hpp b/src/esengine/aot/AotDispatcher.hpp
new file mode 100644
index 000000000..4345d1630
--- /dev/null
+++ b/src/esengine/aot/AotDispatcher.hpp
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AotDispatcher.hpp
+ * @brief A loaded module's systems, bound once and callable by index.
+ *
+ * @details `AotModule` says what a module is and `AotHost` says how one call
+ * goes; between them sits the thing a host actually holds for a frame —
+ * the open module, the arena its calls reuse, and each system resolved
+ * against this world once instead of per call.
+ *
+ * Index, not name. The scheduler asks for the same system every frame
+ * and a name lookup there is a strcmp per system per frame on the path
+ * AOT exists to make cheap; a caller resolves the index at install.
+ *
+ * The lookups are the CALLER's, because who can name a component
+ * differs by host: engine components come from the generated table,
+ * and a project's own live in the pool the scripting language owns.
+ *
+ * Commands come back rather than being applied. A despawn invalidates
+ * the rows just handed over, so who applies them decides when — and
+ * this class does not know how to remove a component by name anyway.
+ */
+#pragma once
+
+#include <cstdint>
+#include <span>
+#include <string>
+#include <vector>
+
+#include "esengine/aot/AotHost.hpp"
+#include "esengine/aot/AotModule.hpp"
+
+namespace esengine::aot {
+
+class Dispatcher {
+public:
+ /**
+ * Open `path` and bind every system it declares.
+ *
+ * True when the module opened and agreed about the engine. A system this
+ * host cannot name every component of is left UNBOUND, not refused — the
+ * per-system fallback, one layer down; `boundAt` says which ones resolved.
+ */
+ bool install(const char* path, std::uint64_t expected,
+ const ComponentLookup& components, const ResourceLookup& resources,
+ std::string* why = nullptr) {
+ reset();
+ if (!module_.open(path, expected, why)) return false;
+ for (const EsSystemDecl& decl : module_.systems()) {
+ names_.push_back(decl.name != nullptr ? decl.name : "");
+ bound_.push_back(bind(decl, components, resources));
+ }
+ return true;
+ }
+
+ /** How many systems the module declared — bound or not. */
+ std::size_t count() const { return bound_.size(); }
+
+ /** The declared name at that index, or an empty string out of range. */
+ const char* nameAt(std::size_t i) const { return i < names_.size() ? names_[i] : ""; }
+
+ /** Whether the system at that index resolved. An unbound one runs nothing. */
+ bool boundAt(std::size_t i) const { return i < bound_.size() && bound_[i].fn != nullptr; }
+
+ /** The index of a declared name, or `npos`. Called at install, not per frame. */
+ std::size_t indexOf(const char* name) const {
+ for (std::size_t i = 0; i < names_.size(); ++i) {
+ if (names_[i] != nullptr && name != nullptr && std::strcmp(names_[i], name) == 0) return i;
+ }
+ return npos;
+ }
+
+ /**
+ * Run one system over these candidates, and hand back what it wrote.
+ *
+ * Resources are resolved per call because the contract only promises an
+ * address for the length of one; the components were resolved at install,
+ * which is the whole point of binding.
+ */
+ std::span<const EsCmd> run(std::size_t i, std::span<const std::uint32_t> candidates,
+ const ResourceLookup& resources) {
+ if (i >= bound_.size()) return {};
+ return runBound(bound_[i], candidates, resources, arena_);
+ }
+
+ /** Close the module and forget the bindings — they point into it. */
+ void reset() {
+ bound_.clear();
+ names_.clear();
+ module_.close();
+ }
+
+ static constexpr std::size_t npos = static_cast<std::size_t>(-1);
+
+private:
+ Module module_;
+ std::vector<const char*> names_;
+ std::vector<BoundSystem> bound_;
+ CallArena arena_;
+};
+
+} // namespace esengine::aot
diff --git a/src/esengine/aot/AotModule.hpp b/src/esengine/aot/AotModule.hpp
index c13d2343d..f0a60b4a8 100644
--- a/src/esengine/aot/AotModule.hpp
+++ b/src/esengine/aot/AotModule.hpp
@@ -27,22 +27,11 @@
#include <string>
#include <utility>
-#include "esengine/aot/estella_abi.h"
+#include "esengine/aot/AotHost.hpp" // abiHash — the width half of the handshake
#include "esengine/core/DynamicLibrary.hpp"
namespace esengine::aot {
-/**
- * What a host expects a module to say, from the contract IT was built against.
- *
- * The width is this side's `sizeof(es_addr_t)`, mixed in exactly as the module
- * mixes its own — which is what stops a 32-bit artifact from loading here and
- * reading every row at half a pointer.
- */
-constexpr std::uint64_t expectedAbiHash(std::uint64_t contractDigest) {
- return contractDigest ^ (0x9e3779b97f4a7c15ULL * static_cast<std::uint64_t>(sizeof(es_addr_t)));
-}
-
class Module {
public:
Module() = default;
@@ -60,7 +49,7 @@ public:
}
/**
- * Open a module and check it agrees with `expected` (see expectedAbiHash).
+ * Open a module and check it says what `expected` says (see `abiHash`).
*
* `why` is filled on every false: the ways this fails want different fixes —
* the file is absent, it carries no declaration table, or it was built for
diff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cpp
index 157fcc25a..e9e773e43 100644
--- a/tests/aot/test_aot_host.cpp
+++ b/tests/aot/test_aot_host.cpp
@@ -34,6 +34,7 @@
#include "esengine/aot/AotHost.hpp"
#include "esengine/aot/AotComponents.generated.hpp"
#include "esengine/aot/AotModule.hpp"
+#include "esengine/aot/AotDispatcher.hpp"
#include "esengine/ecs/Registry.hpp"
#include "esengine/ecs/components/Transform.hpp"
@@ -349,7 +350,7 @@ TEST_CASE("a compiled system runs on the generated resolvers, exactly as on hand
TEST_CASE("the same system, loaded out of a module rather than linked in") {
aot::Module mod;
std::string why;
- const std::uint64_t expected = aot::expectedAbiHash(ES_EXPECTED_CONTRACT_HASH);
+ const std::uint64_t expected = aot::abiHash(ES_EXPECTED_CONTRACT_HASH);
REQUIRE_MESSAGE(mod.open(ES_AOT_MODULE_PATH, expected, &why), why);
// The declaration table is IN the artifact, so a loading host needs no
@@ -386,7 +387,7 @@ TEST_CASE("a module built for another engine is refused, and says which half mov
std::string why;
// One bit of the contract, which is what a rebuilt engine looks like from
// here. It must not open at all: a wrong offset is a read of another field.
- CHECK(mod.open(ES_AOT_MODULE_PATH, aot::expectedAbiHash(ES_EXPECTED_CONTRACT_HASH ^ 1ULL), &why) == false);
+ CHECK(mod.open(ES_AOT_MODULE_PATH, aot::abiHash(ES_EXPECTED_CONTRACT_HASH ^ 1ULL), &why) == false);
CHECK(mod.isOpen() == false);
CHECK(why.find("engine") != std::string::npos);
@@ -394,3 +395,74 @@ TEST_CASE("a module built for another engine is refused, and says which half mov
CHECK(why.find("load") != std::string::npos);
}
#endif
+
+#ifdef ES_AOT_MODULE_PATH
+TEST_CASE("the dispatcher binds once and runs by index") {
+ World w = makeWorld();
+ World linked = makeWorld();
+ aot::Dispatcher dispatcher;
+ std::string why;
+
+ REQUIRE_MESSAGE(dispatcher.install(ES_AOT_MODULE_PATH, aot::abiHash(ES_EXPECTED_CONTRACT_HASH),
+ componentsOf(w), resourcesOf(w), &why), why);
+ REQUIRE(dispatcher.count() == 1u);
+
+ // The index is resolved once, here, because the scheduler asks for the same
+ // system every frame and a strcmp there is per system per frame.
+ const std::size_t at = dispatcher.indexOf("MoveSystem");
+ REQUIRE(at != aot::Dispatcher::npos);
+ CHECK(dispatcher.boundAt(at));
+ CHECK(std::strcmp(dispatcher.nameAt(at), "MoveSystem") == 0);
+ CHECK(dispatcher.indexOf("NotASystem") == aot::Dispatcher::npos);
+
+ // Three frames, so a binding that only survives the first one shows up.
+ aot::CallArena arena;
+ for (int frame = 0; frame < 3; ++frame) {
+ dispatcher.run(at, w.entities, resourcesOf(w));
+ aot::runBound(aot::bind(*declOf("MoveSystem"), componentsOf(linked), resourcesOf(linked)),
+ linked.entities, resourcesOf(linked), arena);
+ }
+ for (std::size_t i = 0; i < w.entities.size(); ++i) {
+ const auto* want = linked.registry.tryGet<ecs::Transform>(Entity::fromRaw(linked.entities[i]));
+ const auto* got = w.registry.tryGet<ecs::Transform>(Entity::fromRaw(w.entities[i]));
+ REQUIRE((want != nullptr) == (got != nullptr));
+ if (want == nullptr) continue;
+ CHECK(want->position.x == got->position.x);
+ CHECK(want->position.y == got->position.y);
+ }
+}
+
+TEST_CASE("a system this host cannot name is left unbound, not refused") {
+ World w = makeWorld();
+ aot::Dispatcher dispatcher;
+ std::string why;
+
+ // A host with no `Mover` — the shape of a project whose script pool has not
+ // been handed over yet. The module still installs: the fallback is PER
+ // SYSTEM, so one it cannot run must not cost the others their module.
+ const aot::ComponentLookup partial = [&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));
+ };
+ }
+ return nullptr;
+ };
+
+ REQUIRE(dispatcher.install(ES_AOT_MODULE_PATH, aot::abiHash(ES_EXPECTED_CONTRACT_HASH),
+ partial, resourcesOf(w), &why));
+ const std::size_t at = dispatcher.indexOf("MoveSystem");
+ REQUIRE(at != aot::Dispatcher::npos);
+ CHECK(dispatcher.boundAt(at) == false);
+
+ // And running it moves nothing, rather than reading a row it never packed.
+ const World fresh = makeWorld();
+ CHECK(dispatcher.run(at, w.entities, resourcesOf(w)).empty());
+ 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 || start == nullptr) continue;
+ CHECK(got->position.x == start->position.x);
+ }
+}
+#endif