runtime: per-frame render event as a frame-counter signal (alternative to #89)

[ResurrectedTrader]

An alternative to #89 with the same user-facing render event, done as a signal instead of a queued event. Pick one of the two; they conflict.

Design

• GameLoop::OnDraw (the backend's onDraw callback, once per rendered frame, in and out of game) calls events::FrameCounter::Increment(): one relaxed atomic increment, before Drawable::DrawAll. It queues nothing, takes no lock, and never touches a script.
• Each pass of a script's event loop (Script::ExecuteEvents, which delay() runs) calls Script::FireRenderEventIfNewFrame() right after pumping the V8 task queue. If FrameCounter::Current() is past the frame this script last fired for (lastRenderFrame_) and the script has a render listener, it fires the listeners once, synchronously, with that frame number, and only then records it.
• No wake-up is needed. The loop already wakes every IdleSleepIntervalMs (default 10 ms) to service cross-thread posted events, so a waiting script sees a new frame with that same latency, without busy-polling.

Coalescing comes for free. A slow script fires once and sees a bigger jump in frame. There is no backlog, and no per-script pending state to manage.

How it differs from #89

• RenderLatch (arm / disarm / deliver, the per-script delivery timestamp) is gone. The per-script state is one uint64_t lastRenderFrame_, touched only on the script thread.
• The game thread does no per-frame work beyond the increment. It has no ListenerCount probe, no ForEachScript walk, no event allocation, no PostEvent, and no failure path. runtime: add a per-frame render script event #89 walks the scripts and posts an event to each listener every frame.
• Payload: just frame, the latest rendered frame number. elapsed is dropped; scripts can use getTickCount().
• render fires only from the event loop (delay() and the other ExecuteEvents waits). runtime: add a per-frame render script event #89's posted event is also run only by PumpMessageLoop inside the same loop, so scripts see no difference.
• The diff is smaller: 17 files, +183/-6, against 16 files, +209/-5. Most of both is tests and docs.

Tests

• FrameCounterTest: counting rendered frames.
• GameLoopTest (reused from runtime: add a per-frame render script event #89): OnDraw raises the render dispatch once per frame, before the drawables are drawn.

Verification

• build.ps1 Release (Win32): 0 warnings, 0 errors.
• build.ps1 test: 174/174 test cases passed.
• build.ps1 check-format: clean.
• extract_api.py and then gen_dts.py emit addEventListener(event: "render", callback: (frame: number) => void), and tsc --noEmit --lib es2020 on the d.ts exits 0.

Not live-tested in game. This is #89's example script, using getTickCount() in place of elapsed:

function main() {
    var label = new Text("render event", 100, 100, 4, 1);
    var x = 100;
    var last = getTickCount();
    addEventListener("render", function (frame) {
        var now = getTickCount();
        x += (now - last) * 0.1;     // ~100 px/s regardless of frame rate
        last = now;
        if (x > 700) x = 100;
        label.x = x;
        label.text = "frame " + frame;
    });
    while (true) delay(1000);
}

🤖 Generated with Claude Code