From 11f37672a04ae90981e3f3976db1be2bca30f2b1 Mon Sep 17 00:00:00 2001 From: gamer147 Date: Sun, 2 Aug 2026 23:45:15 -0400 Subject: [PATCH] Extract VM surface opcode handler --- docs/PROJECT-STRUCTURE.md | 5 +- docs/remake-architecture-and-roadmap.md | 12 ++- .../Age.Engine/Vm/VirtualMachine.Surface.cs | 78 +++++++++++++++++++ engine/Age.Engine/Vm/VirtualMachine.cs | 69 +++------------- 4 files changed, 103 insertions(+), 61 deletions(-) create mode 100644 engine/Age.Engine/Vm/VirtualMachine.Surface.cs diff --git a/docs/PROJECT-STRUCTURE.md b/docs/PROJECT-STRUCTURE.md index 75fd983..8e42bd0 100644 --- a/docs/PROJECT-STRUCTURE.md +++ b/docs/PROJECT-STRUCTURE.md @@ -177,7 +177,10 @@ opcode dispatcher. Its partial-class companion `engine/Age.Engine/Vm/VirtualMach state, BGM restart semantics, and the BGM/voice/SFX/mixer opcode handler; `Step` retains the audio labels and routes that family into the handler. `engine/Age.Engine/Vm/VirtualMachine.Movie.cs` owns modal/asynchronous/ positioned movie playback, movie surface metadata/activity queries, and movie-mask transition dispatch; `Step` -likewise retains and routes the movie labels. +likewise retains and routes the movie labels. `engine/Age.Engine/Vm/VirtualMachine.Surface.cs` owns surface +allocation/loading, texture binding and sizing, mutable surface fill/copy, render-target control, and transient +surface release; its labels remain at their existing dispatcher positions around the retained numeric-glyph and +object cases. The disposable `build/page-map-.jsonl` files are produced by editor/development Godot runs and map runtime ADV page ordinals to their authoritative script offsets for `tools/locate_page.py`. Packaged exports diff --git a/docs/remake-architecture-and-roadmap.md b/docs/remake-architecture-and-roadmap.md index 273d278..3d8af1f 100644 --- a/docs/remake-architecture-and-roadmap.md +++ b/docs/remake-architecture-and-roadmap.md @@ -636,6 +636,12 @@ do not mix mechanical moves with semantic changes. existing positions and routes them through `StepMovie`; the original instruction remains available for the two bytecode-offset compatibility paths. Runtime validation remains green. + The third bounded `VirtualMachine.Step` extraction moved surface allocation/loading, texture binding and + sizing, mutable surface fill/copy, render-target control, and transient-surface release into + `engine/Age.Engine/Vm/VirtualMachine.Surface.cs`. The top-level dispatcher retains these labels at their + existing positions, including the separate routing groups around numeric-glyph and retained-object cases; + public VM behavior and case-body logic remain unchanged. Runtime validation remains green. + **Gate:** no externally visible behavior or command changes; generated artifacts are byte-identical where deterministic, and the corresponding engine, Python, Godot, and corpus validations remain green after each domain move. @@ -1007,8 +1013,8 @@ layer's rendering diverges from ADV; save layout. ## 8. Immediate next step Continue step 2 of the **codebase consolidation** maintenance slice: behavior-neutral physical splits backed by the tracked launcher and layered validation driver. With the planned `Main`, `GodotAdvHost`, and `GfxState` -domains isolated and the first two `VirtualMachine.Step` families routed through domain handlers, extract the -surface/texture opcode family next without replacing the proven dispatcher or changing public types, commands, -and generated output. +domains isolated and the audio, movie, and surface/texture `VirtualMachine.Step` families routed through domain +handlers, extract the retained-object query/mutation and transform opcode family next without replacing the +proven dispatcher or changing public types, commands, and generated output. Concrete playthrough blockers may still preempt this bounded maintenance work; the consolidation effort does not replace Phase B gameplay validation or the open cross-platform gates. diff --git a/engine/Age.Engine/Vm/VirtualMachine.Surface.cs b/engine/Age.Engine/Vm/VirtualMachine.Surface.cs new file mode 100644 index 0000000..a4ae148 --- /dev/null +++ b/engine/Age.Engine/Vm/VirtualMachine.Surface.cs @@ -0,0 +1,78 @@ +using Age.Engine.Hosting; +using Age.Engine.Model; + +namespace Age.Engine.Vm; + +public sealed partial class VirtualMachine +{ + private int StepSurface(string label, IReadOnlyList a, int pc) + { + switch (label) + { + case "create-texture": // 0x1f8 (slot)(w)(h) — allocate a blank surface at the slot + _host.ReleaseSurface((int)Read(a[0])); + Gfx.CreateSurface((int)Read(a[0])); + _host.CreateTexture((int)Read(a[0]), (int)Read(a[1]), (int)Read(a[2])); return pc + 1; + case "set-texture": // 0x1f9 (resId)(slot)(colorkey) — load a file into the slot's surface + { + long resourceId = Read(a[0]); + if (_diagSetTexture) // AGE_DIAG_SETTEX: log the SLOT operand source (literal vs which global) — grey-BG slot dig + System.Console.Error.WriteLine($"[settex] resId=0x{resourceId:x} slot={(int)Read(a[1])} " + + $"slotOp=(type={a[1].Type} val=0x{a[1].Value:x}){(a[1].Type == 3 ? $" G[0x{a[1].Value:x}]" : "")}"); + _host.ReleaseSurface((int)Read(a[1])); + long colorKey = a.Count > 2 ? Read(a[2]) : -1; + Gfx.SetSurface((int)Read(a[1]), resourceId, colorKey); + _host.SetTexture(resourceId, (int)Read(a[1]), colorKey); + return pc + 1; // host still tracks dims for get-texture-size + } + case "u00422E80": // pre-reference compatibility + case "set-tiled-surface-edge-length": // 0x248 (edge pixels) + Gfx.SetTiledSurfaceEdgeLength(Read(a[0])); + return pc + 1; + case "u00422EB0": // pre-reference compatibility + case "load-raw-texture-surface": // 0x249 (packed resource id)(slot)(colorkey) + { + // Native shares 0x1f9's release/load/colorkey path, but constructs its mode-1 + // surface subclass. Both texture opcodes receive the same universal packed id; + // the CPU compositor does not need the D3D subclass distinction. + long resourceId = Read(a[0]); + int surfaceSlot = (int)Read(a[1]); + _host.ReleaseSurface(surfaceSlot); + Gfx.SetSurface(surfaceSlot, resourceId, Read(a[2])); + _host.SetTexture(resourceId, surfaceSlot, Read(a[2])); + return pc + 1; + } + case "draw-texture": // 0x1fb (handle)(slot)(srcX)(srcY)(w)(h)(dstX)(dstY) — bind object -> surface + rect + pos + Gfx.BindDraw(Read(a[0]), (int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), + (int)Read(a[4]), (int)Read(a[5]), (int)Read(a[6]), (int)Read(a[7])); + _host.DrawTexture((int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), (int)Read(a[4]), + (int)Read(a[5]), (int)Read(a[6]), (int)Read(a[7])); return pc + 1; // IHost seam (oracle log; Godot no-ops) + case "get-texture-size": // 0x208 (slot) (out_w) (out_h) + { + var (gw, gh) = _host.GetTextureSize((int)Read(a[0])); + Write(a[1], gw); Write(a[2], gh); + return pc + 1; + } + case "fill-surface-rect": // 0x20b: clipped alpha/RGB fill of a mutable surface + case "u00420D50": + _host.FillSurfaceRect(new SurfaceRectFill( + (int)Read(a[0]), (int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), (int)Read(a[4]), + (int)System.Math.Min(Read(a[5]), 255), Read(a[6]) & 0x00ff_ffff)); + return pc + 1; + case "copy-surface-rect": // 0x207: paired-clipped source-to-destination surface copy + _host.CopySurfaceRect(new SurfaceRectCopy( + (int)Read(a[0]), (int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), + (int)Read(a[4]), (int)Read(a[5]), (int)Read(a[6]), (int)Read(a[7]))); + return pc + 1; + case "select-render-target": // 0x20d: slot <1000 selects a surface; >=1000 restores backbuffer + Gfx.SelectRenderTarget(Read(a[0])); return pc + 1; + case "clear-render-target": // 0x20e: clear color to black and depth to one + _host.ClearRenderTarget(Gfx.CurrentRenderTargetSlot); return pc + 1; + case "release-transient-surfaces": // 0x23d: native fixed range [42,1000) + Gfx.ReleaseSurfaceRange(42, 1000 - 42); + _host.ReleaseSurfaceRange(42, 1000 - 42); return pc + 1; + default: + throw new InvalidOperationException($"Non-surface opcode routed to surface handler: {label}"); + } + } +} diff --git a/engine/Age.Engine/Vm/VirtualMachine.cs b/engine/Age.Engine/Vm/VirtualMachine.cs index 5b1f961..7760015 100644 --- a/engine/Age.Engine/Vm/VirtualMachine.cs +++ b/engine/Age.Engine/Vm/VirtualMachine.cs @@ -2449,44 +2449,14 @@ public sealed partial class VirtualMachine _advTextStyle = _advTextStyle with { FontFace = ReadStr(a[0]) }; return pc + 1; case "comment": case "display-furigana": case "dev_ukn": return pc + 1; - case "create-texture": // 0x1f8 (slot)(w)(h) — allocate a blank surface at the slot - _host.ReleaseSurface((int)Read(a[0])); - Gfx.CreateSurface((int)Read(a[0])); - _host.CreateTexture((int)Read(a[0]), (int)Read(a[1]), (int)Read(a[2])); return pc + 1; - case "set-texture": // 0x1f9 (resId)(slot)(colorkey) — load a file into the slot's surface - { - long resourceId = Read(a[0]); - if (_diagSetTexture) // AGE_DIAG_SETTEX: log the SLOT operand source (literal vs which global) — grey-BG slot dig - System.Console.Error.WriteLine($"[settex] resId=0x{resourceId:x} slot={(int)Read(a[1])} " + - $"slotOp=(type={a[1].Type} val=0x{a[1].Value:x}){(a[1].Type == 3 ? $" G[0x{a[1].Value:x}]" : "")}"); - _host.ReleaseSurface((int)Read(a[1])); - long colorKey = a.Count > 2 ? Read(a[2]) : -1; - Gfx.SetSurface((int)Read(a[1]), resourceId, colorKey); - _host.SetTexture(resourceId, (int)Read(a[1]), colorKey); - return pc + 1; // host still tracks dims for get-texture-size - } + case "create-texture": + case "set-texture": case "u00422E80": // pre-reference compatibility case "set-tiled-surface-edge-length": // 0x248 (edge pixels) - Gfx.SetTiledSurfaceEdgeLength(Read(a[0])); - return pc + 1; case "u00422EB0": // pre-reference compatibility case "load-raw-texture-surface": // 0x249 (packed resource id)(slot)(colorkey) - { - // Native shares 0x1f9's release/load/colorkey path, but constructs its mode-1 - // surface subclass. Both texture opcodes receive the same universal packed id; - // the CPU compositor does not need the D3D subclass distinction. - long resourceId = Read(a[0]); - int surfaceSlot = (int)Read(a[1]); - _host.ReleaseSurface(surfaceSlot); - Gfx.SetSurface(surfaceSlot, resourceId, Read(a[2])); - _host.SetTexture(resourceId, surfaceSlot, Read(a[2])); - return pc + 1; - } - case "draw-texture": // 0x1fb (handle)(slot)(srcX)(srcY)(w)(h)(dstX)(dstY) — bind object -> surface + rect + pos - Gfx.BindDraw(Read(a[0]), (int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), - (int)Read(a[4]), (int)Read(a[5]), (int)Read(a[6]), (int)Read(a[7])); - _host.DrawTexture((int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), (int)Read(a[4]), - (int)Read(a[5]), (int)Read(a[6]), (int)Read(a[7])); return pc + 1; // IHost seam (oracle log; Godot no-ops) + case "draw-texture": + return StepSurface(label, a, pc); case "u0041F3A0": case "register-numeric-glyph-style": // 0x13a: (style)(surface)(atlas x/y)(digit w/h) { @@ -2515,32 +2485,17 @@ public sealed partial class VirtualMachine } return pc + 1; } - case "get-texture-size": // 0x208 (slot) (out_w) (out_h) - { - var (gw, gh) = _host.GetTextureSize((int)Read(a[0])); - Write(a[1], gw); Write(a[2], gh); - return pc + 1; - } - case "fill-surface-rect": // 0x20b: clipped alpha/RGB fill of a mutable surface + case "get-texture-size": + case "fill-surface-rect": case "u00420D50": - _host.FillSurfaceRect(new SurfaceRectFill( - (int)Read(a[0]), (int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), (int)Read(a[4]), - (int)System.Math.Min(Read(a[5]), 255), Read(a[6]) & 0x00ff_ffff)); - return pc + 1; - case "copy-surface-rect": // 0x207: paired-clipped source-to-destination surface copy - _host.CopySurfaceRect(new SurfaceRectCopy( - (int)Read(a[0]), (int)Read(a[1]), (int)Read(a[2]), (int)Read(a[3]), - (int)Read(a[4]), (int)Read(a[5]), (int)Read(a[6]), (int)Read(a[7]))); - return pc + 1; + case "copy-surface-rect": + return StepSurface(label, a, pc); case "clear-retained-gfx-objects": // 0x1f6: erase object records, but preserve surfaces Gfx.ClearRetainedObjects(); return pc + 1; - case "select-render-target": // 0x20d: slot <1000 selects a surface; >=1000 restores backbuffer - Gfx.SelectRenderTarget(Read(a[0])); return pc + 1; - case "clear-render-target": // 0x20e: clear color to black and depth to one - _host.ClearRenderTarget(Gfx.CurrentRenderTargetSlot); return pc + 1; - case "release-transient-surfaces": // 0x23d: native fixed range [42,1000) - Gfx.ReleaseSurfaceRange(42, 1000 - 42); - _host.ReleaseSurfaceRange(42, 1000 - 42); return pc + 1; + case "select-render-target": + case "clear-render-target": + case "release-transient-surfaces": + return StepSurface(label, a, pc); case "play-bgm": case "restart-bgm-loop": case "stop-bgm":