# Design: A2a — Interactive Dialogue Loop (Godot + Age.Engine)

Status: **approved (design)** · Date: 2026-07-06
Related: `docs/phase-a-slice-plan.md` (A2), `docs/remake-architecture-and-roadmap.md`, the A1 engine
(`engine/Age.Engine`), `docs/superpowers/specs/2026-07-06-a1-csharp-vm-design.md`.

## Problem / goal

A1 delivered a headless C# VM byte-identical to `vm0.py`. A2a is the first *presentation* slice: stand up
a **Godot 4.7 (.NET)** project that references `Age.Engine` in-process, make the VM **suspendable**, and
play one CLEAN scene (**SC0000**, 186 lines) as a message window whose text **pauses at `wait-for-input`
(0x72) and resumes on a click**. It proves the two load-bearing A2 unknowns — (1) Godot .NET can host and
run our engine in-process, and (2) the suspend/resume interactive loop — with the validated VM core left
essentially unchanged. Background art, voice, choices, and `call-script`/state are **A2b**.

## Non-goals (→ A2b / later)

Background/AGF pipeline, `play-voice`/`play-bgm`, choices (buttons → VM), `call-script`/state seeding to
enter richer scenes, `set-font`, remaining draw/audio effectful ops, exported-build data packaging, UX
polish (text speed, backlog, skip). A2a is the interactive VM↔Godot loop only.

## Prerequisites (verified 2026-07-06)

- Godot **4.7-stable mono** at `S:/Godot/Godot_v4.7-stable_mono_win64/` (`GodotSharp/` present;
  `--version` → `4.7.stable.mono.official`). Console exe used for headless runs.
- `build/opcodes.json` and `build/vm0-trace.json` exist (from A1); `../extracted/DATA1/SC0000.BIN` present.
- `Age.Engine` targets `net8.0` (Godot 4.7 .NET also targets .NET 8) → compatible.

## Architecture

```
godot/                              Godot 4.7 .NET project (config_version=5)
  project.godot                     main scene = Main.tscn; dotnet/project config
  Himegari.csproj                   Godot.NET.Sdk; net8.0; ProjectReference ../engine/Age.Engine
  Main.tscn                         Control(root) > RichTextLabel + Label(status)
  Main.cs                           owns the VM worker thread + UI methods
  GodotAdvHost.cs : Age.Engine.Hosting.IHost   interactive backend
```

- **In-process, no IPC:** the Godot game assembly references `engine/Age.Engine/Age.Engine.csproj`
  directly. Data is resolved by the existing `Age.Engine.Sys4.Paths` (walks up to `age-reimpl/`; the
  `godot/` project is inside it, so `Paths.OpcodesJson` / `Paths.Scripts()` work in the editor and in
  headless dev runs). *(Exported-build data packaging is A2b/C.)*

### One VM-core change (kept minimal to preserve trace parity)

Add to `IHost`: `void WaitForInput();`. In `VirtualMachine.Step`, split `wait-for-input` out of the
no-op group:
```csharp
case "wait-for-input": _host.WaitForInput(); return pc + 1;
```
`CaptureHost.WaitForInput()` is a **no-op**, so `Steps`/`Emitted` are unchanged and **A1's trace-diff and
RECOVER stay green** (calling an empty method changes nothing the trace observes). This is the entire core
change; all suspend/resume logic lives in `GodotAdvHost`.

### Threading model (background thread + blocking host)

`Main.cs` runs `vm.Run()` on a `Task` (worker thread). Ownership is clean: the worker owns VM state, the
main thread owns UI, and `WaitForInput` is the only rendezvous.

`GodotAdvHost` (constructed with the `Main` node and an `autoAdvance` flag):
- `ShowText(off, text)` → `main.CallDeferred(Main.MethodName.AppendLine, text)` (append on main thread);
  also record `(off, text)` into a `Captured` list (for the self-test).
- `WaitForInput()` → if `autoAdvance` return immediately; else `main.CallDeferred(Main.MethodName.PageBreak)`
  then `_gate.Wait()` (a `SemaphoreSlim(0,1)`); on resume, `main.CallDeferred(Main.MethodName.ClearPage)`.
