M4: Stage.FixedUpdate + Time's fixed-step accumulator

Both were explicitly deferred to M4 by ITime and Stage's own doc comments
back when they were written: a FixedUpdate stage with no real accumulator
behind it would be actively misleading, and building the accumulator with
no physics system to test it against would be untested speculative
machinery. engine.physics (next) is the real consumer.

Time.ConsumeFixedSteps accumulates DeltaTime and hands back how many
FixedDeltaTime-sized (1/50s) steps it can pay for, capped at 5 per frame
so a real stall becomes visible lag instead of a catch-up burst of
physics steps. Engine.Host calls it once per frame in both the headless
and windowed loops, running Stage.FixedUpdate that many times before
Stage.Update — gated by IPlayModeController.IsPlaying the same way Update
already is, and only accumulating time while actually playing, so
entering Play doesn't open with a burst of steps for however long Edit
mode had been sitting idle.

3 new tests on the accumulator itself (below-one-step, whole-steps-plus-
remainder, the 5-step cap under a simulated stall). Full suite: 76 tests.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N1qPfzq8TDCUMFMV3UwV5N

src/Engine.Host/Program.cs

@@ -270,9 +270,19 @@ if (windowed)
         // before this plugin existed. With one loaded, Update only runs
         // while actually Playing: Edit mode still renders the scene every
         // frame (so the editor UI stays responsive and the view isn't
-        // frozen mid-edit), it just never ticks it.
+        // frozen mid-edit), it just never ticks it. FixedUpdate is gated
+        // the same way and for the same reason — physics shouldn't step
+        // while Edit mode has the world frozen — and only accumulates time
+        // while playing, so Play doesn't open with a catch-up burst of
+        // steps for however long Edit mode had been sitting idle.
         if (playMode is null || playMode.IsPlaying)
+        {
+            var fixedSteps = time.ConsumeFixedSteps();
+            for (var step = 0; step < fixedSteps; step++)
+                schedule.RunStage(Stage.FixedUpdate, world);
+
             schedule.RunStage(Stage.Update, world);
+        }
 
         schedule.RunStage(Stage.Render, world);
         schedule.RunStage(Stage.Present, world);
@@ -313,6 +323,11 @@ else
     for (var frame = 0; frame < frames; frame++)
     {
         time.Tick(headlessDeltaTime);
+
+        var fixedSteps = time.ConsumeFixedSteps();
+        for (var step = 0; step < fixedSteps; step++)
+            schedule.RunStage(Stage.FixedUpdate, world);
+
         schedule.RunStage(Stage.Update, world);
     }
 

src/Engine.Kernel/Diagnostics/ITime.cs

@@ -3,13 +3,12 @@ namespace Engine.Kernel.Diagnostics;
 /// <summary>
 /// Frame clock. See docs/kernel-contract.md §2.
 ///
-/// No fixed-step accumulator yet — that was in the original kernel scope
+/// M4 adds the fixed-step accumulator this doc comment used to say was
-/// but nothing consumes it: building it now, with no physics system to
+/// missing: engine.physics needs to step Box3D at a constant rate
-/// test it against, would be exactly the kind of untested speculative
+/// regardless of how the real frame rate wobbles, and a "FixedUpdate"
-/// machinery this project has avoided everywhere else. It arrives with
+/// stage without a real accumulator behind it would be actively
-/// M4, alongside the Stage.FixedUpdate it would drive — a "FixedUpdate"
+/// misleading, not just incomplete. See Stage.FixedUpdate and
-/// stage without a real fixed-timestep accumulator behind it would be
+/// Time.ConsumeFixedSteps for the actual mechanism.
-/// actively misleading, not just incomplete.
 /// </summary>
 public interface ITime
 {
@@ -20,4 +19,12 @@ public interface ITime
     double ElapsedTime { get; }
 
     int FrameCount { get; }
+
+    /// <summary>
+    /// The constant step size Stage.FixedUpdate always runs at, regardless
+    /// of the real frame rate — 1/50s. Not per-project configurable yet:
+    /// nothing has needed a different rate, and a setting nobody's asked
+    /// for is speculative the same way an unconsumed accumulator was.
+    /// </summary>
+    float FixedDeltaTime { get; }
 }

src/Engine.Kernel/Diagnostics/Time.cs

@@ -2,15 +2,26 @@ namespace Engine.Kernel.Diagnostics;
 
 /// <summary>
 /// Read-only to plugins (ITime); advanced by whoever owns the frame loop —
