docs(ui): document overlay setup and verification
Describe the compact panel, module boundaries, build and installation steps, read-only limits, and manual acceptance checks. Record user-confirmed in-game readability.
This commit is contained in:
0xrsydn
parent
82f2c98e7e
commit
108fd8bf80
1 changed files with 198 additions and 0 deletions
198
ui/JevOverlay/README.md
Normal file
198
ui/JevOverlay/README.md
Normal file
|
|
@ -0,0 +1,198 @@
|
|||
# Jev decision overlay
|
||||
|
||||
A separate, read-only C# mod for Slay the Spire 2. It displays the bot's existing
|
||||
`decisions.jsonl` file inside the game. It does not depend on STS2MCP at runtime.
|
||||
The bot still uses STS2MCP to observe and control the game.
|
||||
|
||||
## UI plan
|
||||
|
||||
The first version uses the compact panel selected during planning:
|
||||
|
||||
```text
|
||||
┌ Jev decisions · read only ───────── [−] ┐
|
||||
│ Read-only log · no new rows for 2s │
|
||||
│ #42 · JEV · combat │
|
||||
│ Session: … │
|
||||
│ Proposed: play_card │
|
||||
│ Parameters: {"card_index": 0} │
|
||||
│ Proposal only; execution not recorded. │
|
||||
│ Reason: … │
|
||||
│ Recorded confidence: 0.81 · 720 ms │
|
||||
│ [Show questions and answers] │
|
||||
├ Recent decisions · select to inspect ──┤
|
||||
│ #42 JEV play_card │
|
||||
│ #41 CODE use_potion │
|
||||
│ #40 FALLBACK end_turn │
|
||||
│ [Follow latest] │
|
||||
└────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- The panel starts at the top right. F8 or the header button collapses it.
|
||||
- Selecting a history row stops automatic selection of new decisions.
|
||||
- `Follow latest` resumes automatic selection.
|
||||
- The details button shows recorded Jev questions, answers, model, and latency.
|
||||
- Text areas and history scroll independently. Evidence uses plain text, not markup.
|
||||
- Source names remain visible. Blue identifies Jev; amber identifies fallback.
|
||||
- Only the panel receives mouse input. There is no full-screen input blocker.
|
||||
- The panel uses Godot's default font and controls. It needs no asset pack.
|
||||
|
||||
This is a desktop mouse-and-keyboard first version. Dragging, position persistence,
|
||||
controller navigation, filtering, and a remappable shortcut are not included.
|
||||
The panel does not pause the game or bot. Collapse it if it covers a game control.
|
||||
|
||||
## Module boundaries
|
||||
|
||||
```text
|
||||
ui/JevOverlay/
|
||||
Mod.cs mod startup, frame callback, background polling
|
||||
Core/
|
||||
OverlayConfig.cs explicit absolute log path
|
||||
LogTail.cs bounded, incremental JSONL reader
|
||||
DecisionHistory.cs session/step joins and display text
|
||||
UI/
|
||||
OverlayView.cs Godot controls and selection state
|
||||
Tests/
|
||||
Program.cs temporary-file integration checks
|
||||
JevOverlay.csproj game-facing assembly
|
||||
JevOverlay.json game mod manifest
|
||||
```
|
||||
|
||||
`Core/` has no Godot or game dependency. `UI/` has no file access or game API calls.
|
||||
`Mod.cs` connects them. All controls are built-in Godot nodes, so the mod needs no
|
||||
Godot editor project, custom node source generator, Harmony patch, or `.pck` file.
|
||||
|
||||
The game mod belongs under `ui/`, not a web `frontend/` directory. Python policy,
|
||||
the runner, and vendored code remain unchanged.
|
||||
|
||||
## Build
|
||||
|
||||
Use a .NET 9 SDK. No NuGet packages are needed; `NuGet.Config` clears package feeds.
|
||||
The game assembly paths are explicit. Builds do not install or start anything.
|
||||
|
||||
If `dotnet` is not on your PATH, a temporary Nix shell is sufficient:
|
||||
|
||||
```sh
|
||||
nix shell nixpkgs#dotnet-sdk_9
|
||||
```
|
||||
|
||||
A project flake and direnv configuration are not required for this version.
|
||||
|
||||
Run these commands from the repository root. On macOS arm64:
|
||||
|
||||
```sh
|
||||
GAME_DATA="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2/SlayTheSpire2.app/Contents/Resources/data_sts2_macos_arm64"
|
||||
dotnet build ui/JevOverlay/JevOverlay.csproj -c Release \
|
||||
-p:STS2GameDataDir="$GAME_DATA"
|
||||
```
|
||||
|
||||
On other platforms, set `STS2GameDataDir` to the installed game's directory
|
||||
containing `sts2.dll` and `GodotSharp.dll`. Use assemblies from the target game build.
|
||||
|
||||
Output: `ui/JevOverlay/bin/Release/net9.0/`.
|
||||
Do not distribute game assemblies with the mod.
|
||||
|
||||
## Offline checks
|
||||
|
||||
The integration checks need .NET 9, but no game installation or connection:
|
||||
|
||||
```sh
|
||||
dotnet run --project ui/JevOverlay/Tests/JevOverlay.Tests.csproj -c Release
|
||||
```
|
||||
|
||||
The checks pass temporary files through the actual reader, history, and text formatter.
|
||||
They cover partial writes, UTF-8, malformed rows, session joins, action errors,
|
||||
rotation, truncation, bounded history, large logs, missing files, and recovery.
|
||||
They do not test Godot rendering or game input behavior.
|
||||
|
||||
## Manual installation
|
||||
|
||||
Do this only when you intend to load the mod. Close the game first.
|
||||
|
||||
1. Build against the installed game assemblies.
|
||||
2. Copy `JevOverlay.dll` and `JevOverlay.json` from the output directory into the game's `mods/` directory.
|
||||
3. Copy `JevOverlay.config.example.json` there as `JevOverlay.conf`.
|
||||
4. Set `log_path` to the absolute path of the bot's decision log.
|
||||
5. Restart the game and enable mods if prompted.
|
||||
|
||||
On macOS, the mod directory is:
|
||||
|
||||
```text
|
||||
SlayTheSpire2.app/Contents/MacOS/mods/
|
||||
```
|
||||
|
||||
Example configuration in `JevOverlay.conf` (JSON content, not a mod manifest):
|
||||
|
||||
```json
|
||||
{
|
||||
"log_path": "/absolute/path/to/sts2-bot/capture/decisions.jsonl"
|
||||
}
|
||||
```
|
||||
|
||||
Do not use `~` or environment variables in this value. For Windows JSON paths,
|
||||
use forward slashes or escape backslashes. Custom `run.py --capture-dir` locations
|
||||
need a matching `log_path`.
|
||||
|
||||
The reader waits if the file does not exist. Missing or invalid configuration
|
||||
appears in the panel. Configuration changes require a full game restart.
|
||||
The mod never creates or changes the configured log file.
|
||||
|
||||
To remove the mod, close the game and remove these three installed files.
|
||||
No saves, capture files, or existing mod files need to change.
|
||||
|
||||
## Log meaning and limits
|
||||
|
||||
The viewer consumes the current `run.py` trace format:
|
||||
|
||||
| Event | Display behavior |
|
||||
| --- | --- |
|
||||
| `decide` | Add a proposed action, identified by session and step |
|
||||
| `action_rejected` | Mark that action request as rejected |
|
||||
| `action_error` | Show the request error; completion remains unknown |
|
||||
| `session_end` | Show the session's stop reason, not action completion |
|
||||
| Model/policy failures, `no_decision` | Show a reader notice |
|
||||
| Other events | Ignore without treating them as malformed |
|
||||
|
||||
The log does not record successful action results or a per-decision dry-run flag.
|
||||
The viewer cannot distinguish an unconfirmed live proposal from a dry-run proposal.
|
||||
It never marks a proposal as executed because the next decision arrived.
|
||||
A transport error does not prove that the game failed to execute a request.
|
||||
|
||||
The policy reason is recorded text, not private model reasoning. A `jev` response
|
||||
can accompany a fallback; the `source` field identifies the actual policy path.
|
||||
Recorded answer gates can differ from policy-specific final gates. Confidence is
|
||||
not proof of correctness. No Jev response means only that none was recorded.
|
||||
|
||||
The status reports file activity, not bot or game liveness. Existing history can
|
||||
be displayed when no bot is running. Sessions remain distinct, including when
|
||||
multiple runners append to the file. The latest appended decision is selected
|
||||
when `Follow latest` is enabled; there is no session filter in this version.
|
||||
|
||||
The reader polls every 500 ms on one background worker. It reads at most 256 KiB
|
||||
per poll and starts within the last 256 KiB of an existing log. It keeps at most
|
||||
100 decisions and at most 128 KiB per incomplete line. Oversized or malformed
|
||||
lines are skipped. Display text is limited to 16,000 characters per text area.
|
||||
A displayed decision can leave history while it is selected.
|
||||
|
||||
Truncation and replacement are detected by file length, a prefix, and a checkpoint
|
||||
near the last read offset. A replacement with identical sampled bytes and no
|
||||
length decrease cannot always be distinguished from an append. This viewer is
|
||||
not a durable audit reader. Concurrent writers must still produce complete JSONL
|
||||
rows; the viewer cannot repair interleaved writes.
|
||||
|
||||
## In-game acceptance check — requires explicit approval
|
||||
|
||||
No live game action or model call is needed to validate the panel itself. Point
|
||||
`log_path` at a disposable JSONL file and use synthetic records:
|
||||
|
||||
1. Start the game with the mod installed and check the initial panel.
|
||||
2. Append a `decide` record with a session, step, and action.
|
||||
3. Confirm the panel updates and does not mark the proposal as executed.
|
||||
4. Expand the evidence area and select an older decision.
|
||||
5. Append another record and confirm the older selection remains selected.
|
||||
6. Test F8, collapse, scrolling, resizing, and clicks outside the panel.
|
||||
7. Switch game scenes and confirm there is exactly one panel.
|
||||
8. Remove or truncate the disposable file and confirm reader recovery.
|
||||
|
||||
The user confirmed that the installed panel appears and is readable in-game.
|
||||
Input routing, scene persistence, and the remaining acceptance steps are not yet
|
||||
verified. Building against game assemblies is not a substitute for these checks.
|
||||
Loading…
Add table
Add a link
Reference in a new issue