diff --git a/docs/superpowers/plans/2026-07-06-a2a-godot-dialogue.md b/docs/superpowers/plans/2026-07-06-a2a-godot-dialogue.md new file mode 100644 index 0000000..9b78ea6 --- /dev/null +++ b/docs/superpowers/plans/2026-07-06-a2a-godot-dialogue.md @@ -0,0 +1,437 @@ +# A2a — Interactive Dialogue Loop Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A Godot 4.7 (.NET) project that references `Age.Engine` in-process and plays SC0000's dialogue as a message window that pauses at `wait-for-input` and resumes on a click, proven by a headless self-test. + +**Architecture:** Add one method to the VM's `IHost` seam (`WaitForInput`); the VM core is otherwise unchanged. A Godot project in `godot/` runs `vm.Run()` on a worker thread; the host blocks that thread at `wait-for-input` on a `SemaphoreSlim`, marshals text to the UI via `CallDeferred`, and resumes on click. A `--selftest` mode auto-drives the gate headlessly and asserts the emitted text equals the A1 `vm0-trace.json`. + +**Tech Stack:** C# / .NET 8, Godot 4.7-stable **mono** (`S:/Godot/Godot_v4.7-stable_mono_win64/`), xUnit, `System.Text.Json`. + +## Global Constraints + +- **Work on a feature branch** (e.g. `feat/a2a-godot-dialogue`); do not commit to `main`. +- **Verified Godot toolchain** (spiked 2026-07-06). Let `GODOT="S:/Godot/Godot_v4.7-stable_mono_win64/Godot_v4.7-stable_mono_win64_console.exe"`: + - Import: `"$GODOT" --headless --path godot --import` + - Build C#: `dotnet build godot/Himegari.csproj` (Godot.NET.Sdk restore is cached; no network) + - Run headless: `"$GODOT" --headless --path godot [-- --selftest]` (`OS.GetCmdlineUserArgs()` gets args after `--`) +- The Godot game project targets **`net8.0`** with **`Godot.NET.Sdk/4.7.0`** and `true`, referencing `../engine/Age.Engine/Age.Engine.csproj`. +- **Seam rule preserved:** the only VM-core change is `IHost.WaitForInput()`; `CaptureHost.WaitForInput()` is a no-op so **A1's RECOVER + trace-diff stay green** (nothing the trace observes changes). +- Data via `Age.Engine.Sys4.Paths` (resolves up to `age-reimpl/`; `godot/` is inside it). Prereqs: `build/opcodes.json`, `build/vm0-trace.json`, `../extracted/DATA1/SC0000.BIN` (all present from A1). +- Target scene: **SC0000.BIN** (CLEAN, 186 lines, halt `exit`). +- `.NET`/`Godot` build output stays gitignored (`.godot/`, `engine/**/bin|obj`, `[Bb]in/obj`, `[Oo]bj`); track only source (`godot/*.cs`, `godot/*.tscn`, `godot/project.godot`, `godot/Himegari.csproj`). + +--- + +## File Structure + +``` +engine/Age.Engine/Hosting/IHost.cs (modify: + WaitForInput) +engine/Age.Engine/Hosting/CaptureHost.cs (modify: + WaitForInput no-op) +engine/Age.Engine/Vm/VirtualMachine.cs (modify: wait-for-input calls host) +engine/Age.Engine.Tests/WaitForInputTests.cs (create) +godot/project.godot (create) Godot project, main scene = Main.tscn +godot/Himegari.csproj (create) Godot.NET.Sdk + Age.Engine reference +godot/Main.tscn (create) root Control + script (UI built in code) +godot/Main.cs (create) worker thread, UI methods, input, selftest +godot/GodotAdvHost.cs (create) IHost: capture + CallDeferred + blocking gate +docs/phase-a-slice-plan.md (modify) mark A2a done +``` + +--- + +## Task 1: VM-core `IHost.WaitForInput` hook + +**Files:** Modify `engine/Age.Engine/Hosting/IHost.cs`, `engine/Age.Engine/Hosting/CaptureHost.cs`, `engine/Age.Engine/Vm/VirtualMachine.cs`; Create `engine/Age.Engine.Tests/WaitForInputTests.cs`. + +**Interfaces — Produces:** `IHost.WaitForInput()` called once per `wait-for-input` (0x72) instruction; `CaptureHost.WaitForInput()` no-op. + +- [ ] **Step 1: Write the failing test** — `engine/Age.Engine.Tests/WaitForInputTests.cs`: + +```csharp +using System.Collections.Generic; +using Age.Engine.Hosting; +using Age.Engine.Sys4; +using Age.Engine.Vm; +using Xunit; + +public class WaitForInputTests +{ + private sealed class CountHost : IHost + { + public int Waits; + public List Emitted = new(); + public void ShowText(int offset, string text) => Emitted.Add(offset); + public void CallScript(long id) { } + public void OnStub(int opcode) { } + public void WaitForInput() => Waits++; + } + + [Fact] + public void WaitForInputFiresAndEmittedIsStable() + { + var table = OpcodeTableJson.Load(Paths.OpcodesJson); + var script = Sys4Loader.Load(Paths.Scripts()["SC0000.BIN"], table); + var host = new CountHost(); + var vm = new VirtualMachine(script, table, host); + vm.Run(); + Assert.True(host.Waits > 0, "wait-for-input (0x72) should fire at least once"); + Assert.Equal(186, host.Emitted.Count); // unchanged vs the A1 SC0000 trace + Assert.Equal("exit", vm.HaltReason); + } +} +``` + +- [ ] **Step 2: Run — expect FAIL** (`IHost` has no `WaitForInput`) +```bash +dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~WaitForInputTests +``` +Expected: build error — `CountHost` does not implement `IHost` (missing `WaitForInput`) — i.e. the interface lacks it. + +- [ ] **Step 3: Implement** + +`engine/Age.Engine/Hosting/IHost.cs` — add the method: +```csharp +namespace Age.Engine.Hosting; +public interface IHost +{ + void ShowText(int offset, string text); + void CallScript(long id); + void OnStub(int opcode); + void WaitForInput(); +} +``` +`engine/Age.Engine/Hosting/CaptureHost.cs` — add the no-op (append after `OnStub`): +```csharp + public void WaitForInput() { } +``` +`engine/Age.Engine/Vm/VirtualMachine.cs` — split `wait-for-input` out of the no-op group. Replace: +```csharp + case "end-text-line": case "wait-for-input": case "set-font": + case "comment": case "display-furigana": case "dev_ukn": + return pc + 1; +``` +with: +```csharp + case "wait-for-input": _host.WaitForInput(); return pc + 1; + case "end-text-line": case "set-font": + case "comment": case "display-furigana": case "dev_ukn": + return pc + 1; +``` + +- [ ] **Step 4: Run — expect PASS (new test + full regression)** +```bash +dotnet test engine/AgeEngine.sln +``` +Expected: 7 passed (the new test + the existing 6; RECOVER and TraceDiff unchanged because `CaptureHost.WaitForInput` is a no-op). + +- [ ] **Step 5: Commit** +```bash +git add engine/Age.Engine/Hosting engine/Age.Engine/Vm/VirtualMachine.cs engine/Age.Engine.Tests/WaitForInputTests.cs +git commit -m "feat(a2a): add IHost.WaitForInput hook (wait-for-input 0x72); trace parity preserved" +``` + +--- + +## Task 2: Godot project scaffold + Age.Engine reference (headless smoke) + +**Files:** Create `godot/project.godot`, `godot/Himegari.csproj`, `godot/Main.tscn`, `godot/Main.cs`. + +**Interfaces — Produces:** a buildable Godot .NET project whose `Main._Ready` loads SC0000 via `Age.Engine` and prints a load summary, proving `Paths` + the engine work inside Godot. + +- [ ] **Step 1: Create the project files** + +`godot/project.godot`: +``` +config_version=5 + +[application] +config/name="Himegari (age-reimpl A2a)" +run/main_scene="res://Main.tscn" + +[dotnet] +project/assembly_name="Himegari" +``` +`godot/Himegari.csproj`: +```xml + + + net8.0 + true + enable + + + + + +``` +`godot/Main.tscn` (UI is built in code, so the scene is just the scripted root): +``` +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://Main.cs" id="1"] + +[node name="Main" type="Control"] +layout_mode = 3 +anchors_preset = 15 +script = ExtResource("1") +``` +`godot/Main.cs` (minimal smoke version — replaced in Task 3): +```csharp +using Godot; +using Age.Engine.Sys4; + +public partial class Main : Godot.Control +{ + public override void _Ready() + { + var table = OpcodeTableJson.Load(Paths.OpcodesJson); + var script = Sys4Loader.Load(Paths.Scripts()["SC0000.BIN"], table); + GD.Print($"SMOKE repo={Paths.Repo}"); + GD.Print($"SMOKE SC0000 instrs={script.Instructions.Count} strings={script.Strings.Count}"); + GetTree().Quit(0); + } +} +``` + +- [ ] **Step 2: Import, build, run headless** +```bash +GODOT="S:/Godot/Godot_v4.7-stable_mono_win64/Godot_v4.7-stable_mono_win64_console.exe" +"$GODOT" --headless --path godot --import +dotnet build godot/Himegari.csproj +"$GODOT" --headless --path godot 2>&1 | grep -E 'SMOKE|error|Exception' +``` +Expected: `SMOKE repo=…\age-reimpl`, and `SMOKE SC0000 instrs= strings=` with n>0 (proves `Paths` resolves inside Godot and `Age.Engine` parses SC0000 in-process). If `Paths.Repo` is wrong or missing, `Paths.FindRepo` walks up from the assembly dir for `age-reimpl` — confirm the project is under `age-reimpl/godot/`. + +- [ ] **Step 3: Commit** +```bash +git add godot/project.godot godot/Himegari.csproj godot/Main.tscn godot/Main.cs +git commit -m "feat(a2a): Godot 4.7 .NET project scaffold referencing Age.Engine (headless smoke)" +``` + +--- + +## Task 3: Interactive host + worker thread + headless self-test + +**Files:** Create `godot/GodotAdvHost.cs`; replace `godot/Main.cs`. + +**Interfaces — Consumes:** `IHost`, `VirtualMachine`, `Sys4Loader`, `OpcodeTableJson`, `Paths`. **Produces:** `GodotAdvHost` (blocking gate + capture + `CallDeferred` UI); `Main` (worker thread + selftest). Self-test gate: `--selftest` prints `SELFTEST OK` and exits 0 when the emitted offset sequence equals `build/vm0-trace.json["SC0000.BIN"]`. + +- [ ] **Step 1: Create `godot/GodotAdvHost.cs`** +```csharp +using System.Collections.Generic; +using System.Threading; +using Age.Engine.Hosting; + +public sealed class GodotAdvHost : IHost +{ + private readonly Main _main; + private readonly SemaphoreSlim _gate = new(0, 1); + public volatile bool IsWaiting; + public readonly List<(int Offset, string Text)> Captured = new(); + + public GodotAdvHost(Main main) => _main = main; + + public void ShowText(int offset, string text) + { + Captured.Add((offset, text)); + _main.CallDeferred("AppendLine", text); + } + + public void WaitForInput() + { + _main.CallDeferred("PageBreak"); + IsWaiting = true; + _gate.Wait(); + IsWaiting = false; + _main.CallDeferred("ClearPage"); + } + + // called from the main thread (click) or the selftest auto-clicker + public void SignalInput() { if (_gate.CurrentCount == 0) _gate.Release(); } + + public void CallScript(long id) { } + public void OnStub(int opcode) { } +} +``` + +- [ ] **Step 2: Replace `godot/Main.cs`** +```csharp +using System.Collections.Generic; +using System.Text.Json; +using System.Threading.Tasks; +using Godot; +using Age.Engine.Sys4; +using Age.Engine.Vm; + +public partial class Main : Godot.Control +{ + private Label _text = null!; + private Label _status = null!; + private VirtualMachine _vm = null!; + private GodotAdvHost _host = null!; + private volatile bool _done; + private bool _ended; + private bool _selftest; + + public override void _Ready() + { + _text = new Label { AutowrapMode = TextServer.AutowrapMode.WordSmart }; + _text.SetAnchorsAndOffsetsPreset(LayoutPreset.FullRect); + _text.OffsetLeft = 40; _text.OffsetTop = 40; _text.OffsetRight = -40; _text.OffsetBottom = -80; + AddChild(_text); + _status = new Label(); + _status.SetAnchorsAndOffsetsPreset(LayoutPreset.BottomWide); + _status.OffsetLeft = 40; _status.OffsetTop = -60; + AddChild(_status); + + _selftest = System.Array.IndexOf(OS.GetCmdlineUserArgs(), "--selftest") >= 0; + + var table = OpcodeTableJson.Load(Paths.OpcodesJson); + var script = Sys4Loader.Load(Paths.Scripts()["SC0000.BIN"], table); + _host = new GodotAdvHost(this); + _vm = new VirtualMachine(script, table, _host); + _ = Task.Run(() => { _vm.Run(); _done = true; }); + + if (_selftest) + _ = Task.Run(async () => { while (!_done) { if (_host.IsWaiting) _host.SignalInput(); await Task.Delay(1); } }); + } + + public override void _Process(double delta) + { + if (_done && !_ended) + { + _ended = true; + ShowEnd(); + if (_selftest) RunSelfTest(); + } + } + + public override void _UnhandledInput(InputEvent e) + { + if (_selftest) return; + if (e.IsActionPressed("ui_accept") || + (e is InputEventMouseButton mb && mb.Pressed && mb.ButtonIndex == MouseButton.Left)) + _host.SignalInput(); + } + + public override void _ExitTree() { _host?.SignalInput(); } + + // ---- UI methods invoked on the main thread via CallDeferred ---- + public void AppendLine(string text) => _text.Text += text + "\n"; + public void PageBreak() => _status.Text = "▼ click / Enter"; + public void ClearPage() { _text.Text = ""; _status.Text = ""; } + public void ShowEnd() => _status.Text = "— end —"; + + private void RunSelfTest() + { + var expected = LoadExpected("SC0000.BIN"); + var actual = _host.Captured.ConvertAll(c => c.Offset); + bool ok = expected != null && actual.Count == expected.Count; + for (int i = 0; ok && i < actual.Count; i++) ok = actual[i] == expected![i]; + if (ok) GD.Print($"SELFTEST OK: {actual.Count} lines match vm0 trace"); + else GD.Print($"SELFTEST FAIL: cs={actual.Count} expected={(expected?.Count.ToString() ?? "n/a")}"); + GetTree().Quit(ok ? 0 : 1); + } + + private static List? LoadExpected(string scene) + { + string p = System.IO.Path.Combine(Paths.Build, "vm0-trace.json"); + if (!System.IO.File.Exists(p)) return null; + using var doc = JsonDocument.Parse(System.IO.File.ReadAllText(p)); + if (!doc.RootElement.TryGetProperty(scene, out var e)) return null; + var list = new List(); + foreach (var x in e.GetProperty("offsets").EnumerateArray()) list.Add(x.GetInt32()); + return list; + } +} +``` + +- [ ] **Step 3: Build and run the self-test — expect FAIL first if anything is off, then PASS** +```bash +GODOT="S:/Godot/Godot_v4.7-stable_mono_win64/Godot_v4.7-stable_mono_win64_console.exe" +dotnet build godot/Himegari.csproj +"$GODOT" --headless --path godot -- --selftest 2>&1 | grep -E 'SELFTEST|error|Exception' +echo "exit: ${PIPESTATUS[0]}" +``` +Expected: `SELFTEST OK: 186 lines match vm0 trace`, exit 0. This exercises the worker thread, the real blocking `SemaphoreSlim` gate (driven by the auto-clicker), `CallDeferred` marshalling, and asserts the emitted text equals the trusted `vm0-trace.json`. If it hangs, the gate isn't being released (check `IsWaiting`/`SignalInput`); if the count differs, the VM/host emitted wrong text (compare with `py -3.11 -X utf8 tools/vm0.py --scene SC0000`). + +- [ ] **Step 4: Regression — A1 engine tests still green** +```bash +dotnet test engine/AgeEngine.sln 2>&1 | grep -E 'Passed!|Failed!' +``` +Expected: 7 passed. + +- [ ] **Step 5: Commit** +```bash +git add godot/GodotAdvHost.cs godot/Main.cs +git commit -m "feat(a2a): worker-thread ADV host + blocking wait-for-input + headless self-test (SELFTEST OK)" +``` + +--- + +## Task 4: Manual visual verification + CJK font + docs + +**Files:** Modify `godot/Main.cs` (best-effort CJK font); Modify `docs/phase-a-slice-plan.md`. + +**Interfaces:** none (visual + docs). + +- [ ] **Step 1: Add a best-effort CJK font so the manual visual isn't tofu** — in `Main._Ready`, after `AddChild(_status);`, insert: +```csharp + foreach (var fp in new[] { "C:/Windows/Fonts/YuGothR.ttc", "C:/Windows/Fonts/msgothic.ttc", "C:/Windows/Fonts/meiryo.ttc" }) + { + if (!System.IO.File.Exists(fp)) continue; + try + { + var ff = new FontFile(); + ff.LoadDynamicFont(fp); + _text.AddThemeFontOverride("font", ff); + _status.AddThemeFontOverride("font", ff); + _text.AddThemeFontSizeOverride("font_size", 22); + break; + } + catch { /* fall back to default font */ } + } +``` +(If `FontFile.LoadDynamicFont` doesn't exist in 4.7, the editor will flag it at build; substitute `ResourceLoader.Load(fp)` — but the self-test does not depend on this, so it never blocks the gate.) + +- [ ] **Step 2: Rebuild + self-test still green (font is headless-safe)** +```bash +GODOT="S:/Godot/Godot_v4.7-stable_mono_win64/Godot_v4.7-stable_mono_win64_console.exe" +dotnet build godot/Himegari.csproj +"$GODOT" --headless --path godot -- --selftest 2>&1 | grep SELFTEST +``` +Expected: `SELFTEST OK: 186 lines match vm0 trace`. + +- [ ] **Step 3: Manual visual check (human)** — run windowed and click through: +```bash +"S:/Godot/Godot_v4.7-stable_mono_win64/Godot_v4.7-stable_mono_win64.exe" --path godot +``` +Confirm by eye: the opening narration appears page by page in Japanese, `▼ click / Enter` shows at each `wait-for-input`, a click/Enter advances, and it ends with `— end —`. (This is the one part only a human verifies.) + +- [ ] **Step 4: Update `docs/phase-a-slice-plan.md`** — under the A2 section add: +``` +### A2a — Interactive dialogue loop ✅ DONE (2026-07-06) +Godot 4.7 (.NET) project in `godot/` referencing `Age.Engine` in-process. VM gained one hook +(`IHost.WaitForInput`, 0x72); suspend/resume via a worker thread + blocking SemaphoreSlim in +`GodotAdvHost`, UI marshalled by `CallDeferred`. Plays SC0000 page-by-page, pauses at wait-for-input, +resumes on click. Headless self-test (`--selftest`) asserts the emitted 186-line sequence == vm0-trace; +A1 engine tests stay 7/7. Next: A2b (background/AGF, voice, choices, call-script/state). +Spec/plan: `docs/superpowers/{specs,plans}/2026-07-06-a2a-godot-dialogue*.md`. +``` + +- [ ] **Step 5: Commit** +```bash +git add godot/Main.cs docs/phase-a-slice-plan.md +git commit -m "feat(a2a): CJK font for the message window; mark A2a done in the slice plan" +``` + +--- + +## Self-Review + +**Spec coverage:** Godot 4.7 .NET project + Age.Engine in-process (Task 2) ✓ · one VM-core change `IHost.WaitForInput`, CaptureHost no-op, trace parity (Task 1) ✓ · background-thread host + blocking `SemaphoreSlim` + `CallDeferred` marshalling (Task 3) ✓ · SC0000 page-by-page, pause at wait-for-input, resume on click (Tasks 3–4) ✓ · headless self-test asserting vs `vm0-trace.json` (Task 3) ✓ · A1 regression 7/7 (Tasks 1,3) ✓ · `Paths` resolves in Godot (Task 2) ✓ · cross-thread visibility via `volatile _done`, `Captured` read only after `_done` (Task 3) ✓ · `_ExitTree` releases the gate (Task 3) ✓ · CJK font for the manual visual (Task 4) ✓. Out-of-scope (bg/voice/choice/call-script) correctly absent. + +**Placeholder scan:** none — every code step is complete. The only non-mechanical step is Task 4 Step 3 (human visual check), which is inherently manual and fully specified. + +**Type consistency:** `IHost.WaitForInput()` (Task 1) is implemented by `CaptureHost` (Task 1), the test `CountHost` (Task 1), and `GodotAdvHost` (Task 3). `GodotAdvHost` calls `_main.CallDeferred("AppendLine"|"PageBreak"|"ClearPage")` — all `public` methods on `Main` (Task 3). `Main` uses `Paths.OpcodesJson`/`Paths.Scripts()`/`Paths.Build`/`Paths.Repo`, `OpcodeTableJson.Load`, `Sys4Loader.Load`, `VirtualMachine(script,table,host)` + `.Run()` — all matching the A1 engine signatures. `_host.Captured`/`IsWaiting`/`SignalInput()` used by `Main` match `GodotAdvHost`.