Samuel Bouchet
83270ed4a0
- Play time tracking: accumulate TotalPlayTime each game loop iteration - Return to menu: split _running into _appRunning/_gameRunning so quit returns to main menu instead of exiting the app - Deterministic meta unlock order: ArrowKeySelection first (accessibility), then TextColors, AutoSave, InventoryPanel, etc. (13-step sequence) - Merge KeyboardShortcuts into ArrowKeySelection - Meta box pity system: guarantee a meta box every 10 openings - Inventory flickering: buffer-based rendering with ANSI cursor repositioning - Non-readable symbols: use ASCII abbreviations instead of emoji in footer - Resource/stats confusion: rename Resource Panel to Characteristics Panel in all user-facing text (EN/FR), update specs and descriptions - Block consumable use before inventory panel unlock - Remove obsolete proposal/suggestion files, clean up Spectre-only renderer
128 lines
6.2 KiB
Markdown
128 lines
6.2 KiB
Markdown
# Open The Box
|
|
|
|
## Project Overview
|
|
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.)
|
|
- `Adventures/` — AdventureEngine (Loreline bridge + custom functions)
|
|
- `Simulation/` — Game engines (BoxEngine, MetaEngine, ResourceEngine, CraftingEngine, GameSimulation)
|
|
- `Rendering/` — IRenderer interface, SpectreRenderer, RenderContext, panel components
|
|
- `Rendering/Panels/` — Individual UI panels (PortraitPanel, ResourcePanel, StatsPanel, etc.)
|
|
- `Data/` — ContentRegistry, ItemDefinition, BoxDefinition data loading
|
|
- `Persistence/` — SaveManager, SaveData (JSON serialization)
|
|
- `Localization/` — LocalizationManager, Locale enum
|
|
|
|
## Build & Run
|
|
```
|
|
dotnet build
|
|
dotnet run --project src/OpenTheBox # Spectre.Console sequential mode
|
|
dotnet run --project src/OpenTheBox -- --snapshot 5 # Load snapshot save #5
|
|
```
|
|
|
|
## Test
|
|
```
|
|
dotnet test
|
|
```
|
|
|
|
## Adventure System
|
|
Adventures use Loreline `.lor` script format. Custom functions available in scripts:
|
|
- Inventory: `grantItem(id, qty)`, `hasItem(id)`, `removeItem(id)`
|
|
- Resources: `hasResource(name, min)`, `getResourceValue(name)`, `addResource(name, amount)`
|
|
- Stats: `hasStat(name, min)`, `getStatValue(name)`
|
|
- Cosmetics: `hasCosmetic(id)`, `hasEquipped(slot, style)`
|
|
- Progression: `hasCompletedAdventure(theme)`, `markSecretBranch(id)`, `hasSecretBranch(id)`, `countSecretBranches()`, `allSecretBranches()`
|
|
|
|
Hints for disabled choices use `|||` separator: `Option text|||Hint text #label if condition`
|
|
|
|
full documentation: https://loreline.app/fr/docs/
|
|
|
|
## Pacing Test
|
|
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.
|
|
|
|
## Save Snapshots (Visual Testing)
|
|
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.
|
|
|
|
## Render Capture Tests (Automated Visual Testing)
|
|
|
|
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
|
|
|
|
## Conventions
|
|
- C# 12 with file-scoped namespaces, primary constructors where appropriate
|
|
- Immutable records for value types, sealed classes for services
|
|
- GameState is mutable, passed by reference to engines
|
|
- All user-facing strings go through LocalizationManager
|
|
- Enum names match JSON string values (PascalCase)
|