Phase 4 — Loot, Extraction & Hub

Version: v0.4.0 Status: 🔲 Planned

Goal

Turn the game into a complete extraction roguelike. The full loot system, dual currency, portal modes, death penalties, Blackthorn Hollow hub, and all five NPCs ship in this phase. By the end, the core loop — gear up, choose a portal mode, run a dungeon, extract or die — is fully playable.

Deliverable

A complete solo extraction loop on real Miyoo hardware: manage your stash in Blackthorn Hollow, choose a portal mode, fight through a dungeon, loot gear with rarity and affixes, and either extract to keep it all or die and lose everything equipped. Daily tasks reward you for playing. The hub feels alive with five distinct NPCs.

Planned

Currency System

Two currencies with different loss rules:

Aether Core is crafted at the Aether Forge — not found as a drop. Recipe: Aether + Crux + Rift Fragments (rare component found in Stable/Empowered runs).

Full Item System

All item data lives in shared/src/lib.rs:

pub enum Rarity { Common, Uncommon, Rare, Epic, Legendary }

pub struct Affix { pub name: String, pub value: f32 }

pub struct Augment { pub id: u32, pub name: String, pub effect: String }

pub struct Item {
    pub base_id: u32,
    pub rarity: Rarity,
    pub affixes: Vec<Affix>,
    pub augment_slots: Vec<Option<Augment>>, // 0–3 slots; None = empty
    pub flavor_text: Option<String>,
}

Rarity scaling:

All loot generation happens server-side only. The client receives fully computed Item structs.

Ability Tomes

Found as loot drops in dungeons (same rarity system as gear). Equipped into hotbar slots (up to 4 total, beyond the 2 fixed starters). If equipped when you die, they are permanently lost. If stored in the stash, they are safe.

This ties additional abilities directly to the extraction risk/reward loop.

Dungeon Portal Modes

Chosen at the Dungeon Portal before each run. Captain Thorne manages the UI.

The extraction portal activates 5 minutes into every run. Dungeon despawns at the mode's time limit — anyone still inside loses everything equipped.

Compactors (Recycling)

Two locations, same mechanic — break down unwanted gear into Crux:

