A console-based incremental/idle game built in C# (.NET 9) where players open boxes to discover items, unlock features, and progress through themed adventures. Uses Spectre.Console for rich terminal rendering and Loreline for interactive narrative scripting.
## Architecture
See [specifications.md](specifications.md) for detailed content organization.
## Key Directories
-`src/OpenTheBox/` — Main game source code
-`content/data/` — JSON data files (items, boxes, crafting recipes)
-`content/adventures/` — Loreline `.lor` adventure scripts (one folder per theme)
-`content/localization/` — Translation files
## Source Code Structure
-`Core/` — Game state, enums, item/character models
-`Core/Enums/` — All enum types (StatType, ResourceType, AdventureTheme, CosmeticSlot, etc.)
Other resources (Health, Mana, Food, etc.) were removed as they had no gameplay impact.
## Ephemeral Items
Fortune cookies (`cookie_fortune`) and music melodies (`music_melody`) are consumed immediately on receipt. They trigger their effects (fortune message, melody playback) but never appear in the player's inventory.
To check game progression balance after modifying loot tables (`content/data/boxes.json`):
```
dotnet test --filter "FullRun_PacingReport" --logger "console;verbosity=detailed"
```
This runs a full simulation (3 seeds: 42, 123, 777) and prints a report showing when each milestone is first reached (UI features, adventures, cosmetics, resources, crafting, lore). Use this to verify that rebalancing changes produce the desired early-game pacing.
Key things to look for:
- **1st Meta UI unlock** should happen before box ~50 for a good early experience
- **1st Adventure** should appear before box ~120
- **All content reachable** within ~1000 boxes (game completion)
- No long gaps between milestones (>100 boxes without progress feels stale)
Weights are in `content/data/boxes.json`. The main generator is `box_of_boxes` (auto-opens, produces the next box). Adjust weights there and in tier boxes (`box_not_great`, `box_ok_tier`, etc.) to tune pacing.
To generate a full report of all items and their usage contexts:
```
dotnet test --filter "ItemUtilitySnapshot" --logger "console;verbosity=detailed"
```
The report is written to `tests/snapshots/item_utility_report.txt`. It shows every item with all its usage contexts (loot, crafting, interactions, etc.) sorted by utility score. Items with no usage are flagged as orphans. In DEBUG mode the snapshot is overwritten; in RELEASE mode the test fails if the content changed.
Generate save files at 9 progression stages for quick visual testing:
```
dotnet test --filter "GenerateSaveSnapshots" --logger "console;verbosity=detailed"
```
This creates `saves/snapshot_1.otb` through `saves/snapshot_9.otb` (from 10 boxes to 2000 boxes opened).
Load a snapshot directly:
```
dotnet run --project src/OpenTheBox -- --snapshot 3
```
Where 1-9 corresponds to: (1) very early, (2) first unlocks, (3) several panels, (4) adventures, (5) crafting, (6) most features, (7) near completion, (8) endgame, (9) post-endgame.
These tests simulate gameplay and capture rendered panel output as plain text for review in the test console. They are the primary way to verify visual rendering without launching the game interactively.
### PlaythroughCapture
Simulates N box openings and renders the full game state panels at each step:
```
dotnet test --filter "PlaythroughCapture" --logger "console;verbosity=detailed"
```
- Runs 2 seeds (42 and 777), 15 steps each
- Shows: portrait, stats, resources, inventory, crafting panels at each step
- Logs all events (items received, UI unlocks, crafting, adventures)
- Useful for checking progressive UI unlock rendering and panel composition
### InventoryRenderCapture
Captures the interactive inventory panel rendering at 5 progression stages (box #20, 50, 100, 200, 500):
```
dotnet test --filter "InventoryRenderCapture" --logger "console;verbosity=detailed"
```
- Shows the inventory table with selection highlight (► indicator on first item)
- Renders the detail panel for each item type present at that stage:
- **Consumable**: effect (+N resource) and "Press Enter to use" prompt
- **LoreFragment**: full lore text displayed in italic
- **Cosmetic**: slot information (Hair, Eyes, Body, etc.)
- **Material**: material type and form (Raw, Ingot, Sheet, etc.)
- Useful after modifying `InventoryPanel.cs`, `RenderDetailPanel()`, or loot tables
### Adding New Render Capture Tests
To capture rendering for a new panel or UI element:
1. Use the helper pattern from `RenderGameStatePanels()` or `InventoryRenderCapture`:
```csharp
var writer = new StringWriter();
var console = AnsiConsole.Create(new AnsiConsoleSettings {
Out = new AnsiConsoleOutput(writer),
Ansi = AnsiSupport.No,
ColorSystem = ColorSystemSupport.NoColors
});
console.Profile.Width = SpectreRenderer.RefWidth;
console.Write(MyPanel.Render(...));
// writer.ToString() contains the plain-text rendering
```
2. Use `--logger "console;verbosity=detailed"` to see `Console.WriteLine()` output in the test runner
3. Tests should `Assert.True(true)` or use lightweight assertions — the goal is visual inspection of output
