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`, `AllResourcesVisible`

### `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` / `resourceValue` — Resource modification
- `metaUnlock` — UI feature to unlock
- `workstationType` — Workstation blueprint

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

## Adventures (`content/adventures/`)

### Folder Structure
```
content/adventures/
├── space/          — Sci-fi theme (Key resource: Oxygen)
├── medieval/       — Fantasy theme (Key resources: Mana, Stamina)
├── pirate/         — Pirate theme (Key resources: Gold, Stamina)
├── contemporary/   — Modern urban theme (Key resources: Energy, Gold)
├── sentimental/    — Romance theme (Key resources: Health, Mana)
├── prehistoric/    — Stone age theme (Key resources: Food, Stamina)
├── cosmic/         — Cosmic/divine theme (Key resources: Mana, Energy)
├── microscopic/    — Micro-world theme (Key resources: Energy, Oxygen)
├── darkfantasy/    — Gothic horror theme (Key resources: Blood, Mana)
└── 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("Blood", 20)`        | `darkfantasy_blood_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 ─┤
  │                                         │
  │         ┌───────────────────────────────┘
  │         ▼
  │    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)
Health, Mana, Food, Stamina, Blood, Gold, Oxygen, Energy
Note: internally called "Resource" in code, displayed as "Characteristics" to the player.
Characteristics represent the character's attributes with current/max values (e.g., Health 40/100).
They are implicitly unlocked when the player receives an item referencing that resource type (e.g., a Health Potion reveals Health).

### 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 (health, mana, etc.)
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.