From 2cfaa37344a6b48c36754ba556f6c7455d98d5f0 Mon Sep 17 00:00:00 2001
From: Resurrected Trader <admin@resurrected.trade>
Date: Thu, 8 Oct 2026 09:14:06 +0100
Subject: [PATCH 1/3] runtime: add a per-frame "render" script event as a
 frame-counter signal

addEventListener("render", (frame) => ...) runs at most once per rendered
frame, in and out of game, so scripts can move or restyle drawables every
frame. GameLoop::OnDraw only increments a global frame counter
(events::RenderFrames) before Drawable::DrawAll; it queues nothing and never
waits on a script. Each pass of a script's event loop (Script::ExecuteEvents,
inside delay()) fires its render listeners once when the counter moved since
it last did, so a slow script sees a bigger jump in frame rather than a
backlog, and no script listening costs nothing beyond the increment.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/game_thread_safety.md                    | 16 +++++++
 src/contract/game/GameCallbacks.h             |  5 +-
 .../components/events/EventDispatch.cpp       |  5 ++
 src/runtime/components/events/EventDispatch.h |  3 ++
 src/runtime/components/events/Events.h        | 23 +++++++++
 src/runtime/components/events/RenderFrames.h  | 33 +++++++++++++
 src/runtime/components/gameloop/GameLoop.cpp  |  1 +
 src/runtime/components/gameloop/GameLoop.h    |  4 +-
 src/runtime/components/script/Script.cpp      | 14 +++++-
 src/runtime/components/script/Script.h        |  6 +++
 src/runtime/runtime.vcxproj                   |  1 +
 tests/runtime/events/RenderFramesTest.cpp     | 48 +++++++++++++++++++
 tests/runtime/fakes/GameLoopCollaborators.cpp |  5 ++
 tests/runtime/fakes/GameLoopCollaborators.h   |  3 ++
 .../shims/components/events/EventDispatch.h   |  3 +-
 tests/runtime/gameloop/GameLoopTest.cpp       | 17 +++++++
 tests/runtime/js_tests.vcxproj                |  2 +
 17 files changed, 183 insertions(+), 6 deletions(-)
 create mode 100644 src/runtime/components/events/RenderFrames.h
 create mode 100644 tests/runtime/events/RenderFramesTest.cpp

