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, Blood 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: Blood)
└── 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 ─┤
  │              (Gold, Blood 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)

Blood, Gold Only resources with actual adventure gates are kept. Blood 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, Blood)
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.