-/// Engine.Host today, headless or windowed — via <see cref="Tick"/>, which
+/// Engine.Host today, headless or windowed — via <see cref="Tick"/> and
-/// isn't on the interface. Same split as Schedule/ISchedule: the host gets
+/// <see cref="ConsumeFixedSteps"/>, neither on the interface. Same split as
-/// the extra, plugin-facing code doesn't.
+/// Schedule/ISchedule: the host gets the extra, plugin-facing code doesn't.
 /// </summary>
 public sealed class Time : ITime
 {
+    // Capped so a real stall — a debugger pause, a slow disk load — can't
+    // turn into a catch-up burst of hundreds of physics steps executing
+    // back to back, each one still assuming a normal frame budget around
+    // it. Five steps behind (0.1s at the default rate) already means
+    // something else is wrong; better to visibly fall behind real time
+    // than to freeze the process trying to simulate through it.
+    private const int MaxStepsPerFrame = 5;
+
+    private float _accumulator;
+
     public float DeltaTime { get; private set; }
     public double ElapsedTime { get; private set; }
     public int FrameCount { get; private set; }
+    public float FixedDeltaTime { get; } = 1f / 50f;
 
     public void Tick(float deltaTime)
     {
@@ -18,4 +29,25 @@ public sealed class Time : ITime
         ElapsedTime += deltaTime;
         FrameCount++;
     }
+
+    /// <summary>
+    /// Adds this frame's DeltaTime to the accumulator and returns how many
+    /// FixedDeltaTime-sized steps it can pay for, having already deducted
+    /// that much. Call once per frame, then run Stage.FixedUpdate that many
+    /// times (zero is normal — most frames are shorter than FixedDeltaTime
+    /// at 50Hz against a 60+fps display).
+    /// </summary>
+    public int ConsumeFixedSteps()
+    {
+        _accumulator += DeltaTime;
+
+        var steps = 0;
+        while (_accumulator >= FixedDeltaTime && steps < MaxStepsPerFrame)
+        {
+            _accumulator -= FixedDeltaTime;
+            steps++;
+        }
+
+        return steps;
+    }
 }

src/Engine.Kernel/Scheduling/Stage.cs

@@ -3,16 +3,22 @@ namespace Engine.Kernel.Scheduling;
 /// <summary>
 /// Fixed, kernel-defined, not plugin-extensible — see "Frame stages" in
 /// docs/kernel-contract.md §8. <see cref="Present"/> is the second addition
-/// to the original {Update, Render} set (after FixedUpdate was scoped for
+/// to the original {Update, Render} set, added for M3's editor: engine.
-/// M4), added for M3's editor: engine.render splits its old single
+/// render splits its old single Clear+Draw+SwapBuffers system into a
-/// Clear+Draw+SwapBuffers system into a Render-stage draw and a
+/// Render-stage draw and a Present-stage swap specifically so engine.
-/// Present-stage swap specifically so engine.editor's ImGui overlay — which
+/// editor's ImGui overlay — which has to run after the scene is drawn but
-/// has to run after the scene is drawn but before the buffers swap — has
+/// before the buffers swap — has somewhere to register that isn't a race
-/// somewhere to register that isn't a race against load order. Not a stage
+/// against load order. <see cref="FixedUpdate"/> is the third, arriving
-/// added speculatively: SwapBuffers already needed to move somewhere real.
+/// with M4 exactly as ITime's own doc comment said it would: engine.physics
+/// steps Box3D here, at ITime.FixedDeltaTime's fixed rate, run zero-or-more
+/// times per frame by the accumulator Engine.Host drives — see
+/// Time.ConsumeFixedSteps. Runs before Update each frame it fires, so
+/// gameplay code reading a Rigidbody's position in Update sees this frame's
+/// physics result, not last frame's.
 /// </summary>
 public enum Stage
 {
+    FixedUpdate,
     Update,
     Render,
     Present,

tests/Engine.Kernel.Tests/TimeTests.cs

@@ -38,4 +38,37 @@ public class TimeTests
         Assert.Equal(0.75, time.ElapsedTime, 3);
         Assert.Equal(2, time.FrameCount);
     }
+
+    [Fact]
+    public void ConsumeFixedSteps_BelowOneStep_ReturnsZero()
+    {
+        var time = new Time();
+
+        // FixedDeltaTime is 1/50 = 0.02s; a 60fps-ish frame is shorter.
+        time.Tick(0.01f);
+
+        Assert.Equal(0, time.ConsumeFixedSteps());
+    }
+
+    [Fact]
+    public void ConsumeFixedSteps_ConsumesWholeStepsAndKeepsRemainder()
+    {
+        var time = new Time();
+
+        time.Tick(0.05f); // 2.5 steps' worth
+        Assert.Equal(2, time.ConsumeFixedSteps());
+
+        time.Tick(0.03f); // remainder 0.01 + 0.03 = 0.04 -> 2 more steps
+        Assert.Equal(2, time.ConsumeFixedSteps());
+    }
+
+    [Fact]
+    public void ConsumeFixedSteps_CapsAtFiveEvenAfterAHugeStall()
+    {
+        var time = new Time();
+
+        time.Tick(10f); // a debugger pause, not a real frame
+
+        Assert.Equal(5, time.ConsumeFixedSteps());
+    }
 }