Miyoo Extraction RPG — Phase 4: Multiplayer, Queues & Polish

Phase 4 brings the full multiplayer experience online. You will implement the PvE-only and PvPvE queues with smart team-size matching, support up to 8 players per dungeon (capped at 3 per team in PvPvE), and add the final polish layer (sound, particles, Onion OS packaging) so the game feels complete and ready for release.

🎯 Goal

Deliver robust, balanced multiplayer with two queue types, matched team sizes, and a polished experience that runs smoothly on real Miyoo hardware.

✅ Final Deliverable

A fully playable multiplayer build: players can queue into PvE-only or PvPvE sessions, form matched teams (max 3 per team, 8 total), fight together or as rivals, hear sound effects, see augment particles, and launch directly from the Onion OS launcher.

📋 Prerequisites — Complete Phase 0, 1, 2 & 3 First

✔️ Rust server with combat, loot, and town systems
✔️ Miyoo client with full inventory, town hub, and extraction loop
✔️ Working hybrid TCP+UDP networking and chunk culling
✔️ Three classes, abilities, and loot fully functional
✔️ Daily/weekly tasks and SQLite persistence

Detailed Steps for Phase 4

Expand Shared Crate with Multiplayer Structures

In shared/src/lib.rs add team and queue data:

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum QueueType { PvEOnly, PvPvE }

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Team {
    pub id: u32,
    pub players: Vec<PlayerId>,
    pub color: u32, // for tinting sprites
}

#[derive(Debug, Serialize, Deserialize)]
pub enum Packet {
    // ... previous
    JoinQueue { queue_type: QueueType, party_size: u8 },
    QueueMatched { dungeon_id: u64, team_id: u32 },
    TeamUpdate { team_id: u32, members: Vec<PlayerId> },
}

Server: Build Lobby & Queue System

Create a lobby manager that:

Separates players into PvE-only or PvPvE queues
Groups players into parties (friends queue together)
Matches parties by size and skill/gear score (simple version first)

Server: Implement Matchmaking Logic with Limits

Enforce your rules:

PvE-only: flexible 1–8 players
PvPvE: matched team sizes, max 3 per team, hard 8-player dungeon cap
Balanced filling (duo prefers another duo or two solos, never 2 vs 6)
Fallback to “start anyway” after timeout

Client: Lobby UI & Queue Selection

Add a clean lobby screen on the Miyoo before entering a dungeon:

Buttons: “PvE Only” and “PvPvE (Rivals)”
Party list (friends who queued together)
Live queue status and estimated wait time

Team Assignment, Indicators & Friendly Fire

Server assigns teams on match. Client shows:

Colored name tags or tints on other players
Friendly-fire toggle (off by default in PvPvE)
Chat or ping system (optional but nice)

Multiplayer State Synchronization

Enhance UDP snapshots with interest management:

Only send data for entities in visible chunks (culling)
Handle up to 8 players + enemies without lag
Test prediction/reconciliation with multiple clients

Polish: Sound, Particles & Visual Feedback

Add the final layer of juice:

SDL2_mixer for attack sounds, spell effects, loot pickup, extraction chime
Simple particle system for legendary augments and critical hits
Team-colored glows and death effects

Onion OS Packaging & Final Hardware Testing

Package everything as a proper .app folder with icon and launcher metadata.
Run full end-to-end tests on multiple Miyoo devices with different network conditions (home WiFi, hotspot, 2–8 players).

✅ Phase 4 Complete When You Can:

✔️ Queue into PvE-only or PvPvE sessions with proper matchmaking
✔️ Play in balanced teams (max 3 per team, 8 total) with clear indicators
✔️ Experience smooth multiplayer combat and loot sharing/stealing
✔️ Hear sound effects and see polished particles on real hardware
✔️ Launch the game directly from Onion OS as a proper .app

The game is now a complete, polished multiplayer extraction experience. Phase 5 is just content, balance, and release.