fix: avoid AGF decode during movie preroll

engine/Age.Engine.Tests/MovieOpcodeTests.cs

@@ -100,6 +100,33 @@ public class MovieOpcodeTests
         Assert.Equal(0x33, vm.Gfx.SnapshotVisibleObjects().Single().SurfaceResId);
     }
 
+    [Fact]
+    public void PlayMovieKeepsCreatedSurfaceBlankDuringSynchronousHostSetup()
+    {
+        var table = OpcodeTableJson.Load(Paths.OpcodesJson);
+        var script = ScriptAssembler.Assemble(table, "MOVIE-PREROLL", new List<(int, Operand[])>
+        {
+            (0x1f8, new[] { new Operand(0, 5), new Operand(0, 800), new Operand(0, 600), new Operand(0, 0) }),
+            (0x1fb, new[]
+            {
+                new Operand(0, 1), new Operand(0, 5), new Operand(0, 0), new Operand(0, 0),
+                new Operand(0, 800), new Operand(0, 600), new Operand(0, 0), new Operand(0, 0),
+            }),
+            (0x236, new[] { new Operand(0, 0x33), new Operand(0, 5), new Operand(0, 2), new Operand(0, 0) }),
+            (0x2, System.Array.Empty<Operand>()),
+        }, System.Array.Empty<string>());
+        var host = new RecordingHost();
+        VirtualMachine? vm = null;
+        long resourceDuringSetup = -1;
+        host.OnPlayMovie = () => resourceDuringSetup = vm!.Gfx.SnapshotVisibleObjects().Single().SurfaceResId;
+        vm = new VirtualMachine(script, table, host);
+
+        vm.Run();
+
+        Assert.Equal(0, resourceDuringSetup);
+        Assert.Equal(0x33, vm.Gfx.SnapshotVisibleObjects().Single().SurfaceResId);
+    }
+
     [Fact]
     public void QueryMovieStopTimeReturnsTheValueRetainedByPlayMovie()
     {

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 System.Action? OnPlayMovie;
     public long? MovieStopTimeMs;
     public readonly List<(long Resource, int Surface, long Flags)> ModalMovies = new();
     public readonly List<int> ClearedRenderTargets = new();
@@ -151,6 +152,7 @@ internal class RecordingHost : IHost
     public long? PlayMovieToSurface(long resourceId, int surfaceSlot, long movieFlags, long syncMask)
     {
         Movies.Add((resourceId, surfaceSlot, movieFlags, syncMask));
+        OnPlayMovie?.Invoke();
         return MovieStopTimeMs;
     }
     public void PlayModalMovieToSurface(long rawResourceId, int surfaceSlot, long movieFlags)

engine/Age.Engine/Vm/VirtualMachine.cs

@@ -1422,10 +1422,13 @@ public sealed class VirtualMachine
                     Gfx.RemapObjectSurface(movieHandle, surfaceSlot, 0);
                     surfaceSlot = 0;
                 }
+                // Graph construction is synchronous. Keep the existing created surface blank during that
+                // boundary; publishing the movie resource first would let a concurrent compositor mistake
+                // the MPEG payload's .AGF name for a still image before the host registers/decodes it.
+                long? stopTimeMs = _host.PlayMovieToSurface(resourceId, surfaceSlot, Read(a[2]), Read(a[3]));
                 // The native CMovieToTexture renderer replaces the pixels of the already-created surface.
                 // Retain the same resource binding so the compositor resolves live movie frames for its objects.
                 Gfx.SetSurface(surfaceSlot, resourceId, 0);
-                long? stopTimeMs = _host.PlayMovieToSurface(resourceId, surfaceSlot, Read(a[2]), Read(a[3]));
                 Gfx.SetMovieStopTime(surfaceSlot, stopTimeMs);
                 return pc + 1; // native cmd size 9 resumes at the next instruction; playback is asynchronous
             }