openthebox/CLAUDE.md

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 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                    # Default: Terminal.Gui panel layout
dotnet run --project src/OpenTheBox -- --classic       # Classic 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:

   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

Classic Mode

Terminal.Gui panel layout is the default. Use --classic for the old sequential Spectre.Console renderer:

dotnet run --project src/OpenTheBox -- --classic

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)