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 records a call wrote, applied after it

yhh0384d1bc834b
diff --git a/src/esengine/aot/AotCommands.hpp b/src/esengine/aot/AotCommands.hpp
new file mode 100644
index 000000000..3cdfb9902
--- /dev/null
+++ b/src/esengine/aot/AotCommands.hpp
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AotCommands.hpp
+ * @brief What a host does with the records a compiled system wrote.
+ *
+ * @details A compiled system calls the engine zero times, so it cannot despawn
+ * an entity — it appends a record and the host acts on it after the
+ * call, which is also the only moment it safely can: a despawn
+ * invalidates the rows the call was reading.
+ *
+ * Separate from `AotHost.hpp` because acting means knowing the
+ * Registry, and that header stays free of the engine so a harness can
+ * use it without linking one.
+ *
+ * Counts what it could not apply rather than ignoring it. The record
+ * set grows, and a host that quietly dropped a kind it had not learned
+ * would look exactly like one where the system did nothing.
+ */
+#pragma once
+
+#include <cstdint>
+#include <span>
+
+#include "esengine/aot/estella_abi.h"
+#include "esengine/ecs/Entity.hpp"
+#include "esengine/ecs/Registry.hpp"
+
+namespace esengine::aot {
+
+/**
+ * Apply a call's records to this registry; returns how many it did not know.
+ *
+ * Despawn is the whole v1 set, and the interpreted side applies exactly that —
+ * so a nonzero result is this host being older than the module it loaded, not
+ * a malformed record.
+ */
+inline std::uint32_t applyCommands(ecs::Registry& registry, std::span<const EsCmd> cmds) {
+ std::uint32_t unknown = 0;
+ for (const EsCmd& cmd : cmds) {
+ switch (cmd.kind) {
+ case ES_CMD_DESPAWN:
+ // `a` is the raw entity, as every address-free record carries it.
+ registry.destroy(Entity::fromRaw(cmd.a));
+ break;
+ default:
+ ++unknown;
+ break;
+ }
+ }
+ return unknown;
+}
+
+} // namespace esengine::aot
diff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cpp
index 188b25e0a..333da6bd4 100644
--- a/tests/aot/test_aot_host.cpp
+++ b/tests/aot/test_aot_host.cpp
@@ -35,6 +35,7 @@
#include "esengine/aot/AotComponents.generated.hpp"
#include "esengine/aot/AotModule.hpp"
#include "esengine/aot/AotDispatcher.hpp"
+#include "esengine/aot/AotCommands.hpp"
#include "esengine/aot/EngineDigest.generated.h"
#include "esengine/ecs/Registry.hpp"
#include "esengine/ecs/components/Transform.hpp"
@@ -537,3 +538,22 @@ TEST_CASE("a pool that moved its rows takes the twin with it") {
}
}
#endif
+
+TEST_CASE("the records a call wrote are applied after it, and unknown ones are counted") {
+ World w = makeWorld();
+ const std::uint32_t victim = w.entities[2];
+ const std::uint32_t bystander = w.entities[3];
+ REQUIRE(w.registry.valid(Entity::fromRaw(victim)));
+
+ const EsCmd cmds[] = {
+ { ES_CMD_DESPAWN, victim, 0u, 0u },
+ // A kind this host has not learned. Counted, because a host quietly
+ // dropping one looks exactly like a system that did nothing.
+ { 0xFFFFFFFFu, bystander, 0u, 0u },
+ };
+ const std::uint32_t unknown = aot::applyCommands(w.registry, cmds);
+
+ CHECK(unknown == 1u);
+ CHECK(w.registry.valid(Entity::fromRaw(victim)) == false);
+ CHECK(w.registry.valid(Entity::fromRaw(bystander)));
+}