openthebox/specifications.md

# Open The Box — Content Specifications

## Data Files (`content/data/`)

### `boxes.json`
Array of box definitions. Each box has:
- `id` — Unique identifier (e.g., `box_common`, `box_adventure`, `box_endgame`)
- `nameKey`, `descriptionKey` — Localization keys
- `rarity` — Common, Uncommon, Rare, Epic, Legendary, Mythic
- `isAutoOpen` — If true, box opens immediately when obtained
- `lootTable`:
  - `guaranteedRolls` — Array of item IDs always given
  - `rollCount` — Number of random rolls
  - `entries` — Weighted loot entries with optional `condition`:
    - `condition.type`: `HasItem`, `HasNotItem`, `ResourceAbove`, `ResourceBelow`, `BoxesOpenedAbove`, `HasUIFeature`, `HasWorkstation`, `HasAdventure`, `HasCosmetic`

### `items.json`
Array of item definitions. Categories: Token, Consumable, Material, Cosmetic, Meta, Box.
Special properties:
- `adventureTheme` — Links token to an adventure theme
- `cosmeticSlot` / `cosmeticValue` — Cosmetic equipment data
- `statType` / `statValue` — Stat modification
- `resourceType` / `resourceAmount` — Resource modification (Gold, Ink only)
- `metaUnlock` — UI feature to unlock
- `workstationType` — Workstation blueprint

### `recipes.json`
Crafting recipes with inputs, outputs, and workstation requirements.

## Adventures (`content/adventures/`)

### Folder Structure
```
content/adventures/
├── space/          — Sci-fi theme
├── medieval/       — Fantasy theme
├── pirate/         — Pirate theme
├── contemporary/   — Modern urban theme (Key resource: Gold)
├── sentimental/    — Romance theme
├── prehistoric/    — Stone age theme
├── cosmic/         — Cosmic/divine theme
├── microscopic/    — Micro-world theme
├── darkfantasy/    — Gothic horror theme (Key resource: Ink)
└── destiny/        — Final adventure (acknowledges all other adventures)
```

Each folder contains:
- `intro.lor` — Main adventure script (English)
- `intro.fr.lor` — French translation
- (Other locales as needed)

### Secret Branches
Each regular adventure (not Destiny) has ONE secret branch gated by stats, resources, or cosmetics:

| Adventure    | Condition                          | Branch ID                    |
|-------------|------------------------------------|-----------------------------|
| Space       | `hasStat("Wisdom", 10)`           | `space_box_whisperer`       |
| Medieval    | `hasStat("Charisma", 10)`         | `medieval_dragon_charmer`   |
| Pirate      | `hasEquipped("legs", "PegLeg")`   | `pirate_one_of_us`         |
| Contemporary| `hasResource("Gold", 30)`          | `contemporary_vip`          |
| Sentimental | `hasStat("Wisdom", 10)`           | `sentimental_true_sight`    |
| Prehistoric | `hasStat("Strength", 10)`         | `prehistoric_champion`      |
| Cosmic      | `hasStat("Intelligence", 10)`     | `cosmic_enlightened`        |
| Microscopic | `hasStat("Dexterity", 10)`        | `microscopic_surgeon`       |
| DarkFantasy | `hasResource("Ink", 20)`        | `darkfantasy_ink_communion`|

### Destiny Adventure (Final)
- Triggered by `destiny_token` from `box_endgame`
- Acknowledges completed adventures and found secret branches
- Has 4 ending tiers based on secret branches found (0, 1-4, 5-8, all 9)
- Ultimate ending grants `destiny_star` item

## Game Systems Interaction Map

```
Boxes ──► Items ──► Inventory
  │         │          │
  │         ├──► Meta Unlocks (UI features, panels)
  │         ├──► Adventure Tokens ──► Adventures
  │         ├──► Cosmetics ──► Appearance ──┐
  │         ├──► Stat Items ──► Stats ──────┤
  │         └──► Consumables ──► Resources ─┤
  │              (Gold, Ink only)           │
  │                                         │
  │         ┌───────────────────────────────┘
  │         ▼
  │    Adventure Conditions (gate secret branches)
  │         │
  │         ▼
  │    Secret Branches ──► Destiny Adventure (final acknowledgment)
  │
  └──► Crafting (materials consumed, items produced)
```

## Localization (`content/localization/`)
- Key-value JSON files per locale
- Locales: EN (default), FR
- Adventure translations use Loreline's `#label` system with separate `.{locale}.lor` files. See https://loreline.app/fr/docs/localization/ if needed

## Enums Reference

### AdventureTheme
Space, Medieval, Pirate, Contemporary, Sentimental, Prehistoric, Cosmic, Microscopic, DarkFantasy, Destiny

### StatType
Strength, Intelligence, Luck, Charisma, Dexterity, Wisdom

### ResourceType (Characteristics)
Ink, Gold
Only resources with actual adventure gates are kept. Ink gates the DarkFantasy secret branch (≥20), Gold gates the Contemporary secret branch (≥30).
Resources are displayed as "Characteristics" to the player with current/max values (e.g., Gold 50/100).

### CosmeticSlot
Hair, Eyes, Body, Legs, Arms

### Rarity
Common, Uncommon, Rare, Epic, Legendary, Mythic

## Meta Unlock Order (Deterministic)

UI features are unlocked in a fixed order regardless of which meta box drops. The loot tables control *when* a meta item drops (via conditions/weights), but *which* feature is unlocked is always the next in this sequence:

1. **ArrowKeySelection** — Arrow key + keyboard navigation (first for accessibility)
2. **TextColors** — Basic 8-color ANSI text
3. **AutoSave** — Automatic saving
4. **InventoryPanel** — Interactive inventory table
5. **StatsPanel** — Progression stats and character attributes
6. **ResourcePanel** — Characteristics bars (Gold, Ink)
7. **PortraitPanel** — ASCII art portrait
8. **ChatPanel** — Event log panel
9. **ExtendedColors** — 256-color palette
10. **BoxAnimation** — Animated box openings
11. **CraftingPanel** — Crafting system
12. **CompletionTracker** — Completion percentage
13. **FullLayout** — Multi-panel grid layout

Note: KeyboardShortcuts is merged into ArrowKeySelection.

### Pity System
If the player opens 10 boxes without receiving a meta box, one is guaranteed on the next opening.

## Item Utility Audit

Run the snapshot test to generate a full item utility report:
```
dotnet test --filter "ItemUtilitySnapshot" --logger "console;verbosity=detailed"
```
The report is written to `tests/snapshots/item_utility_report.txt` and shows every item with its usage contexts (loot source, crafting, interactions, adventure gates, etc.). Items with no usage context are flagged as orphans.