This project has been created as part of the 42 curriculum by jmattion & loursel

The Answer Protocol (TAP)

A Retro Multiplayer Text Adventure (MUD)

---

Description

The Answer Protocol (TAP) is a shared-world retro text adventure (MUD) built for the 42 curriculum, centered on a highly concurrent, asynchronous Rust server and a custom TCP protocol.

Players navigate a school-themed world, complete quests, and face off against an NPC through a turn-based social encounter system. The setting is a light framing device for the actual point of the project: designing a real-time protocol and a server that handles many concurrent clients correctly and safely.

The project features:

• A high-performance asynchronous Rust server
• A lightweight CLI client for pure text interaction
• A GUI client built with the Bevy engine

---

Instructions

Prerequisites

• Rust & Cargo — latest stable version
• Assets — GUI assets (images/sounds) must be located in the assets/ directory of the GUI client

Building

cargo build --release

Running

# Start the server
cargo run --bin server

# Run the GUI client
cargo run --bin client_gui

# Run the CLI client
cargo run --bin client_cli

---

Architecture

The system follows a highly concurrent, asynchronous model to handle multiple players in real-time.

Component	Description
Server Design	Built with tokio. Uses a Command Dispatcher pattern — incoming TCP strings are parsed into tokens and routed via a HashMap of function pointers.
Concurrency Model	Global state (Map, Connected Usernames, Groups) is wrapped in Arc<Mutex<T>>, enabling safe cross-thread reads/writes via Tokio tasks.
Client Communication	An EventManager handles broadcast events (EVT) and private group messages without blocking the main request-response cycle.

---

Protocol Implementation

Strictly adhering to RFC 42TAP. All mandatory commands are supported:

- CONNECT
- LOOK
- MOVE
- CHAT
- TAKE
- DROP
- INVENTORY
- TALK
- ATTACK
- STATUS
- QUEST
- QUESTS
- WHO
- GROUP
- QUIT

Deviations & Justifications

Graceful JSON Extensions — To support the GUI's health bars and complex dialogue trees, the server appends JSON payloads to standard OK responses:

OK {"attacker_hp": 100, ...}

A generic CLI client from another group will simply print the raw JSON as text (compliant with the MUD's "raw text" nature), while our GUI parses it to trigger visual animations. 100% interchangeable.

---

Encounter System

The game includes a turn-based social encounter system, primarily focused on one NPC: Kurumi.

Actions

#	Move	Damage	Success Rate	Requirement
1	The Polite Hello	Low	High	—
2	The Cheesy Compliment	Medium	Lower	—
3	The Bold Flirt	High	Medium	luxury_cologne

Rules

• Damage is static per attack type; success is determined by RNG.
• Failing an attack triggers a counter-attack from the NPC.
• The player always takes the first move.
• Retreat stages — Kurumi retreats to the Library at 69 HP, then to the Rooftop at 29 HP.
• Defeat — Reaching 0 HP sends you to school_toilets (the recovery room) with 75 HP, inventory dropped on the spot.

---

Quest System

The Alchemist's Request

Mei — Science Lab

• Objective: Bring her the love_letter hidden in the Library.
• Reward: luxury_cologne (unlocks The Bold Flirt action)

Win Over the Ice Queen

Futaro — Gymnasium

• Objective: Defeat Kurumi in the encounter system.
• Validation: Checked via player quest history + Kurumi's HP state.
• Reward: kurumis_heart_key (the game-winning item)

---

World Design

11 interconnected rooms, one loop and branches:

                                SCHOOL MAP
                                ==========

      [CAFETERIA] <----------> [COURTYARD] <----------> [STUDENT LOUNGE]
      (NPC: Rina)              (NPC: Kurumi)                   ^
   (Item: Chocolates)                                          |
              ^                                                |
              |                                                v
              v                                         [EAST CORRIDOR] <---> [LIBRARY]
         [GYMNASIUM]                                     (NPC: Akane)      (Item: Letter)
        (NPC: Futaro)                                          ^
              ^                                                |
              |                                                |
              v                                                v
 [TOILETS] <-> [WEST CORRIDOR] <-----> [MAIN HALLWAY] <-----> [SCIENCE LAB]
                                           ^                   (NPC: Mei)
                                           |
                                           v
                                       [ROOFTOP] (UP)

NPCs

NPC	Role	Location
Futaro	Quest Giver	Gymnasium
Mei	Quest Giver	Science Lab
Rina	Lore	Cafeteria
Akane	Lore	East Corridor
Kurumi	Target	Moves between rooms

Key Items

• box_chocolates — Cafeteria
• love_letter — Library

---

Server Logging

[INFO] - 2026-04-16 15:20:40 - Server started on port 7878
[DEBUG] - 2026-04-16 15:10:26 - Received command from 10.11.4.6:38400: INVENTORY
[WARN] - 2026-04-16 15:10:13 - ERR 418 PLAYER_NOT_FOUND
[ERROR] - 2026-04-16 15:04:15 - Failed to read from client: Connection closed

Logged events include: TCP connections/handshakes, command parsing with parameters, world state changes (Take/Drop), and encounter results.

Persistent logging: all logs are saved to /tmp/logs/.

Anti-Abuse Protection

• Commands exceeding 255 per 500ms → ERR 929 TOO_MANY_REQUESTS + disconnect.
• Duplicate IP connections are blocked to mitigate basic DDoS patterns.

---

Group Contributions

jmattion

• Developed the GUI using Bevy (ECS)
• Implemented the CLI client with async Tokio loops
• Designed the world data (YAML)
• Built dynamic UI systems (dialogue boxes, HP bars, inventory formatters)

loursel

• Developed the async TCP server core using Tokio
• Implemented the protocol dispatcher and command routing
• Built the encounter and quest logic engines
• Implemented the logging system and anti-abuse/spam protections

---

Testing

• Multiplayer — Connect one GUI + one CLI client, use CHAT global / CHAT room to verify real-time message propagation.
• Shared World — Drop an item in the cafeteria with one client, verify the other can LOOK and TAKE it.
• Encounter / Retreat — Reduce Kurumi's HP and verify she moves to the Library, then the Rooftop.
• Quest — Complete Mei's quest, receive the cologne, verify ATTACK 3 becomes available in the GUI against Kurumi.

---

Resources

• Rust Documentation
• Tokio.rs Tutorial
• Bevy Documentation

AI Usage: documentation and README drafting.

---

Built at 42 — jmattion & loursel