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): a module's systems, bound once and called by index
yhh635d50942663
diff --git a/src/esengine/aot/AotDispatcher.hpp b/src/esengine/aot/AotDispatcher.hppnew file mode 100644index 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::aotdiff --git a/src/esengine/aot/AotModule.hpp b/src/esengine/aot/AotModule.hppindex 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 fordiff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cppindex 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 handTEST_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 movstd::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 movCHECK(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