2026-03-11 17:50:37 +01:00
# 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` :
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
- `condition.type` : `HasItem` , `HasNotItem` , `ResourceAbove` , `ResourceBelow` , `BoxesOpenedAbove` , `HasUIFeature` , `HasWorkstation` , `HasAdventure` , `HasCosmetic`
2026-03-11 17:50:37 +01:00
### `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
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
- `resourceType` / `resourceAmount` — Resource modification (Gold, Blood only)
2026-03-11 17:50:37 +01:00
- `metaUnlock` — UI feature to unlock
- `workstationType` — Workstation blueprint
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
### `recipes.json`
Crafting recipes with inputs, outputs, and workstation requirements.
2026-03-11 17:50:37 +01:00
## Adventures (`content/adventures/`)
### Folder Structure
```
content/adventures/
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
├── 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)
2026-03-11 17:50:37 +01:00
└── 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 ─┤
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
│ (Gold, Blood only) │
2026-03-11 17:50:37 +01:00
│ │
│ ┌───────────────────────────────┘
│ ▼
│ 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
Fix adventure parsing, add French accents, fix cosmetic translation bug
- Fix Loreline parsing: escape quotes in dialogue, remove [if] bracket
syntax, remove # in text conflicting with tags
- Add French accents to all 9 .fr.lor translation files (hundreds of fixes)
- Fix cosmetic equip display: use item nameKey lookup instead of
constructing key from cosmeticValue (fixes StardustLegendary MISSING)
- Deduplicate cosmetics in appearance menu
- Localize all hardcoded strings (welcome, inventory, adventure, cosmetic)
- Add new tests: Loreline parsing (19), cosmetic slot keys, slot+value
uniqueness (302 total, 0 failures)
2026-03-11 20:40:07 +01:00
- Adventure translations use Loreline's `#label` system with separate `.{locale}.lor` files. See https://loreline.app/fr/docs/localization/ if needed
2026-03-11 17:50:37 +01:00
## Enums Reference
### AdventureTheme
Space, Medieval, Pirate, Contemporary, Sentimental, Prehistoric, Cosmic, Microscopic, DarkFantasy, Destiny
### StatType
Strength, Intelligence, Luck, Charisma, Dexterity, Wisdom
2026-03-14 20:21:18 +01:00
### ResourceType (Characteristics)
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
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).
2026-03-11 17:50:37 +01:00
### CosmeticSlot
Hair, Eyes, Body, Legs, Arms
### Rarity
Common, Uncommon, Rare, Epic, Legendary, Mythic
2026-03-14 20:21:18 +01:00
## 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
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
6. **ResourcePanel** — Characteristics bars (Gold, Blood)
2026-03-14 20:21:18 +01:00
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.
Remove 6 unused resource types and add item utility snapshot test
Strip Health, Mana, Food, Stamina, Oxygen, Energy — only Gold and Blood
remain as they serve as adventure gates (Contemporary ≥30, DarkFantasy ≥20).
Remove 22 orphaned items, 5 recipes, and the AlchemyTable workstation.
Replace energy_cell in rocket_boots recipe with cosmic_shard.
Change box_endgame condition from AllResourcesVisible to BoxesOpenedAbove:500.
Add ItemUtilitySnapshot test that maps every item to its usage contexts
(loot sources, crafting, interactions, adventures) and generates a report.
DEBUG overwrites the snapshot; RELEASE asserts no changes.
Update specifications.md and CLAUDE.md to reflect resource cleanup.
Remove obsolete bugs.md and refactoring_plan.md.
2026-03-15 15:05:45 +01:00
## 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.
