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.