- `SignalInput()` → `_gate.Release()` (called from the main thread on click).
- `CallScript`/`OnStub` → record/ignore (A2a stubs them like A1).

`Main.cs`:
- `_Ready()`: parse `OS.GetCmdlineUserArgs()` for `--selftest`; load `OpcodeTable` + SC0000 `Script` via
  `Paths`; build `GodotAdvHost(this, autoAdvance: selftest)`; start `_task = Task.Run(() => { _vm.Run(); _done = true; })`.
- `_UnhandledInput(e)`: on `ui_accept` or a left mouse click, `_host.SignalInput()`.
- UI methods (called via `CallDeferred`): `AppendLine(string)` appends to the `RichTextLabel`;
  `PageBreak()` shows a "▼ click" indicator; `ClearPage()` clears the label; `ShowEnd()` shows "— end —".
- `_Process()`: when `_done` flips true, call `ShowEnd()` once; in **selftest** mode, compare
  `_host.Captured` offsets to the expected SC0000 sequence and `GetTree().Quit(exitCode)`.

## Data flow (one page)

worker `vm.Run()` → N× `ShowText` (each `CallDeferred(AppendLine)`) → `wait-for-input` →
`WaitForInput()` shows ▼ and blocks the worker → user clicks → `_UnhandledInput` → `SignalInput()`
releases → worker clears the page and continues → … → `exit` → `_done` → `ShowEnd()`.

## Validation

- **Headless self-test (auto-verifiable, the A2a gate):** run
  `Godot_v4.7-stable_mono_win64_console.exe --headless --path godot -- --selftest`. `Main` runs SC0000 on
  the worker thread with `autoAdvance` (WaitForInput returns immediately), still marshalling `AppendLine`
  via `CallDeferred` (so the thread + deferred path is exercised headlessly), waits for `_done`, then
  asserts `_host.Captured` offsets equal `build/vm0-trace.json["SC0000.BIN"]["offsets"]` (186 lines) and
  quits `0`/`1`, printing `SELFTEST OK`/`SELFTEST FAIL: …`. This proves Godot .NET hosts Age.Engine, the
  worker-thread + `CallDeferred` marshalling works, and the emitted text matches the trusted oracle.
- **A1 regression:** `dotnet test engine/AgeEngine.sln` → still 6/6 (WaitForInput no-op in CaptureHost).
- **Manual visual (human):** open `godot/` in the Godot 4.7 .NET editor (or run non-headless) and click
  through SC0000 — text appears page by page, pauses at ▼, advances on click, ends cleanly. The
  suspend/resume timing under a real window is the part only a human can confirm.

## Risks

- **Godot .NET project scaffolding by hand** — `project.godot` + `.csproj` must be correct for
  `godot --headless` to build the C# assembly. Mitigation: generate via the Godot editor's C# setup if the
  hand-authored files fail to build; the plan verifies with a headless build before wiring logic.
- **`CallDeferred` method binding** — deferred calls target `Main` methods by name; they must be
  `public` (or `[Signal]`/source-gen `MethodName`) on the `Node`. Verified by the self-test.
- **Headless drivers** — use `--headless` (no audio/video driver needed); the self-test avoids real input.
- **Thread vs Godot lifetime** — if the scene exits while the worker blocks in `WaitForInput`, release the
  gate in `_ExitTree()` and guard `CallDeferred` after tree exit. Covered in the plan.
- **Cross-thread visibility** — `_done` is `volatile` (worker writes, `_Process` reads); `_host.Captured`
  is only read after `_done` is observed true, so the completed write is safely published. No lock needed
  beyond that ordering.
- **`Paths` in an exported build** — dev-only for A2a (resolves via the repo tree); packaging is deferred.

## Out of scope (A2b and beyond)

Background via `AGF2BMP2AGF.exe` → texture, `play-voice`/`play-bgm` (OGG), choices → UI buttons feeding VM
globals, `call-script`/state seeding to unlock richer/EMPTY scenes, `set-font`, remaining draw ops,
export packaging, and ADV UX (text speed, backlog, auto/skip).