Phase 5 — Multiplayer, Queues & Hub Systems

Version: v0.5.0 Status: 🔄 In Progress

Goal

Complete the extraction loop and open it up to multiple players. Portal mode selection, proper death penalties, chest loot, and in-dungeon inventory close out the Phase 4 gaps. Queue matchmaking and PvPvE bring multiplayer online. Hub systems (Bounty Board, Dungeon Compactor, Aether Forge) give players reasons to keep running. Sound effects ship here too.

Deliverable

A fully playable multiplayer build: queue into a PvE or PvPvE session, run a dungeon with matched teammates and rivals, loot chests, die and lose Crux, extract and keep your gear, hear sound effects, and interact with hub vendors and the Bounty Board.

Planned

5.1 — Portal Mode Selection Screen

Currently Unstable fires immediately when pressing A at the portal. This milestone adds the proper mode selection UI.

• Full-screen mode picker showing all three modes:
  • Unstable — Free, small map, 10 min, 0% compactor, PvE or PvPvE
  • Stable — 20 Aether, medium map, 15 min, 30–40% compactor, PvE or PvPvE
  • Empowered — 1 Aether Core, large map, 20 min, 100% compactor, PvPvE only
• Stable and Empowered shown as locked (greyed) with cost displayed
• A confirms selection; B cancels back to hub
• Server deducts cost on EnterQueue; blocks if insufficient currency
• For Phase 5.1: Unstable is the only functional mode; Stable/Empowered UI visible but locked

5.2 — Phase 4 Gap Closure

Close the gaps from Phase 4 before adding new systems.

• Crux loss on death: 20–30% of carried Crux destroyed server-side on PlayerDied; DeathResult { crux_lost } sent to client; shown on death screen
• Chest loot drops: chests in dungeons roll a guaranteed item drop (weighted rarity by chest visual type 0–7); uses existing loot pipeline; item appears as ground loot
• In-dungeon inventory: Select button (currently held-to-extract) opens a simple list of equipped items and run loot; B closes; no stash access in-dungeon; items can be inspected but not rearranged (Phase 5 scope — full management deferred)
• Hub music: separate background track playing in Blackthorn Hollow; fades on transition to dungeon

5.3 — Queue System & Dungeon Instances (Server)

The server manages multiple dungeon instances concurrently.

Queue:

• Server maintains a lobby queue per (RunType, PortalMode) combination
• Run types: PvE (max 4 players, 1 team) and PvPvE (max 8 players, flexible teams)
• Queue fires when capacity is reached OR after a timeout (solo queue: starts immediately)
• Solo queue in PvPvE: warning shown to client before confirming

Instance management:

• Each instance is an isolated tokio::spawn task with its own GameWorld
• No state shared between instances
• Instance cleans itself up when all players have extracted, died, or disconnected
• Max concurrent instances capped to stay within Pi/VPS memory budget

Team assignment:

• PvE: all players on one team, no friendly fire
• PvPvE: server assigns teams trying to balance sizes (max 4 per team); flexible compositions (4v4, 3v3v2, 2v2v2v2)

5.4 — Remote Player Rendering (Client)

Other players appear in the dungeon.

• Remote players render as 32×32 sprites using their chosen character sheet and class animation
• Team indicator: small coloured diamond above sprite — green (same team), red (rival); no indicator in PvE
• No player names displayed in-run (screen is too small)
• Client receives remote player positions in WorldSnapshot; interest management filters to ~15-tile radius

Interest management (server):

• WorldSnapshot only includes entities within ~15 tiles of the receiving player
• Prevents rivals from seeing each other's positions through packet inspection

5.5 — Corpse Looting

On death, equipped items stay in the world.

PvE:

• Half of equipped loot randomly destroyed server-side on PlayerDied
• Surviving half placed as a lootable corpse entity
• Only teammates can interact with it
• Teammates pick up items and can hand them back; items go to that player's stash on extraction

PvPvE:

• All equipped loot placed on corpse
• Any player can loot it — server validates pickup on first-come basis
• Looted items go directly to the looter's stash on extraction

Client:

• Corpse rendered as a distinct entity (visual TBD — likely a coloured marker)
• Walking over it shows a proximity hint; R1 opens a loot list
• Same pickup flow as ground loot

