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.