diff --git a/docs/game_thread_safety.md b/docs/game_thread_safety.md
index c1d3871..4e38552 100644
--- a/docs/game_thread_safety.md
+++ b/docs/game_thread_safety.md
@@ -180,6 +180,22 @@ game::GameThread::Execute([&] {
 
 `Execute()` releases the script's `GameReadLock` so the game thread can acquire `GameWriteLock` to drain the task queue.
 
+## Per-frame events (`render`)
+
+The `render` event is a signal, not a queued event. `GameLoop::OnDraw` (the backend's `onDraw` callback, once
+per rendered frame, in and out of game) only increments a global frame counter (`events::RenderFrames`,
+`components/events/RenderFrames.h`) before `Drawable::DrawAll`; it queues nothing and never waits on a script,
+so a frame costs one atomic increment whether or not any script listens. Each pass of a script's event loop
+(`Script::ExecuteEvents`, i.e. inside `delay()`) compares the counter with the frame the script last fired
+`render` for and, if it moved, fires the `render` listeners once with the latest frame number. No wake-up is
+needed: the loop already polls every `IdleSleepIntervalMs`, the same latency as any cross-thread posted event. A
+slow script just sees a bigger jump in `frame`; there is no backlog to drain.
+
+Handlers run on the script's thread, so a frame is usually already being drawn by then: a drawable change made
+in a `render` handler typically shows from the next frame. Drawable fields are atomics, so the handler needs no
+game lock to change them; reading game state from it takes the usual `GameReadLock`, which waits for the game
+thread's sleep window.
+
 ## Lock Releasers
 
 ### GameWriteLockReleaser
diff --git a/src/contract/game/GameCallbacks.h b/src/contract/game/GameCallbacks.h
index 306ac52..e7973cb 100644
--- a/src/contract/game/GameCallbacks.h
+++ b/src/contract/game/GameCallbacks.h
@@ -105,8 +105,9 @@ struct GameCallbacks {
     //     the game thread (pass through to real Sleep).
     void (*onSleep)(std::chrono::milliseconds duration) = nullptr;
 
-    // Called from the game's render function.
-    // Framework flushes drawables so overlays composite with the current frame.
+    // Called from the game's render function, once per rendered frame (in and out of game).
+    // Framework counts the frame for the script "render" event, then flushes drawables so
+    // overlays composite with the current frame.
     void (*onDraw)() = nullptr;
 };
 
diff --git a/src/runtime/components/events/EventDispatch.cpp b/src/runtime/components/events/EventDispatch.cpp
index 9d7b1a1..2862811 100644
--- a/src/runtime/components/events/EventDispatch.cpp
+++ b/src/runtime/components/events/EventDispatch.cpp
@@ -8,6 +8,7 @@
 #include <utility>
 
 #include "Events.h"
+#include "RenderFrames.h"
 #include "components/script/Commands.h"
 #include "components/script/ScriptEngine.h"
 #include "config/AppConfig.h"
@@ -128,6 +129,10 @@ void CopyDataEventDispatch(game::IpcMode mode, const std::string& payload) {
     FireIfListening<CopyDataEvent>(mode, payload);
 }
 
+void RenderEventDispatch() {
+    RenderFrames::Count();
+}
+
 void ScriptBroadcastEventDispatch(const v8::FunctionCallbackInfo<v8::Value>& args) {
     // Not probed: constructing this serialises the arguments, which can run script code (getters),
     // so skipping it when nobody listens would be observable.
diff --git a/src/runtime/components/events/EventDispatch.h b/src/runtime/components/events/EventDispatch.h
index 5fbcbea..5e29667 100644
--- a/src/runtime/components/events/EventDispatch.h
+++ b/src/runtime/components/events/EventDispatch.h
@@ -36,6 +36,9 @@ void ItemActionEventDispatch(uint32_t unitId, uint32_t action, const std::string
 void GameActionEventDispatch(int32_t mode, uint32_t param1, uint32_t param2, const std::string& name1,
                              const std::string& name2);
 void CopyDataEventDispatch(game::IpcMode mode, const std::string& payload);
+// Once per rendered frame, on the game thread, before the drawables are drawn. Only counts the frame:
+// each script fires its "render" listeners from its own event loop (Script::ExecuteEvents).
+void RenderEventDispatch();
 void ScriptBroadcastEventDispatch(const v8::FunctionCallbackInfo<v8::Value>& args);
 
 // Blockable event dispatchers (return true if event was blocked)
diff --git a/src/runtime/components/events/Events.h b/src/runtime/components/events/Events.h
index 0edc755..d34d24f 100644
--- a/src/runtime/components/events/Events.h
+++ b/src/runtime/components/events/Events.h
@@ -520,6 +520,29 @@ class BroadcastEvent : public BaseEvent {
     std::vector<std::vector<uint8_t>> values_;
 };
 
+// ============================================================================
+// Render Event
+// ============================================================================
+
+/// @event A frame was rendered (in game and out of game). Fires at most once per frame, so handlers can move or
+/// restyle drawables every frame. Handlers run on the script's own thread whenever its event loop runs (inside
+/// delay()), so a change usually shows from the next frame. A script that falls behind fires once for all the frames
+/// it missed rather than once per frame.
+/// @param frame {number} - the number of the most recently rendered frame, counted from load; compare with the previous
+/// call's to see how many frames were skipped
+class RenderEvent : public BaseEvent {
+   protected:
+    std::vector<v8::Local<v8::Value>> MakeArgs(v8::Isolate* isolate) const override {
+        return {api::convert::ToJS(isolate, frame)};
+    }
+
+   public:
+    explicit RenderEvent(uint32_t frame) : frame(frame) {}
+    const uint32_t frame;
+    static constexpr std::string_view EVENT_NAME = "render";
+    [[nodiscard]] std::string_view Name() const override { return EVENT_NAME; }
+};
+
 // ============================================================================
 // Screen Hook Events
 // ============================================================================
diff --git a/src/runtime/components/events/RenderFrames.h b/src/runtime/components/events/RenderFrames.h
new file mode 100644
index 0000000..e4cf0ea
--- /dev/null
+++ b/src/runtime/components/events/RenderFrames.h
@@ -0,0 +1,33 @@
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+
+namespace d2bs::runtime::events {
+
+// The per-frame "render" event is a signal, not a queued event: the game thread only counts rendered
+// frames, and each script's event loop fires its render listeners when the count has moved since it
+// last did. Nothing is queued per frame, so a script that falls behind just sees a bigger jump. Kept
+// free of V8 so the coalescing can be tested on its own.
+class RenderFrames {
+    inline static std::atomic<uint32_t> count_ = 0;
+
+   public:
+    // Game thread, once per rendered frame.
+    static void Count() { count_.fetch_add(1, std::memory_order_relaxed); }
+
+    // Any thread. The number of the most recently rendered frame (the first is 1).
+    static uint32_t Latest() { return count_.load(std::memory_order_relaxed); }
+
+    // True if a frame was rendered since `seen`, which then moves to the latest frame.
+    static bool TakeNew(uint32_t& seen) {
+        const uint32_t latest = Latest();
+        if (latest == seen) {
+            return false;
+        }
+        seen = latest;
+        return true;
+    }
+};
+
+}  // namespace d2bs::runtime::events
diff --git a/src/runtime/components/gameloop/GameLoop.cpp b/src/runtime/components/gameloop/GameLoop.cpp
index 97920d3..90f4590 100644
--- a/src/runtime/components/gameloop/GameLoop.cpp
+++ b/src/runtime/components/gameloop/GameLoop.cpp
@@ -209,6 +209,7 @@ void GameLoop::OnSleep(std::chrono::milliseconds duration) {
 void GameLoop::OnDraw() const {
     // Fires from the render function, before the next OnSleep has taken a new
     // snapshot - previous_.state is the most recently observed game state.
+    events::RenderEventDispatch();
     drawing::Drawable::DrawAll(previous_.state);
     // Always-on "d2bsng <version>" corner banner (carries the update-available
     // marker). Drawn after script drawables so it stays on top.
diff --git a/src/runtime/components/gameloop/GameLoop.h b/src/runtime/components/gameloop/GameLoop.h
index ef439ba..5a814cf 100644
--- a/src/runtime/components/gameloop/GameLoop.h
+++ b/src/runtime/components/gameloop/GameLoop.h
@@ -75,8 +75,8 @@ class GameLoop {
     // left held on exit so the next frame body starts under the write lock.
     void OnSleep(std::chrono::milliseconds duration);
 
-    // Called from the game's render function. Flushes drawables for the most
-    // recently observed game state.
+    // Called from the game's render function. Counts the frame for the script
+    // "render" event, then flushes drawables for the most recently observed game state.
     void OnDraw() const;
 
     // Attributes the caller's scope to `phase` on the game thread's timeline. Inert on other
diff --git a/src/runtime/components/script/Script.cpp b/src/runtime/components/script/Script.cpp
index be96430..c0420d5 100644
--- a/src/runtime/components/script/Script.cpp
+++ b/src/runtime/components/script/Script.cpp
@@ -24,6 +24,7 @@
 #include "components/events/DelayedEvent.h"
 #include "components/events/EventDispatch.h"
 #include "components/events/Events.h"
+#include "components/events/RenderFrames.h"
 #include "components/inspector/ScriptInspector.h"
 #include "components/script/CompileSource.h"
 #include "components/script/NativeCallHook.h"
@@ -73,7 +74,8 @@ Script::Script(std::filesystem::path path, ScriptMode mode, std::vector<std::vec
       idle_(IDLE_TIMELINE),
       mode_(mode),
       args_(std::move(args)),
-      logger_(utils::GetLogger(path_.filename().string())) {}
+      logger_(utils::GetLogger(path_.filename().string())),
+      lastRenderFrame_(events::RenderFrames::Latest()) {}
 
 std::shared_ptr<spdlog::logger> GetLogger(v8::Isolate* isolate) {
     if (auto* script = ScriptEngine::Instance().GetScript(isolate)) {
@@ -887,6 +889,8 @@ void Script::ExecuteEvents(std::chrono::milliseconds duration) {
             inspector_->DrainIncoming();
         }
 
+        FireRenderIfNewFrame();
+
         // steady_clock::now() is QueryPerformanceCounter on MSVC, so each read
         // routes through the speedhack hook: take one reading per pass and reuse it
         // for the heap-stat throttle, the deadline check, and the wait.
@@ -918,6 +922,14 @@ void Script::ExecuteEvents(std::chrono::milliseconds duration) {
     }
 }
 
+void Script::FireRenderIfNewFrame() {
+    // The frame is consumed even with no listener, so adding one later waits for the next frame.
+    if (!events::RenderFrames::TakeNew(lastRenderFrame_) || !IsEventRegistered(events::RenderEvent::EVENT_NAME)) {
+        return;
+    }
+    ExecuteEvent(std::make_shared<events::RenderEvent>(lastRenderFrame_));
+}
+
 bool Script::ExecuteEvent(const std::shared_ptr<events::BaseEvent>& event) {
     auto* iso = isolate_.load().get();
     if (!iso)
diff --git a/src/runtime/components/script/Script.h b/src/runtime/components/script/Script.h
index ba47c1b..3079123 100644
--- a/src/runtime/components/script/Script.h
+++ b/src/runtime/components/script/Script.h
@@ -229,6 +229,10 @@ class Script : public std::enable_shared_from_this<Script> {
     // Drops every handler and its listener counts. Caller holds eventFunctionsMutex_.
     void ClearEventFunctionsLocked();
 
+    // Script thread, each event-loop pass. Fires the "render" listeners once if a frame was rendered
+    // since they last fired (see events::RenderFrames).
+    void FireRenderIfNewFrame();
+
     void ThreadMain(const std::stop_token& stopToken);
     void SetupIsolate();
     void TeardownIsolate();
@@ -249,6 +253,8 @@ class Script : public std::enable_shared_from_this<Script> {
     std::vector<std::vector<uint8_t>> args_;
     std::atomic<ScriptState> state_{ScriptState::Stopped};
     std::shared_ptr<spdlog::logger> logger_;
+    // The frame this script last fired "render" for. Script-thread-only.
+    uint32_t lastRenderFrame_;
 
     std::jthread thread_;
     // Shared ownership prevents use-after-dispose: Stop() and PostEvent() (called
diff --git a/src/runtime/runtime.vcxproj b/src/runtime/runtime.vcxproj
index d07b27f..4c89ec3 100644
--- a/src/runtime/runtime.vcxproj
+++ b/src/runtime/runtime.vcxproj
@@ -177,6 +177,7 @@
     <ClInclude Include="components\events\DelayedEvent.h" />
     <ClInclude Include="components\events\Events.h" />
     <ClInclude Include="components\events\EventDispatch.h" />
+    <ClInclude Include="components\events\RenderFrames.h" />
     <!-- Console -->
     <ClInclude Include="components\console\ConsoleSink.h" />
     <ClInclude Include="components\console\Console.h" />
diff --git a/tests/runtime/events/RenderFramesTest.cpp b/tests/runtime/events/RenderFramesTest.cpp
new file mode 100644
index 0000000..0bca74a
--- /dev/null
+++ b/tests/runtime/events/RenderFramesTest.cpp
@@ -0,0 +1,48 @@
+#include <doctest/doctest.h>
+
+#include <cstdint>
+
+#include "components/events/RenderFrames.h"
+
+using d2bs::runtime::events::RenderFrames;
+
+TEST_CASE("RenderFrames counts rendered frames") {
+    const auto before = RenderFrames::Latest();
+    RenderFrames::Count();
+    CHECK(RenderFrames::Latest() == before + 1);
+    RenderFrames::Count();
+    CHECK(RenderFrames::Latest() == before + 2);
+}
+
+TEST_CASE("RenderFrames fires once per new frame and coalesces the frames a script missed") {
+    uint32_t seen = RenderFrames::Latest();
+    CHECK_FALSE(RenderFrames::TakeNew(seen));
+
+    RenderFrames::Count();
+    REQUIRE(RenderFrames::TakeNew(seen));
+    CHECK(seen == RenderFrames::Latest());
+    CHECK_FALSE(RenderFrames::TakeNew(seen));
+
+    const auto before = seen;
+    RenderFrames::Count();
+    RenderFrames::Count();
+    RenderFrames::Count();
+    REQUIRE(RenderFrames::TakeNew(seen));
+    CHECK(seen == before + 3);
+    CHECK_FALSE(RenderFrames::TakeNew(seen));
+}
+
+TEST_CASE("RenderFrames tracks each script's last frame independently") {
+    uint32_t fast = RenderFrames::Latest();
+    uint32_t slow = fast;
+
+    RenderFrames::Count();
+    CHECK(RenderFrames::TakeNew(fast));
+    RenderFrames::Count();
+    CHECK(RenderFrames::TakeNew(fast));
+
+    CHECK(RenderFrames::TakeNew(slow));
+    CHECK(slow == fast);
+    CHECK_FALSE(RenderFrames::TakeNew(fast));
+    CHECK_FALSE(RenderFrames::TakeNew(slow));
+}
diff --git a/tests/runtime/fakes/GameLoopCollaborators.cpp b/tests/runtime/fakes/GameLoopCollaborators.cpp
index 1f0451f..d79ecf1 100644
--- a/tests/runtime/fakes/GameLoopCollaborators.cpp
+++ b/tests/runtime/fakes/GameLoopCollaborators.cpp
@@ -33,6 +33,11 @@ void ManaEventDispatch(uint32_t mana) {
 void PlayerAssignEventDispatch(uint32_t unitId) {
     test::State().playerAssignEvents.push_back(unitId);
 }
+void RenderEventDispatch() {
+    auto& s = test::State();
+    ++s.renderEventCount;
+    s.drawAllCountAtRender = s.drawAllCount;
+}
 
 }  // namespace d2bs::runtime::events
 
diff --git a/tests/runtime/fakes/GameLoopCollaborators.h b/tests/runtime/fakes/GameLoopCollaborators.h
index 85d8148..fa6066e 100644
--- a/tests/runtime/fakes/GameLoopCollaborators.h
+++ b/tests/runtime/fakes/GameLoopCollaborators.h
@@ -30,6 +30,9 @@ struct GameLoopState {
     std::vector<uint32_t> playerAssignEvents;
     int32_t exitGameCount = 0;
     int32_t drawAllCount = 0;
+    int32_t renderEventCount = 0;
+    // drawAllCount when the latest render event was dispatched.
+    int32_t drawAllCountAtRender = -1;
     std::optional<d2bs::game::GameState> lastDrawState;
 };
 
diff --git a/tests/runtime/fakes/shims/components/events/EventDispatch.h b/tests/runtime/fakes/shims/components/events/EventDispatch.h
index 0436284..164094b 100644
--- a/tests/runtime/fakes/shims/components/events/EventDispatch.h
+++ b/tests/runtime/fakes/shims/components/events/EventDispatch.h
@@ -4,7 +4,7 @@
 //
 // Test-only shim for components/events/EventDispatch.h. The real header pulls
 // in <v8.h> via ScriptBroadcastEventDispatch, which the test binary does not
-// link. GameLoop.cpp only touches the three dispatchers below, so that's all we
+// link. GameLoop.cpp only touches the dispatchers below, so that's all we
 // declare here; the capturing implementations live in
 // tests/runtime/fakes/GameLoopCollaborators.cpp.
 
@@ -15,5 +15,6 @@ namespace d2bs::runtime::events {
 void LifeEventDispatch(uint32_t life);
 void ManaEventDispatch(uint32_t mana);
 void PlayerAssignEventDispatch(uint32_t unitId);
+void RenderEventDispatch();
 
 }  // namespace d2bs::runtime::events
diff --git a/tests/runtime/gameloop/GameLoopTest.cpp b/tests/runtime/gameloop/GameLoopTest.cpp
index d78b4b9..8015b98 100644
--- a/tests/runtime/gameloop/GameLoopTest.cpp
+++ b/tests/runtime/gameloop/GameLoopTest.cpp
@@ -258,6 +258,23 @@ TEST_CASE_FIXTURE(GameLoopFixture, "OnDraw paints drawables with most recently o
     // NOLINTEND(bugprone-unchecked-optional-access)
 }
 
+TEST_CASE_FIXTURE(GameLoopFixture, "OnDraw counts the render frame once per frame, before the drawables") {
+    auto& s = d2bs::test::State();
+
+    GameLoop::Instance().OnSleep(std::chrono::milliseconds{0});
+    CHECK(s.renderEventCount == 0);
+
+    GameLoop::Instance().OnDraw();
+    CHECK(s.renderEventCount == 1);
+    CHECK(s.drawAllCountAtRender == 0);
+    CHECK(s.drawAllCount == 1);
+
+    GameLoop::Instance().OnDraw();
+    CHECK(s.renderEventCount == 2);
+    CHECK(s.drawAllCountAtRender == 1);
+    CHECK(s.drawAllCount == 2);
+}
+
 TEST_CASE_FIXTURE(GameLoopFixture, "waitForProfile disables script lifecycle") {
     auto& cfg = d2bs::core::config::GetAppConfig();
     cfg.waitForProfile.store(true);
diff --git a/tests/runtime/js_tests.vcxproj b/tests/runtime/js_tests.vcxproj
index 9afbe99..c5530f3 100644
--- a/tests/runtime/js_tests.vcxproj
+++ b/tests/runtime/js_tests.vcxproj
@@ -155,6 +155,8 @@
     <ClCompile Include="api\LockedHandleTest.cpp" />
     <!-- GameLoop tests -->
     <ClCompile Include="gameloop\GameLoopTest.cpp" />
+    <!-- Render event coalescing tests -->
+    <ClCompile Include="events\RenderFramesTest.cpp" />
   </ItemGroup>
   <PropertyGroup Label="Vcpkg">
     <VcpkgEnabled>true</VcpkgEnabled>

From f2e5548c65aa5d9b94fdef5431eb17ec3e49f9f7 Mon Sep 17 00:00:00 2001
From: Resurrected Trader <admin@resurrected.trade>
Date: Thu, 8 Oct 2026 20:41:16 +0100
Subject: [PATCH 2/3] runtime: count render frames with FrameCounter, without a
 dispatch step

RenderFrames becomes FrameCounter (a uint64_t count, Increment / Current)
and RenderEventDispatch goes: GameLoop::OnDraw increments the counter
itself. Script::FireRenderEventIfNewFrame fires when the current frame is
past the one it last fired for and the script listens for "render", and
only then records it, so a listener added later fires on the next pass.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/game_thread_safety.md                    |  7 +--
 .../components/events/EventDispatch.cpp       |  5 --
 src/runtime/components/events/EventDispatch.h |  3 --
 src/runtime/components/events/Events.h        |  6 +--
 src/runtime/components/events/FrameCounter.h  | 22 +++++++++
 src/runtime/components/events/RenderFrames.h  | 33 -------------
 src/runtime/components/gameloop/GameLoop.cpp  |  3 +-
 src/runtime/components/script/Script.cpp      | 15 +++---
 src/runtime/components/script/Script.h        |  6 +--
 src/runtime/runtime.vcxproj                   |  2 +-
 tests/runtime/events/FrameCounterTest.cpp     | 13 +++++
 tests/runtime/events/RenderFramesTest.cpp     | 48 -------------------
 tests/runtime/fakes/GameLoopCollaborators.cpp |  7 +--
 tests/runtime/fakes/GameLoopCollaborators.h   |  5 +-
 .../shims/components/events/EventDispatch.h   |  3 +-
 tests/runtime/gameloop/GameLoopTest.cpp       | 12 +++--
 tests/runtime/js_tests.vcxproj                |  2 +-
 17 files changed, 69 insertions(+), 123 deletions(-)
 create mode 100644 src/runtime/components/events/FrameCounter.h
 delete mode 100644 src/runtime/components/events/RenderFrames.h
 create mode 100644 tests/runtime/events/FrameCounterTest.cpp
 delete mode 100644 tests/runtime/events/RenderFramesTest.cpp

diff --git a/docs/game_thread_safety.md b/docs/game_thread_safety.md
index 4e38552..56727ad 100644
--- a/docs/game_thread_safety.md
+++ b/docs/game_thread_safety.md
@@ -183,11 +183,12 @@ game::GameThread::Execute([&] {
 ## Per-frame events (`render`)
 
 The `render` event is a signal, not a queued event. `GameLoop::OnDraw` (the backend's `onDraw` callback, once
-per rendered frame, in and out of game) only increments a global frame counter (`events::RenderFrames`,
-`components/events/RenderFrames.h`) before `Drawable::DrawAll`; it queues nothing and never waits on a script,
+per rendered frame, in and out of game) only increments a global frame counter (`events::FrameCounter`,
+`components/events/FrameCounter.h`) before `Drawable::DrawAll`; it queues nothing and never waits on a script,
 so a frame costs one atomic increment whether or not any script listens. Each pass of a script's event loop
 (`Script::ExecuteEvents`, i.e. inside `delay()`) compares the counter with the frame the script last fired
-`render` for and, if it moved, fires the `render` listeners once with the latest frame number. No wake-up is
+`render` for and, if it moved and the script listens for `render`, fires the listeners once with the latest frame
+number. No wake-up is
 needed: the loop already polls every `IdleSleepIntervalMs`, the same latency as any cross-thread posted event. A
 slow script just sees a bigger jump in `frame`; there is no backlog to drain.
 
diff --git a/src/runtime/components/events/EventDispatch.cpp b/src/runtime/components/events/EventDispatch.cpp
index 2862811..9d7b1a1 100644
--- a/src/runtime/components/events/EventDispatch.cpp
+++ b/src/runtime/components/events/EventDispatch.cpp
@@ -8,7 +8,6 @@
 #include <utility>
 
 #include "Events.h"
-#include "RenderFrames.h"
 #include "components/script/Commands.h"
 #include "components/script/ScriptEngine.h"
 #include "config/AppConfig.h"
@@ -129,10 +128,6 @@ void CopyDataEventDispatch(game::IpcMode mode, const std::string& payload) {
     FireIfListening<CopyDataEvent>(mode, payload);
 }
 
-void RenderEventDispatch() {
-    RenderFrames::Count();
-}
-
 void ScriptBroadcastEventDispatch(const v8::FunctionCallbackInfo<v8::Value>& args) {
     // Not probed: constructing this serialises the arguments, which can run script code (getters),
     // so skipping it when nobody listens would be observable.
diff --git a/src/runtime/components/events/EventDispatch.h b/src/runtime/components/events/EventDispatch.h
index 5e29667..5fbcbea 100644
--- a/src/runtime/components/events/EventDispatch.h
+++ b/src/runtime/components/events/EventDispatch.h
@@ -36,9 +36,6 @@ void ItemActionEventDispatch(uint32_t unitId, uint32_t action, const std::string
 void GameActionEventDispatch(int32_t mode, uint32_t param1, uint32_t param2, const std::string& name1,
                              const std::string& name2);
 void CopyDataEventDispatch(game::IpcMode mode, const std::string& payload);
-// Once per rendered frame, on the game thread, before the drawables are drawn. Only counts the frame:
-// each script fires its "render" listeners from its own event loop (Script::ExecuteEvents).
-void RenderEventDispatch();
 void ScriptBroadcastEventDispatch(const v8::FunctionCallbackInfo<v8::Value>& args);
 
 // Blockable event dispatchers (return true if event was blocked)
diff --git a/src/runtime/components/events/Events.h b/src/runtime/components/events/Events.h
index d34d24f..50edccc 100644
--- a/src/runtime/components/events/Events.h
+++ b/src/runtime/components/events/Events.h
@@ -533,12 +533,12 @@ class BroadcastEvent : public BaseEvent {
 class RenderEvent : public BaseEvent {
    protected:
     std::vector<v8::Local<v8::Value>> MakeArgs(v8::Isolate* isolate) const override {
-        return {api::convert::ToJS(isolate, frame)};
+        return {api::convert::ToJS(isolate, static_cast<double>(frame))};
     }
 
    public:
-    explicit RenderEvent(uint32_t frame) : frame(frame) {}
-    const uint32_t frame;
+    explicit RenderEvent(uint64_t frame) : frame(frame) {}
+    const uint64_t frame;
     static constexpr std::string_view EVENT_NAME = "render";
     [[nodiscard]] std::string_view Name() const override { return EVENT_NAME; }
 };
diff --git a/src/runtime/components/events/FrameCounter.h b/src/runtime/components/events/FrameCounter.h
new file mode 100644
index 0000000..453de1b
--- /dev/null
+++ b/src/runtime/components/events/FrameCounter.h
@@ -0,0 +1,22 @@
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+
+namespace d2bs::runtime::events {
+
+// Rendered frames since load. The game thread counts each frame; each script fires its "render"
+// listeners from its own event loop when the count has moved past the frame it last fired for, so
+// nothing is queued per frame and a script that falls behind just sees a bigger jump.
+class FrameCounter {
+    inline static std::atomic<uint64_t> count_ = 0;
+
+   public:
+    // Game thread, once per rendered frame.
+    static void Increment() { count_.fetch_add(1, std::memory_order_relaxed); }
+
+    // Any thread. The number of the most recently rendered frame (the first is 1).
+    static uint64_t Current() { return count_.load(std::memory_order_relaxed); }
+};
+
+}  // namespace d2bs::runtime::events
diff --git a/src/runtime/components/events/RenderFrames.h b/src/runtime/components/events/RenderFrames.h
deleted file mode 100644
index e4cf0ea..0000000
--- a/src/runtime/components/events/RenderFrames.h
+++ /dev/null
@@ -1,33 +0,0 @@
-#pragma once
-
-#include <atomic>
-#include <cstdint>
-
-namespace d2bs::runtime::events {
-
-// The per-frame "render" event is a signal, not a queued event: the game thread only counts rendered
-// frames, and each script's event loop fires its render listeners when the count has moved since it
-// last did. Nothing is queued per frame, so a script that falls behind just sees a bigger jump. Kept
-// free of V8 so the coalescing can be tested on its own.
-class RenderFrames {
-    inline static std::atomic<uint32_t> count_ = 0;
-
-   public:
-    // Game thread, once per rendered frame.
-    static void Count() { count_.fetch_add(1, std::memory_order_relaxed); }
-
-    // Any thread. The number of the most recently rendered frame (the first is 1).
-    static uint32_t Latest() { return count_.load(std::memory_order_relaxed); }
-
-    // True if a frame was rendered since `seen`, which then moves to the latest frame.
-    static bool TakeNew(uint32_t& seen) {
-        const uint32_t latest = Latest();
-        if (latest == seen) {
-            return false;
-        }
-        seen = latest;
-        return true;
-    }
-};
-
-}  // namespace d2bs::runtime::events
diff --git a/src/runtime/components/gameloop/GameLoop.cpp b/src/runtime/components/gameloop/GameLoop.cpp
index 90f4590..34069d6 100644
--- a/src/runtime/components/gameloop/GameLoop.cpp
+++ b/src/runtime/components/gameloop/GameLoop.cpp
@@ -11,6 +11,7 @@
 #include "components/drawing/Drawable.h"
 #include "components/drawing/VersionBanner.h"
 #include "components/events/EventDispatch.h"
+#include "components/events/FrameCounter.h"
 #include "components/profile/ProfileService.h"
 #include "components/script/Script.h"
 #include "components/script/ScriptEngine.h"
@@ -209,7 +210,7 @@ void GameLoop::OnSleep(std::chrono::milliseconds duration) {
 void GameLoop::OnDraw() const {
     // Fires from the render function, before the next OnSleep has taken a new
     // snapshot - previous_.state is the most recently observed game state.
-    events::RenderEventDispatch();
+    events::FrameCounter::Increment();
     drawing::Drawable::DrawAll(previous_.state);
     // Always-on "d2bsng <version>" corner banner (carries the update-available
     // marker). Drawn after script drawables so it stays on top.
diff --git a/src/runtime/components/script/Script.cpp b/src/runtime/components/script/Script.cpp
index c0420d5..2b05d69 100644
--- a/src/runtime/components/script/Script.cpp
+++ b/src/runtime/components/script/Script.cpp
@@ -24,7 +24,7 @@
 #include "components/events/DelayedEvent.h"
 #include "components/events/EventDispatch.h"
 #include "components/events/Events.h"
-#include "components/events/RenderFrames.h"
+#include "components/events/FrameCounter.h"
 #include "components/inspector/ScriptInspector.h"
 #include "components/script/CompileSource.h"
 #include "components/script/NativeCallHook.h"
@@ -75,7 +75,7 @@ Script::Script(std::filesystem::path path, ScriptMode mode, std::vector<std::vec
       mode_(mode),
       args_(std::move(args)),
       logger_(utils::GetLogger(path_.filename().string())),
-      lastRenderFrame_(events::RenderFrames::Latest()) {}
+      lastRenderFrame_(events::FrameCounter::Current()) {}
 
 std::shared_ptr<spdlog::logger> GetLogger(v8::Isolate* isolate) {
     if (auto* script = ScriptEngine::Instance().GetScript(isolate)) {
@@ -889,7 +889,7 @@ void Script::ExecuteEvents(std::chrono::milliseconds duration) {
             inspector_->DrainIncoming();
         }
 
-        FireRenderIfNewFrame();
+        FireRenderEventIfNewFrame();
 
         // steady_clock::now() is QueryPerformanceCounter on MSVC, so each read
         // routes through the speedhack hook: take one reading per pass and reuse it
@@ -922,12 +922,13 @@ void Script::ExecuteEvents(std::chrono::milliseconds duration) {
     }
 }
 
-void Script::FireRenderIfNewFrame() {
-    // The frame is consumed even with no listener, so adding one later waits for the next frame.
-    if (!events::RenderFrames::TakeNew(lastRenderFrame_) || !IsEventRegistered(events::RenderEvent::EVENT_NAME)) {
+void Script::FireRenderEventIfNewFrame() {
+    const auto current = events::FrameCounter::Current();
+    if (current <= lastRenderFrame_ || !IsEventRegistered(events::RenderEvent::EVENT_NAME)) {
         return;
     }
-    ExecuteEvent(std::make_shared<events::RenderEvent>(lastRenderFrame_));
+    lastRenderFrame_ = current;
+    ExecuteEvent(std::make_shared<events::RenderEvent>(current));
 }
 
 bool Script::ExecuteEvent(const std::shared_ptr<events::BaseEvent>& event) {
diff --git a/src/runtime/components/script/Script.h b/src/runtime/components/script/Script.h
index 3079123..b32e5af 100644
--- a/src/runtime/components/script/Script.h
+++ b/src/runtime/components/script/Script.h
@@ -230,8 +230,8 @@ class Script : public std::enable_shared_from_this<Script> {
     void ClearEventFunctionsLocked();
 
     // Script thread, each event-loop pass. Fires the "render" listeners once if a frame was rendered
-    // since they last fired (see events::RenderFrames).
-    void FireRenderIfNewFrame();
+    // since they last fired (see events::FrameCounter).
+    void FireRenderEventIfNewFrame();
 
     void ThreadMain(const std::stop_token& stopToken);
     void SetupIsolate();
@@ -254,7 +254,7 @@ class Script : public std::enable_shared_from_this<Script> {
     std::atomic<ScriptState> state_{ScriptState::Stopped};
     std::shared_ptr<spdlog::logger> logger_;
     // The frame this script last fired "render" for. Script-thread-only.
-    uint32_t lastRenderFrame_;
+    uint64_t lastRenderFrame_;
 
     std::jthread thread_;
     // Shared ownership prevents use-after-dispose: Stop() and PostEvent() (called
diff --git a/src/runtime/runtime.vcxproj b/src/runtime/runtime.vcxproj
index 4c89ec3..7663fc6 100644
--- a/src/runtime/runtime.vcxproj
+++ b/src/runtime/runtime.vcxproj
@@ -177,7 +177,7 @@
     <ClInclude Include="components\events\DelayedEvent.h" />
     <ClInclude Include="components\events\Events.h" />
     <ClInclude Include="components\events\EventDispatch.h" />
-    <ClInclude Include="components\events\RenderFrames.h" />
+    <ClInclude Include="components\events\FrameCounter.h" />
     <!-- Console -->
     <ClInclude Include="components\console\ConsoleSink.h" />
     <ClInclude Include="components\console\Console.h" />
diff --git a/tests/runtime/events/FrameCounterTest.cpp b/tests/runtime/events/FrameCounterTest.cpp
new file mode 100644
index 0000000..772bf29
--- /dev/null
+++ b/tests/runtime/events/FrameCounterTest.cpp
@@ -0,0 +1,13 @@
+#include <doctest/doctest.h>
+
+#include "components/events/FrameCounter.h"
+
+using d2bs::runtime::events::FrameCounter;
+
+TEST_CASE("FrameCounter counts rendered frames") {
+    const auto before = FrameCounter::Current();
+    FrameCounter::Increment();
+    CHECK(FrameCounter::Current() == before + 1);
+    FrameCounter::Increment();
+    CHECK(FrameCounter::Current() == before + 2);
+}
diff --git a/tests/runtime/events/RenderFramesTest.cpp b/tests/runtime/events/RenderFramesTest.cpp
deleted file mode 100644
index 0bca74a..0000000
--- a/tests/runtime/events/RenderFramesTest.cpp
+++ /dev/null
@@ -1,48 +0,0 @@
-#include <doctest/doctest.h>
-
-#include <cstdint>
-
-#include "components/events/RenderFrames.h"
-
-using d2bs::runtime::events::RenderFrames;
-
-TEST_CASE("RenderFrames counts rendered frames") {
-    const auto before = RenderFrames::Latest();
-    RenderFrames::Count();
-    CHECK(RenderFrames::Latest() == before + 1);
-    RenderFrames::Count();
-    CHECK(RenderFrames::Latest() == before + 2);
-}
-
-TEST_CASE("RenderFrames fires once per new frame and coalesces the frames a script missed") {
-    uint32_t seen = RenderFrames::Latest();
-    CHECK_FALSE(RenderFrames::TakeNew(seen));
-
-    RenderFrames::Count();
-    REQUIRE(RenderFrames::TakeNew(seen));
-    CHECK(seen == RenderFrames::Latest());
-    CHECK_FALSE(RenderFrames::TakeNew(seen));
-
-    const auto before = seen;
-    RenderFrames::Count();
-    RenderFrames::Count();
-    RenderFrames::Count();
-    REQUIRE(RenderFrames::TakeNew(seen));
-    CHECK(seen == before + 3);
-    CHECK_FALSE(RenderFrames::TakeNew(seen));
-}
-
-TEST_CASE("RenderFrames tracks each script's last frame independently") {
-    uint32_t fast = RenderFrames::Latest();
-    uint32_t slow = fast;
-
-    RenderFrames::Count();
-    CHECK(RenderFrames::TakeNew(fast));
-    RenderFrames::Count();
-    CHECK(RenderFrames::TakeNew(fast));
-
-    CHECK(RenderFrames::TakeNew(slow));
-    CHECK(slow == fast);
-    CHECK_FALSE(RenderFrames::TakeNew(fast));
-    CHECK_FALSE(RenderFrames::TakeNew(slow));
-}
diff --git a/tests/runtime/fakes/GameLoopCollaborators.cpp b/tests/runtime/fakes/GameLoopCollaborators.cpp
index d79ecf1..30972ce 100644
--- a/tests/runtime/fakes/GameLoopCollaborators.cpp
+++ b/tests/runtime/fakes/GameLoopCollaborators.cpp
@@ -4,6 +4,7 @@
 #include "components/drawing/Drawable.h"
 #include "components/drawing/VersionBanner.h"
 #include "components/events/EventDispatch.h"
+#include "components/events/FrameCounter.h"
 #include "components/script/ScriptEngine.h"
 #include "config/AppConfig.h"
 
@@ -33,11 +34,6 @@ void ManaEventDispatch(uint32_t mana) {
 void PlayerAssignEventDispatch(uint32_t unitId) {
     test::State().playerAssignEvents.push_back(unitId);
 }
-void RenderEventDispatch() {
-    auto& s = test::State();
-    ++s.renderEventCount;
-    s.drawAllCountAtRender = s.drawAllCount;
-}
 
 }  // namespace d2bs::runtime::events
 
@@ -48,6 +44,7 @@ void Drawable::DrawAll(game::GameState state) {
     auto& s = test::State();
     ++s.drawAllCount;
     s.lastDrawState = state;
+    s.frameAtDraw = events::FrameCounter::Current();
 }
 
 // GameLoop::OnDraw also draws the version banner; the real implementation pulls
diff --git a/tests/runtime/fakes/GameLoopCollaborators.h b/tests/runtime/fakes/GameLoopCollaborators.h
index fa6066e..f07bce6 100644
--- a/tests/runtime/fakes/GameLoopCollaborators.h
+++ b/tests/runtime/fakes/GameLoopCollaborators.h
@@ -30,9 +30,8 @@ struct GameLoopState {
     std::vector<uint32_t> playerAssignEvents;
     int32_t exitGameCount = 0;
     int32_t drawAllCount = 0;
-    int32_t renderEventCount = 0;
-    // drawAllCount when the latest render event was dispatched.
-    int32_t drawAllCountAtRender = -1;
+    // FrameCounter::Current() when DrawAll last ran.
+    uint64_t frameAtDraw = 0;
     std::optional<d2bs::game::GameState> lastDrawState;
 };
 
diff --git a/tests/runtime/fakes/shims/components/events/EventDispatch.h b/tests/runtime/fakes/shims/components/events/EventDispatch.h
index 164094b..0436284 100644
--- a/tests/runtime/fakes/shims/components/events/EventDispatch.h
+++ b/tests/runtime/fakes/shims/components/events/EventDispatch.h
@@ -4,7 +4,7 @@
 //
 // Test-only shim for components/events/EventDispatch.h. The real header pulls
 // in <v8.h> via ScriptBroadcastEventDispatch, which the test binary does not
-// link. GameLoop.cpp only touches the dispatchers below, so that's all we
+// link. GameLoop.cpp only touches the three dispatchers below, so that's all we
 // declare here; the capturing implementations live in
 // tests/runtime/fakes/GameLoopCollaborators.cpp.
 
@@ -15,6 +15,5 @@ namespace d2bs::runtime::events {
 void LifeEventDispatch(uint32_t life);
 void ManaEventDispatch(uint32_t mana);
 void PlayerAssignEventDispatch(uint32_t unitId);
-void RenderEventDispatch();
 
 }  // namespace d2bs::runtime::events
diff --git a/tests/runtime/gameloop/GameLoopTest.cpp b/tests/runtime/gameloop/GameLoopTest.cpp
index 8015b98..a151b20 100644
--- a/tests/runtime/gameloop/GameLoopTest.cpp
+++ b/tests/runtime/gameloop/GameLoopTest.cpp
@@ -8,6 +8,7 @@
 #include <system_error>
 #include <thread>
 
+#include "components/events/FrameCounter.h"
 #include "components/gameloop/GameLoop.h"
 #include "components/profile/ProfileService.h"
 #include "components/script/Commands.h"
@@ -21,6 +22,7 @@
 #include "utils/utils.h"
 
 using d2bs::game::GameState;
+using d2bs::runtime::events::FrameCounter;
 using d2bs::runtime::gameloop::GameLoop;
 
 namespace {
@@ -262,16 +264,16 @@ TEST_CASE_FIXTURE(GameLoopFixture, "OnDraw counts the render frame once per fram
     auto& s = d2bs::test::State();
 
     GameLoop::Instance().OnSleep(std::chrono::milliseconds{0});
-    CHECK(s.renderEventCount == 0);
+    const auto before = FrameCounter::Current();
 
     GameLoop::Instance().OnDraw();
-    CHECK(s.renderEventCount == 1);
-    CHECK(s.drawAllCountAtRender == 0);
+    CHECK(FrameCounter::Current() == before + 1);
+    CHECK(s.frameAtDraw == before + 1);
     CHECK(s.drawAllCount == 1);
 
     GameLoop::Instance().OnDraw();
-    CHECK(s.renderEventCount == 2);
-    CHECK(s.drawAllCountAtRender == 1);
+    CHECK(FrameCounter::Current() == before + 2);
+    CHECK(s.frameAtDraw == before + 2);
     CHECK(s.drawAllCount == 2);
 }
 
diff --git a/tests/runtime/js_tests.vcxproj b/tests/runtime/js_tests.vcxproj
index c5530f3..90d9ae5 100644
--- a/tests/runtime/js_tests.vcxproj
+++ b/tests/runtime/js_tests.vcxproj
@@ -156,7 +156,7 @@
     <!-- GameLoop tests -->
     <ClCompile Include="gameloop\GameLoopTest.cpp" />
     <!-- Render event coalescing tests -->
-    <ClCompile Include="events\RenderFramesTest.cpp" />
+    <ClCompile Include="events\FrameCounterTest.cpp" />
   </ItemGroup>
   <PropertyGroup Label="Vcpkg">
     <VcpkgEnabled>true</VcpkgEnabled>

From e41797fe9158c3f2be533974c01c613bcec8d743 Mon Sep 17 00:00:00 2001
From: Resurrected Trader <admin@resurrected.trade>
Date: Thu, 8 Oct 2026 20:51:20 +0100
Subject: [PATCH 3/3] runtime: never fire render inside a render handler

A render handler that calls delay() runs the event loop again, and a frame
drawn during that delay would fire render inside itself, one level deeper
every frame until the stack runs out. A per-thread flag (each script has
its own thread) skips render while its handler runs; the frames drawn
meanwhile fold into the next call.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/game_thread_safety.md               | 3 ++-
 src/runtime/components/events/Events.h   | 3 ++-
 src/runtime/components/script/Script.cpp | 8 ++++++++
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/docs/game_thread_safety.md b/docs/game_thread_safety.md
index 56727ad..192f46a 100644
--- a/docs/game_thread_safety.md
+++ b/docs/game_thread_safety.md
@@ -190,7 +190,8 @@ so a frame costs one atomic increment whether or not any script listens. Each pa
 `render` for and, if it moved and the script listens for `render`, fires the listeners once with the latest frame
 number. No wake-up is
 needed: the loop already polls every `IdleSleepIntervalMs`, the same latency as any cross-thread posted event. A
-slow script just sees a bigger jump in `frame`; there is no backlog to drain.
+slow script just sees a bigger jump in `frame`; there is no backlog to drain. The loop never fires `render` inside a `render`
+handler: a handler that calls `delay()` would otherwise see a new frame and nest one level deeper every frame.
 
 Handlers run on the script's thread, so a frame is usually already being drawn by then: a drawable change made
 in a `render` handler typically shows from the next frame. Drawable fields are atomics, so the handler needs no
diff --git a/src/runtime/components/events/Events.h b/src/runtime/components/events/Events.h
index 50edccc..2bcb840 100644
--- a/src/runtime/components/events/Events.h
+++ b/src/runtime/components/events/Events.h
@@ -527,7 +527,8 @@ class BroadcastEvent : public BaseEvent {
 /// @event A frame was rendered (in game and out of game). Fires at most once per frame, so handlers can move or
 /// restyle drawables every frame. Handlers run on the script's own thread whenever its event loop runs (inside
 /// delay()), so a change usually shows from the next frame. A script that falls behind fires once for all the frames
-/// it missed rather than once per frame.
+/// it missed rather than once per frame; render never fires inside its own handler, so a delay() there skips the frames
+/// drawn meanwhile.
 /// @param frame {number} - the number of the most recently rendered frame, counted from load; compare with the previous
 /// call's to see how many frames were skipped
 class RenderEvent : public BaseEvent {
diff --git a/src/runtime/components/script/Script.cpp b/src/runtime/components/script/Script.cpp
index 2b05d69..fa392f4 100644
--- a/src/runtime/components/script/Script.cpp
+++ b/src/runtime/components/script/Script.cpp
@@ -923,11 +923,19 @@ void Script::ExecuteEvents(std::chrono::milliseconds duration) {
 }
 
 void Script::FireRenderEventIfNewFrame() {
+    // A render handler that calls delay() runs this event loop again, and a frame drawn during that delay would
+    // fire render inside itself, nesting deeper every frame. Each script has its own thread, so this is per script.
+    static thread_local bool isInRenderHandler = false;
+    if (isInRenderHandler) {
+        return;
+    }
     const auto current = events::FrameCounter::Current();
     if (current <= lastRenderFrame_ || !IsEventRegistered(events::RenderEvent::EVENT_NAME)) {
         return;
     }
     lastRenderFrame_ = current;
+    isInRenderHandler = true;
+    const utils::DeferGuard leaveHandler([] { isInRenderHandler = false; });
     ExecuteEvent(std::make_shared<events::RenderEvent>(current));
 }