i-want-to-heal/docs/gearing-system.md

# Gearing System

## Goal

Gearing should move from boss-specific multi-item drop tables to one clear currency loop:

1. Kill bosses.
2. Earn boss coins.
3. Craft gear with those coins.
4. Upgrade that boss gear into the next item-level tier with higher-rarity coins.

This keeps boss loot readable, removes low-percentage frustration, and makes every boss kill progress a targeted gear goal.

## Coin Tiers

Coins are component items. Each coin is tied to a boss source and an item-level tier.

| Item Level | Display Color | Rarity Key | Example |
| --- | --- | --- | --- |
| 5 | White | common | Bulldrome Coin |
| 10 | Green | uncommon | Green Bulldrome Coin |
| 15 | Blue | rare | Blue Bulldrome Coin |
| 20 | Purple | epic | Purple Bulldrome Coin |
| 25 | Orange | legendary | Orange Bulldrome Coin |

Implementation note: the current TypeScript rarity union supports `common`, `uncommon`, `rare`, and `epic`. Orange needs a new rarity key, recommended as `legendary`, plus UI color styling.

## Boss Loot

Each boss has one loot roll.

For now, each successful boss loot roll awards 1 to 3 coins:

| Roll Result | Coins Awarded |
| --- | --- |
| Low roll | 1 coin |
| Normal roll | 2 coins |
| High roll | 3 coins |

Recommended weighting:

| Coins | Chance |
| --- | --- |
| 1 | 50% |
| 2 | 35% |
| 3 | 15% |

The coin source comes from the defeated boss. Bulldrome drops Bulldrome coins, Rathian drops Rathian coins, and so on.

The coin tier comes from content difficulty or roguelike depth:

| Source | Coin Tier |
| --- | --- |
| Item level 5 content | White level 5 coins |
| Item level 10 content | Green level 10 coins |
| Item level 15 content | Blue level 15 coins |
| Item level 20 content | Purple level 20 coins |
| Item level 25 content | Orange level 25 coins |

## Crafting Costs

Gear is crafted with boss coins from the same boss and item-level tier.

| Gear Item Level | Cost |
| --- | --- |
| 5 | 5 white boss coins |
| 10 | 10 green boss coins |
| 15 | 15 blue boss coins |
| 20 | 20 purple boss coins |
| 25 | 25 orange boss coins |

Example:

- Bulldrome item-level 5 helmet costs 5 white Bulldrome coins.
- Bulldrome item-level 10 helmet costs 10 green Bulldrome coins.
- Rathian item-level 20 gloves cost 20 purple Rathian coins.

## Gear Upgrades

Crafting can create gear directly, but upgrades should become the preferred long-term path.

Upgrade rule:

- Existing boss gear upgrades into the next item-level version of the same boss gear.
- Upgrade cost uses coins from the next tier.
- Required coin quantity equals the target item level.

Examples:

| Upgrade | Cost |
| --- | --- |
| Bulldrome item level 5 gear -> Bulldrome item level 10 gear | 10 green Bulldrome coins |
| Bulldrome item level 10 gear -> Bulldrome item level 15 gear | 15 blue Bulldrome coins |
| Bulldrome item level 15 gear -> Bulldrome item level 20 gear | 20 purple Bulldrome coins |
| Bulldrome item level 20 gear -> Bulldrome item level 25 gear | 25 orange Bulldrome coins |

Upgrade should consume the old item and award the upgraded item. This avoids duplicate clutter and keeps equipment identity clear.

## Roguelike Loot

Roguelike bosses should award coins when defeated, using the same 1 to 3 coin roll.

Roguelike coin tier should scale by wave band:

| Waves | Coin Tier |
| --- | --- |
| 1-4 | Level 5 white coins |
| 5-9 | Level 10 green coins |
| 10-14 | Level 15 blue coins |
| 15-19 | Level 20 purple coins |
| 20+ | Level 25 orange coins |

Boss identity can be handled two ways:

1. Boss-based coins: use the actual boss template selected for that roguelike boss.
2. Roguelike coins: use a generic roguelike coin per tier.

Recommended first pass: boss-based coins. It reuses the same crafting economy as dungeons and makes roguelike runs feel connected to the main gear chase.

## Roguelike Checkpoints

Checkpoints should unlock every 5 waves.

| Highest Cleared Wave | Future Start Wave |
| --- | --- |
| 0-4 | 1 |
| 5-9 | 5 |
| 10-14 | 10 |
| 15-19 | 15 |
| 20+ | Highest unlocked 5-wave checkpoint |

Checkpoint rule:

- Unlock a checkpoint after clearing its boss band.
- Starting from a checkpoint begins at that wave band with matching coin tier.
- Runs should still record leaderboard progress from the selected start wave so full runs and checkpoint runs can be ranked separately later.

Current implementation note: the roguelike screen always starts at stage 1 and only awards XP per boss. Checkpoints need saved character progress and a start-wave selector.

## Current Code Fit

The existing system already has most of the required foundation:

- `items.slot = 'component'` can represent coins.
- `character_inventory.quantity` already stacks components.
- `crafting_recipes` and `crafting_recipe_components` already support coin costs.
- `encounter_loot_rolls` and `encounter_loot_roll_items` already persist retry-safe loot awards.
- `completeRoguelike` is already called after each roguelike boss kill for XP, so coin awards can attach to that same flow.

Needed changes:

- Replace current 4-component boss drop tables with one boss coin per boss per tier.
- Change boss loot roll count from multiple chance slots to one 1-3 coin roll.
- Add orange/legendary rarity support.
- Add upgrade recipes or a dedicated upgrade endpoint.
- Add roguelike boss coin awards.
- Add roguelike checkpoint persistence and start-wave selection.
- Export updated offline starter data after seed changes.

## Suggestions

Use guaranteed coin drops for now. One to three coins per boss gives steady progress and makes craft timing easy to understand.

Keep coins boss-specific, not slot-specific. Slot-specific components add complexity without much decision value.

Use upgrade-first UI. Show the next upgrade for equipped gear before showing the full crafting catalog.

Keep direct crafting and upgrading at the same coin cost for the target tier. Direct crafting helps new slots catch up; upgrading preserves boss gear identity.

Add a pity floor only if needed later. If boss kills always award coins, the system already has deterministic progress.

Use one orange rarity key: `legendary`. Avoid storing display color names as rarity values; colors can change without data migration.