Add idle frame handling and document frame lifecycle

Test/BlingoEngine.Tests/Casts/DummyTextMember.cs

@@ -32,7 +32,7 @@ internal class DummyTextMember : IBlingoMemberTextBase, IBlingoMemberTextBaseInt
     public int Height { get; set; }
     public long Size { get; set; }
     public string Comments { get; set; } = string.Empty;
-    public string FileName { get; set; }
+    public string FileName { get; set; } = string.Empty;
     public BlingoMemberType Type { get; set; } = BlingoMemberType.Text;
     public string CastName => string.Empty;
     public IBlingoCast Cast => _cast;
@@ -95,7 +95,7 @@ public void InitDefaults() { }
     public IAbstTexture2D? GetTexture() => null;
     public void ChangesHasBeenApplied() { }
     public void LoadFile() { LoadFileCalled = true; }
-    public void SetFileName(string name) => _fileName = name;
+    public void SetFileName(string name) => FileName = name;
 
     public string GetTextMDString()
     {

Test/BlingoEngine.Tests/MovieEventOrderTests.cs

@@ -0,0 +1,103 @@
+using System.Collections.Generic;
+using System.Linq;
+using BlingoEngine.Events;
+using BlingoEngine.Movies;
+using BlingoEngine.Movies.Events;
+using BlingoEngine.Tests.Fakes;
+
+namespace BlingoEngine.Tests;
+
+public class MovieEventOrderTests
+{
+    [Fact]
+    public void AdvanceFrame_RaisesFrameLifecycleEventsInManualOrder()
+    {
+        var timeline = new List<string>();
+        var mediator = new BlingoEventMediator();
+        var frameHandler = new RecordingFrameHandler(timeline);
+        mediator.Subscribe(frameHandler);
+        mediator.SubscribeStepFrame(frameHandler);
+
+        var harness = FakeBlingoMovieBuilder.Create(mediator, timeline);
+        PrivateFieldSetter.SetField(harness.Movie, "_isPlaying", true);
+
+        harness.Movie.AdvanceFrame();
+        harness.Movie.OnIdle(1f / 60f);
+        harness.Movie.AdvanceFrame();
+
+        var expected = new[]
+        {
+            "beginSprite",
+            "stepFrame",
+            "prepareFrame",
+            "enterFrame",
+            "idleFrame",
+            "exitFrame",
+            "endSprite"
+        };
+
+        Assert.True(timeline.Count >= expected.Length, "timeline missing expected callbacks");
+        Assert.Equal(expected, timeline.Take(expected.Length));
+    }
+}
+
+public class TransitionEventOrderTests
+{
+    [Fact]
+    public void AdvanceFrame_RaisesTransitionLifecycleAroundFrameHandlers()
+    {
+        var timeline = new List<string>();
+        var mediator = new BlingoEventMediator();
+        var frameHandler = new RecordingFrameHandler(timeline);
+        mediator.Subscribe(frameHandler);
+        mediator.SubscribeStepFrame(frameHandler);
+
+        var harness = FakeBlingoMovieBuilder.Create(mediator, timeline, options =>
+        {
+            options.RecordTransitionLifecycle = true;
+            options.TransitionActivationFrame = 1;
+        });
+
+        harness.TransitionPlayer.StartResult = false;
+        PrivateFieldSetter.SetField(harness.Movie, "_isPlaying", true);
+
+        harness.Movie.AdvanceFrame();
+        harness.Movie.OnIdle(1f / 60f);
+        harness.Movie.AdvanceFrame();
+
+        var expected = new[]
+        {
+            "beginSprite",
+            "transition.beginSprite",
+            "stepFrame",
+            "prepareFrame",
+            "enterFrame",
+            "idleFrame",
+            "exitFrame",
+            "endSprite",
+            "transition.endSprite"
+        };
+
+        Assert.True(timeline.Count >= expected.Length, "timeline missing expected callbacks");
+        Assert.Equal(expected, timeline.Take(expected.Length));
+        Assert.Equal(1, harness.TransitionPlayer.StartCallCount);
+    }
+}
+
+internal sealed class RecordingFrameHandler : IHasStepFrameEvent, IHasPrepareFrameEvent,
+    IHasEnterFrameEvent, IHasIdleFrameEvent, IHasExitFrameEvent
+{
+    private readonly List<string> _timeline;
+
+    internal RecordingFrameHandler(List<string> timeline) => _timeline = timeline;
+
+    public void StepFrame() => _timeline.Add("stepFrame");
+
+    public void PrepareFrame() => _timeline.Add("prepareFrame");
+
+    public void EnterFrame() => _timeline.Add("enterFrame");
+
+    public void IdleFrame() => _timeline.Add("idleFrame");
+
+    public void ExitFrame() => _timeline.Add("exitFrame");
+}

src/BlingoEngine/Core/BlingoClock.cs

@@ -6,6 +6,7 @@
     public interface IBlingoClockListener
     {
         void OnTick();
+        void OnIdle(float deltaTime);
     }
     /// <summary>
     /// Lingo Clock interface.
@@ -38,13 +39,29 @@ public void Tick(float deltaTime)
             _accumulatedTime += deltaTime;
             float frameTime = 1f / FrameRate;
 
+            int framesDispatched = 0;
             while (_accumulatedTime >= frameTime)
             {
                 foreach (var l in _listeners) l.OnTick();
                 EngineTickCount++;
-
+                framesDispatched++;
                 _accumulatedTime -= frameTime;
             }
+
+            if (framesDispatched == 0)
+            {
+                if (deltaTime > 0f)
+                {
+                    foreach (var listener in _listeners)
+                        listener.OnIdle(deltaTime);
+                }
+            }
+            else if (_accumulatedTime > 0f)
+            {
+                var idleDelta = _accumulatedTime;
+                foreach (var listener in _listeners)
+                    listener.OnIdle(idleDelta);
+            }
         }
 
         public void Subscribe(IBlingoClockListener listener)

