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

Health, Mana, Food, Stamina, Blood, Gold, Oxygen, Energy

CosmeticSlot

Hair, Eyes, Body, Legs, Arms

Rarity

Common, Uncommon, Rare, Epic, Legendary, Mythic