• Town Compactor (near Crowe's Tradehouse) — Safe. Standard exchange rate. Always available.
• Dungeon Compactor — Spawns inside dungeons (chance based on mode). Significantly better rate. High risk: anything gained is lost if you don't extract. Recycling any augment or slotted item also returns a small amount of Aether.

Extraction & Death Logic (Server)

• An extraction portal spawns at dungeon generation and activates 5 minutes in
• Successful extraction → all equipped items and Ability Tomes move to the player's permanent stash in SQLite
• Death in PvE → half of equipped loot is randomly destroyed; teammates can retrieve the remaining items from the corpse
• Death in PvPvE → full corpse looting by anyone
• Crux — 20–30% lost on death regardless of mode; remainder kept
• Aether — never lost on death
• Stash items are always safe — never at risk

Blackthorn Hollow — Full Hub

The complete town hub ships in this phase. Five NPCs, all functional.

Grim (Tavern) — Sells basic potions and consumables. Dry commentary between runs. Short, skippable dialogue.

Mira (The Ironvault) — Stash keeper. Allows viewing, equipping, and organizing all extracted items. Context-aware lines after death or a good extraction.

Bargus Crowe (Crowe's Tradehouse) — Buys unwanted loot at base Crux value. Sells supplies, potions, and low-tier gear. Also hosts the Scavenger Exchange (basic version: list gear for others to buy with Crux, small fee applies).

Veyra (Aether Forge) — Augment socketing and unsocketing. Augment crafting (requires components + Aether + Crux). Breaking down augments for components. Full Aether Forge UI.

Captain Thorne (Dungeon Portal) — Queue selection (PvE-only or PvPvE) and portal mode selection (Unstable / Stable / Empowered) with clear cost and risk display.

All NPC dialogue is max 2–3 lines, skippable at any time. Context-aware lines for death, legendary finds, and first run.

Client: Inventory & Equip UI

Built for the Miyoo's small screen:

• 4–6 column grid of 16×16 item icons
• Select with D-pad, confirm with A
• Tooltip shows: rarity-coloured name, base stats, affix list, augment slot indicators (tiny glowing gems), flavor text
• Stat comparison when hovering a new item over an equipped one ("+12 Damage vs current")
• Hotbar shows equipped Ability Tomes with cooldown indicators

Client: Bounty Board (Daily/Weekly Tasks)

Clean list screen accessed in the central square. Displays current tasks and progress counters. Refreshes automatically (server-side timers).

Daily task examples:

• Extract with at least 3 different item types
• Defeat 15 enemies in a single run
• Use 5 potions during a run

Weekly task examples:

• Complete 5 successful extractions
• Extract a Rare or higher item
• Survive an Empowered run

Rewards: Crux, Aether, occasional Rift Fragments or crafting components. Never mandatory.

SQLite Persistence (Server)

Player data stored server-side in SQLite via rusqlite:

• Permanent stash (all extracted items)
• Crux and Aether balances
• Task progress and last-refresh timestamps
• Character class selection

Nothing meaningful is stored on the Miyoo client side — it's always authoritative from the server.

Deploy & Test Loop

cargo run -p server
cargo build -p client --target armv7-unknown-linux-musleabihf
# Replace 192.0.0.1 with your Miyoo's local IP
scp target/armv7-unknown-linux-musleabihf/debug/client root@192.0.0.1:/tmp/rpg98_client
ssh root@192.0.0.1 "/tmp/rpg98_client"

Key end-to-end tests:

• Gear up in hub → enter Unstable run → extract → verify stash updated
• Die in PvE → confirm equipped items lost, Crux partially preserved
• Complete a daily task → confirm reward delivered
• Craft an Aether Core → run Empowered mode → use Dungeon Compactor
• Find and equip an Ability Tome → die → confirm tome permanently lost

Completion Checklist (Planned)

• Full Item struct in shared crate (rarity, affixes, augment slots, flavor text)
• Server loot generation function (weighted rarity, stat scaling, affix rolls, slot rolls)
• Ability Tomes as loot drops, equippable to hotbar, lost on death
• Crux + Aether currencies with correct death loss rules
• Dungeon Portal with all three modes (Unstable / Stable / Empowered)
• Extraction portal spawns + activates at 5 min, dungeon despawns at time limit
• PvE death rule (half loot destroyed, rest on corpse)
• PvPvE death rule (full corpse looting)
• Town Compactor functional
• Dungeon Compactor spawns in dungeons at correct rates per mode
• SQLite persistence for stash, currency, task progress
• All five NPCs functional with correct services
• Aether Forge: socket/unsocket augments, craft augments, break down for components
• Scavenger Exchange: list and buy gear for Crux
• Inventory/equip UI with tooltip and stat comparison
• Bounty Board: daily and weekly tasks with auto-refresh and rewards
• Complete solo extraction loop tested end-to-end on real Miyoo hardware

Actual

— Not yet started. To be filled in when Phase 4 is complete. —

What Was Built

Deviations & Discoveries

What Was Deferred

Completion Checklist (Actual)

• Full Item struct in shared crate (rarity, affixes, augment slots, flavor text)
• Server loot generation function (weighted rarity, stat scaling, affix rolls, slot rolls)
• Ability Tomes as loot drops, equippable to hotbar, lost on death
• Crux + Aether currencies with correct death loss rules
• Dungeon Portal with all three modes (Unstable / Stable / Empowered)
• Extraction portal spawns + activates at 5 min, dungeon despawns at time limit
• PvE death rule (half loot destroyed, rest on corpse)
• PvPvE death rule (full corpse looting)
• Town Compactor functional
• Dungeon Compactor spawns in dungeons at correct rates per mode
• SQLite persistence for stash, currency, task progress
• All five NPCs functional with correct services
• Aether Forge: socket/unsocket augments, craft augments, break down for components
• Scavenger Exchange: list and buy gear for Crux
• Inventory/equip UI with tooltip and stat comparison
• Bounty Board: daily and weekly tasks with auto-refresh and rewards
• Complete solo extraction loop tested end-to-end on real Miyoo hardware

Previous: Phase 3 — Combat & Classes Next: Phase 5 — Multiplayer & Queues