src/BlingoEngine/Events/BlingoEventMediator.cs

@@ -28,6 +28,7 @@ public class BlingoEventMediator : IBlingoEventMediator, IBlingoMouseEventHandle
         private readonly List<IHasStepFrameEvent> _stepFrames = new(); // must be handled by actorlist
         private readonly List<IHasPrepareFrameEvent> _prepareFrames = new();
         private readonly List<IHasEnterFrameEvent> _enterFrames = new();
+        private readonly List<IHasIdleFrameEvent> _idleFrames = new();
         private readonly List<IHasExitFrameEvent> _exitFrames = new();
         private readonly List<IHasFocusEvent> _focuss = new();
         private readonly List<IHasBlurEvent> _blurs = new();
@@ -83,6 +84,7 @@ public void Subscribe(object ms, int priority = DefaultPriority, bool ignoreMous
 
             if (ms is IHasPrepareFrameEvent prepareFrameEvent) Insert(_prepareFrames, prepareFrameEvent);
             if (ms is IHasEnterFrameEvent enterFrameEvent) Insert(_enterFrames, enterFrameEvent);
+            if (ms is IHasIdleFrameEvent idleFrameEvent) Insert(_idleFrames, idleFrameEvent);
             if (ms is IHasExitFrameEvent exitFrameEvent) Insert(_exitFrames, exitFrameEvent);
             if (ms is IHasFocusEvent focusEvent) Insert(_focuss, focusEvent);
             if (ms is IHasBlurEvent blurEvent) Insert(_blurs, blurEvent);
@@ -113,6 +115,7 @@ public void Unsubscribe(object ms, bool ignoreMouse = false)
             // Not stepframe it seems stepframe is only used through the actor list.
             if (ms is IHasPrepareFrameEvent prepareFrameEvent) _prepareFrames.Remove(prepareFrameEvent);
             if (ms is IHasEnterFrameEvent enterFrameEvent) _enterFrames.Remove(enterFrameEvent);
+            if (ms is IHasIdleFrameEvent idleFrameEvent) _idleFrames.Remove(idleFrameEvent);
             if (ms is IHasExitFrameEvent exitFrameEvent) _exitFrames.Remove(exitFrameEvent);
             if (ms is IHasFocusEvent focusEvent) _focuss.Remove(focusEvent);
             if (ms is IHasBlurEvent blurEvent) _blurs.Remove(blurEvent);
@@ -148,6 +151,7 @@ bool ShouldRemove(object obj) => string.IsNullOrEmpty(preserveNamespaceFragment)
             FilterList(_mouseExits);
             FilterList(_prepareFrames);
             FilterList(_enterFrames);
+            FilterList(_idleFrames);
             FilterList(_exitFrames);
             FilterList(_focuss);
             FilterList(_blurs);
@@ -172,6 +176,7 @@ bool ShouldRemove(object obj) => string.IsNullOrEmpty(preserveNamespaceFragment)
         internal void RaiseStepFrame() => _stepFrames.ForEach(x => x.StepFrame());
         internal void RaisePrepareFrame() => _prepareFrames.ForEach(x => x.PrepareFrame());
         internal void RaiseEnterFrame() => _enterFrames.ForEach(x => x.EnterFrame());
+        internal void RaiseIdleFrame() => _idleFrames.ForEach(x => x.IdleFrame());
         internal void RaiseExitFrame() => _exitFrames.ForEach(x => x.ExitFrame());
         public void RaiseFocus() => _focuss.ForEach(x => x.Focus());
         public void RaiseBlur() => _blurs.ForEach(x => x.Blur());

src/BlingoEngine/Movies/BlingoDebugOverlay.cs

@@ -75,6 +75,11 @@ public void OnTick()
         _engineFrames++;
     }
 
+    public void OnIdle(float deltaTime)
+    {
+        // Idle callbacks do not affect the debug overlay.
+    }
+
     public void Prepare()
     {
         throw new NotImplementedException();