docs(phase-b): design — cross-scene state (persistent globals + runner)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
gamer147
@@ -0,0 +1,105 @@
|
||||
# Design: Phase B — Cross-Scene State (persistent globals + a state-carrying runner)
|
||||
|
||||
Status: **approved-by-delegation (owner asleep; autonomous Phase B mandate)** · Date: 2026-07-07
|
||||
Related: `docs/remake-architecture-and-roadmap.md` (Phase B), `docs/phase-a-slice-plan.md`
|
||||
(A2b-Geometry — the state-divergence finding that motivates this), `engine/Age.Engine`
|
||||
(`Vm/VirtualMachine.cs`), `engine/Age.Cli/Program.cs`.
|
||||
|
||||
## Problem / goal
|
||||
|
||||
Every VM run today is a **single scene in isolation** with an empty global bank. But the session's
|
||||
biggest finding is that most divergence from the real game — the bg/sprite geometry drift, the 12
|
||||
state-gated EMPTY scenes, Lily's form-gated voices — is **state divergence**: the real game carries a
|
||||
persistent global store across scenes (boot init → scene → scene …), so scenes take branches our
|
||||
fresh-state VM never reaches.
|
||||
|
||||
The foundational Frida-free step is therefore **cross-scene state**: a persistent global bank that
|
||||
survives scene boundaries, seedable up front, so we can (a) run a boot script then a scene with its
|
||||
state, (b) seed known flags (chapter, form) and observe scenes branch correctly, and (c) later drive a
|
||||
real multi-scene sequence. This is pure bytecode execution — no Frida, no packer, no unsolved
|
||||
call-script registry (the scene *sequence* is supplied; auto-chaining via SCJUMP is a later slice).
|
||||
|
||||
**Goal:** a reusable `GameSession` in `Age.Engine` that owns a persistent global store and runs scenes
|
||||
into it, plus an `Age.Cli play` mode that runs a supplied scene sequence carrying state (with optional
|
||||
seeds) and dumps the combined dialogue. Headless, deterministic, unit-tested.
|
||||
|
||||
## Scope
|
||||
|
||||
**In:**
|
||||
- `Age.Engine/Vm/GameSession.cs` — persistent `Globals`/`GlobalStrings`; `RunScene(script, host)` seeds
|
||||
a fresh `VirtualMachine` from session state, runs it, and merges the final state back. Returns a small
|
||||
result (emitted lines, halt reason, steps).
|
||||
- Seeding API: `Seed(int addr, long value)` / `SeedString(int addr, string)`.
|
||||
- `Age.Cli play <SCENE...> [0xADDR=VAL ...]` — run a sequence carrying state; print per-scene dialogue
|
||||
counts + halt, and the combined emitted line count. Reuses `CaptureHost`.
|
||||
- Unit tests: state persists A→B; SC0000 via `GameSession` is byte-identical to a single run (186 lines);
|
||||
a seeded global is visible to the scene and changes an observable (branch/emit).
|
||||
|
||||
**Out (later slices):** SCJUMP-driven auto-sequencing, `call-script` id→code resolution, the input/
|
||||
hotspot model (interactive/EMPTY scenes), save-file (de)serialization of the store, Godot wiring of
|
||||
`GameSession`. This slice is the state *substrate*; those consume it.
|
||||
|
||||
## Architecture
|
||||
|
||||
### `Age.Engine/Vm/GameSession.cs` (new)
|
||||
```csharp
|
||||
public sealed class GameSession
|
||||
{
|
||||
public Dictionary<int, long> Globals { get; } = new();
|
||||
public Dictionary<int, string> GlobalStrings { get; } = new();
|
||||
|
||||
public void Seed(int addr, long value) => Globals[addr] = value;
|
||||
public void SeedString(int addr, string value)=> GlobalStrings[addr] = value;
|
||||
|
||||
public SceneResult RunScene(Script script, OpcodeTable table, IHost host, VmOptions? o = null)
|
||||
{
|
||||
var vm = new VirtualMachine(script, table, host, o);
|
||||
foreach (var kv in Globals) vm.Globals[kv.Key] = kv.Value;
|
||||
foreach (var kv in GlobalStrings) vm.GlobalStrings[kv.Key] = kv.Value;
|
||||
vm.Run();
|
||||
// merge final state back (globals are one flat space; last write wins — matches the engine)
|
||||
foreach (var kv in vm.Globals) Globals[kv.Key] = kv.Value;
|
||||
foreach (var kv in vm.GlobalStrings) GlobalStrings[kv.Key] = kv.Value;
|
||||
return new SceneResult(vm.Emitted.ToList(), vm.HaltReason, vm.Steps);
|
||||
}
|
||||
}
|
||||
public sealed record SceneResult(IReadOnlyList<(int Offset, string Text)> Emitted, string? Halt, long Steps);
|
||||
```
|
||||
Seam rule preserved: `GameSession` lives in `Vm`, references only `Model`/`Hosting` (never `Sys4`). The
|
||||
VM itself is unchanged (its `Globals`/`GlobalStrings` are already public and pre-seedable — the `audio`/
|
||||
`gfx` CLI modes already write them before `Run`), so **trace/selftest parity is untouched**.
|
||||
|
||||
### `Age.Cli play` (Program.cs)
|
||||
`play SC0000.BIN SC0030.BIN 0xa57=1` → build a `GameSession`, apply seeds, `RunScene` each in order
|
||||
through a `CaptureHost`, print `scene: N lines (halt …)` per scene and the carried global count. Mirrors
|
||||
the existing `audio`/`gfx` seed-arg parsing.
|
||||
|
||||
## Data flow
|
||||
```
|
||||
seeds ──► GameSession.Globals ──►┐
|
||||
├─ RunScene(A): VM seeded from session → runs → merge back ─► session grows
|
||||
scene A ──────────────────────►─┘
|
||||
scene B ──► RunScene(B): VM seeded from session (now includes A's writes) → runs → merge back
|
||||
```
|
||||
|
||||
## Testing / verification
|
||||
1. **Persistence (synthetic):** script A = `mov (global-int 0x5000) 0x2a; exit`; script B = `show-text`
|
||||
guarded by `jcc (global-int 0x5000)`… — simplest: A sets `G[0x5000]=42`, then assert
|
||||
`session.Globals[0x5000]==42` after `RunScene(A)`, and that `RunScene(B)` sees it. Build scripts
|
||||
in-memory (as `TextureGeometryTests` does) so it's deterministic and needs no corpus.
|
||||
2. **Parity:** `GameSession.RunScene(SC0000)` emits exactly the 186 offsets of the single-run trace
|
||||
(`build/vm0-trace.json`) — proves the session wrapper doesn't perturb execution.
|
||||
3. **Seeding changes behavior:** seed `G[0xa57]=1` (Lily form A) before SC0000 and assert the emitted
|
||||
set differs from the unseeded run (the form-gated lines now execute) — the headless analogue of the
|
||||
audio finding, and the first concrete demonstration that state seeding works end-to-end.
|
||||
4. **CLI smoke:** `Age.Cli play SC0000.BIN` runs and prints a sane summary; engine suite stays green.
|
||||
|
||||
## Risks / open questions
|
||||
- **Merge semantics:** globals are one flat space; merging the VM's full final map back into the session
|
||||
(last-write-wins) matches the engine's single global bank. Local frames are per-call and correctly do
|
||||
NOT persist (they live in the VM, not the session). ✓
|
||||
- **Which globals are "state" vs scratch:** we carry *all* of them (the engine does). Transient scratch
|
||||
registers (e.g. `G[0x62424]`) get overwritten next use — harmless. No filtering needed.
|
||||
- **Scene sequence source:** supplied by the caller here; SCJUMP-driven sequencing is a later slice and
|
||||
does not block this substrate.
|
||||
- **No divergence risk to A1/A2:** the VM is untouched; parity test (2) is the guardrail.
|
||||
Reference in New Issue
Block a user