5.6 — Bounty Board

Optional daily/weekly tasks that support the core loop. Never required for progression.

• Bounty Board POI in Blackthorn Hollow opens a task list (up to 3 active bounties)
• Task types (Phase 5 subset): kill N enemies, extract N times, pick up N items of rarity X
• Rewards: Crux, Aether, or a guaranteed item drop
• Tasks reset daily/weekly server-side; progress tracked in SQLite
• Client shows task list with progress bars and reward icons
• New table: bounties (id, character_id, kind, target, progress, reward_kind, reward_amount, expires_at)

5.7 — Dungeon Compactor

A rare in-dungeon vendor that gives better Crux rates than the Town Compactor.

• Spawns inside dungeons based on portal mode: 0% Unstable, 30–40% Stable, 100% Empowered
• Interacting (A) opens a simple exchange screen: sell equipped/run items for Crux at a bonus rate
• Items sold here are gone permanently — cannot retrieve after the run
• If you die before extracting, any Crux gained from the compactor is lost with your Crux pool

5.8 — Aether Forge

Hub crafting station for augmenting gear.

• Aether Forge POI opens a crafting UI
• Augments: up to 3 slots per item (rolled on drop); slots contain stat bonuses or special effects
• Crafting consumes Aether + Crux to add or reroll an augment on an item from your stash
• Augment effects (Phase 5 subset): flat stat bonuses (ATK, DEF, SPD), HP regen on kill, cooldown reduction
• Server-side only — client sends CraftAugment { item_id, slot_index, recipe_id }; server rolls and responds with updated item

5.9 — Sound Effects

WAV files only — ALSA direct on Miyoo (no SDL2 audio).

Target sounds:

• Melee swing and hit
• Spell cast and impact
• Player hurt and death
• Item pickup and equip
• Chest open
• Portal activation and extraction success
• UI navigation (menu scroll, confirm, cancel)
• Hub ambient loop

All audio must be tuned for the Miyoo's small speaker. All files must be WAV (16-bit PCM); no OGG or MP3.

Network Messages Added in Phase 5

All over TCP.

SQLite Schema Additions

CREATE TABLE bounties (
    id             INTEGER PRIMARY KEY,
    character_id   INTEGER NOT NULL,
    kind           TEXT NOT NULL,
    target         INTEGER NOT NULL,
    progress       INTEGER NOT NULL DEFAULT 0,
    reward_kind    TEXT NOT NULL,
    reward_amount  INTEGER NOT NULL,
    expires_at     INTEGER NOT NULL
);

Augment data lives on the Item struct (already has augment_slots: Vec<Augment>) — no new table needed; item JSON in stash_items / equipped_items carries augments.

What Carries Over from Phase 4

• Full account, session, character, stash, and equipped-items DB layer
• Complete hub flow (login → character select → hub → dungeon → extract/die → hub)
• All combat mechanics unchanged
• Enemy AI and dungeon generation unchanged
• Inventory UI (Equipment / Stash / Character tabs) — graphical overhaul deferred to Phase 6
• Loot pipeline (rolls, ground rendering, pickup, affix combat wiring)

Deferred to Phase 6

• Graphical inventory (icon-based grid vs current list UI)
• Full NPC sprites and dialogue in Blackthorn Hollow
• Per-class Y-button and B double-tap ability effects (full rework)
• Stable and Empowered portal modes going fully live (5.1 only stubs them)
• Password hashing server-side (bcrypt); current SHA-256 is client-side only
• Hub map tileset rendering (hand-authored map in map editor)
• Auto-update client binary from server
• Onion OS .port launcher packaging

Done

(Updated as milestones complete)

• 5.1 Portal Mode Selection Screen
• 5.2 Phase 4 Gap Closure (Crux death loss, chest loot, in-dungeon inventory, hub music)
• 5.3 Queue System & Dungeon Instances
• 5.4 Remote Player Rendering + Interest Management
• 5.5 Corpse Looting (PvE + PvPvE)
• 5.6 Bounty Board
• 5.7 Dungeon Compactor
• 5.8 Aether Forge
• 5.9 Sound Effects

Previous: Phase 4 — Loot, Extraction & Hub Next: Phase 6 — Polish & Release