Implement movie surface stop-time queries

engine/Age.Engine.Tests/MovieOpcodeTests.cs

@@ -100,6 +100,70 @@ public class MovieOpcodeTests
         Assert.Equal(0x33, vm.Gfx.SnapshotVisibleObjects().Single().SurfaceResId);
     }
 
+    [Fact]
+    public void QueryMovieStopTimeReturnsTheValueRetainedByPlayMovie()
+    {
+        var table = OpcodeTableJson.Load(Paths.OpcodesJson);
+        var script = ScriptAssembler.Assemble(table, "MOVIE-TIME", new List<(int, Operand[])>
+        {
+            (0x236, new[] { new Operand(0, 0x33), new Operand(0, 5), new Operand(0, 2), new Operand(0, 0) }),
+            (0x23f, new[] { new Operand(3, 0x1234), new Operand(0, 5) }),
+            (0x2, System.Array.Empty<Operand>()),
+        }, System.Array.Empty<string>());
+        var host = new RecordingHost { MovieStopTimeMs = 1876 };
+        var vm = new VirtualMachine(script, table, host);
+
+        vm.Run();
+
+        Assert.Equal(1876, vm.Globals[0x1234]);
+        Assert.True(vm.Gfx.TryGetMovieStopTime(5, out long? retained));
+        Assert.Equal(1876, retained);
+        Assert.Empty(host.Warnings);
+
+        vm.Gfx.SetSurface(5, 0x34, 0); // replacing the native surface tears down its movie metadata
+        Assert.False(vm.Gfx.TryGetMovieStopTime(5, out _));
+    }
+
+    [Fact]
+    public void QueryMovieStopTimeReturnsMinusOneWithoutWarningForAnEmptyMovieSlot()
+    {
+        var table = OpcodeTableJson.Load(Paths.OpcodesJson);
+        var script = ScriptAssembler.Assemble(table, "EMPTY-MOVIE-TIME", new List<(int, Operand[])>
+        {
+            (0x23f, new[] { new Operand(3, 0x1234), new Operand(0, 5) }),
+            (0x2, System.Array.Empty<Operand>()),
+        }, System.Array.Empty<string>());
+        var host = new RecordingHost();
+        var vm = new VirtualMachine(script, table, host);
+        vm.Gfx.GetOrCreate(5); // retained-object existence is unrelated to the native movie-object slot
+
+        vm.Run();
+
+        Assert.Equal(-1, vm.Globals[0x1234]);
+        Assert.Empty(host.Warnings);
+    }
+
+    [Fact]
+    public void QueryMovieStopTimeWarnsAndReturnsMinusOneWhenMetadataIsUnavailable()
+    {
+        var table = OpcodeTableJson.Load(Paths.OpcodesJson);
+        var script = ScriptAssembler.Assemble(table, "MISSING-MOVIE-TIME", new List<(int, Operand[])>
+        {
+            (0x236, new[] { new Operand(0, 0x33), new Operand(0, 5), new Operand(0, 2), new Operand(0, 0) }),
+            (0x23f, new[] { new Operand(3, 0x1234), new Operand(0, 5) }),
+            (0x2, System.Array.Empty<Operand>()),
+        }, System.Array.Empty<string>());
+        var host = new RecordingHost();
+        var vm = new VirtualMachine(script, table, host);
+
+        vm.Run();
+
+        Assert.Equal(-1, vm.Globals[0x1234]);
+        string warning = Assert.Single(host.Warnings);
+        Assert.Contains("movie stop-time unavailable MISSING-MOVIE-TIME@", warning);
+        Assert.Contains("surface=5; returning -1", warning);
+    }
+
     [Fact]
     public void Sc0000MoviePayloadReadsFromArchiveVfsAndIsMpegProgramStream()
     {
@@ -136,6 +200,8 @@ public class MovieOpcodeTests
         var entry = resources.Resolve("SC0000", 0x33)!;
         using var decoder = new DirectShowMovieDecoder(resources.ReadMovie(entry));
 
+        Assert.True(decoder.StopTimeMs > 0, "DirectShow should expose a positive IMediaPosition stop time");
+
         var deadline = DateTime.UtcNow.AddSeconds(10);
         RgbaImage? frame = null;
         while (DateTime.UtcNow < deadline && !decoder.TryTakeFrame(out frame))

engine/Age.Engine.Tests/TestSupport.cs

@@ -38,6 +38,7 @@ internal class RecordingHost : IHost
     public readonly List<int> SfxReleases = new();
     public readonly List<(int Target, long Duration)> BgmFades = new();
     public readonly List<(long Resource, int Surface, long Flags, long SyncMask)> Movies = new();
+    public long? MovieStopTimeMs;
     public readonly List<(long Resource, int Surface, long Flags)> ModalMovies = new();
     public readonly List<int> ClearedRenderTargets = new();
     public readonly List<(int First, int Count)> ReleasedSurfaceRanges = new();
@@ -45,11 +46,13 @@ internal class RecordingHost : IHost
     public readonly List<(long Resource, int Slot)> Textures = new();
     public readonly List<bool> MessageSkipChanges = new();
     public readonly List<bool> PhysicalMessageSkipChanges = new();
+    public readonly List<string> Warnings = new();
     public readonly List<long> CursorResources = new();
     public readonly List<bool> AdvPagePresentationSuspended = new();
     public int CursorClearCount;
     public int SceneContextResets;
     public long TextureResourceIdOffset;
+    public void ReportWarning(string message) => Warnings.Add(message);
     public long ResolveTextureResourceId(long resourceId) => resourceId + TextureResourceIdOffset;
     public void ShowText(int offset, string text) => Lines.Add((offset, text));
     public void SetAdvTextCursor(int layoutSlot, int x, int y) => TextCursors.Add((layoutSlot, x, y));
@@ -145,8 +148,11 @@ internal class RecordingHost : IHost
         => ScheduledSfxStarts.Add((channel, startMode, delayMs));
     public void ReleaseSoundEffect(int channel) => SfxReleases.Add(channel);
     public void FadeBgm(int targetPercent, long durationMs) => BgmFades.Add((targetPercent, durationMs));
-    public void PlayMovieToSurface(long resourceId, int surfaceSlot, long movieFlags, long syncMask)
-        => Movies.Add((resourceId, surfaceSlot, movieFlags, syncMask));
+    public long? PlayMovieToSurface(long resourceId, int surfaceSlot, long movieFlags, long syncMask)
+    {
+        Movies.Add((resourceId, surfaceSlot, movieFlags, syncMask));
+        return MovieStopTimeMs;
+    }
     public void PlayModalMovieToSurface(long rawResourceId, int surfaceSlot, long movieFlags)
         => ModalMovies.Add((rawResourceId, surfaceSlot, movieFlags));
 }