All communication between the MMO Project client and server uses a versioned JSON WebSocket protocol over a single persistent connection. Every message carries aDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/TaylorZaneKirk/MMO-Project/llms.txt
Use this file to discover all available pages before exploring further.
type field that identifies the message and a payload object containing message-specific fields. The server is the authoritative source for all game state — no client message directly mutates state.
Design rule
All client messages represent player intent, not player-authored state mutations. The server resolves all outcomes authoritatively and sends the confirmed result back to the client before the client applies any change.Message format
Every message on the wire follows this envelope structure:type value matches the name field in protocol-v1.json. The payload object contains the fields documented for that message. Empty or missing payloads are not used — every message has at least one payload field.
Version
The protocol version for this slice isv1. The client sends protocol_version: "v1" as part of login_request. The server rejects any message that carries an unknown or unsupported protocol version and closes the connection.
Complete message catalog
| Message Name | Direction | Purpose |
|---|---|---|
login_request | C→S | Authenticate with account credentials and declare protocol version |
login_response | S→C | Return login outcome, session ID, and account ID |
character_load_response | S→C | Bind the authenticated session to the account’s character |
enter_world_response | S→C | Deliver starting map position and presence source |
world_snapshot | S→C | Deliver full authoritative world state including player, NPCs, ground items, and remote players |
player_state_update | S→C | Broadcast a remote player’s updated position and state to map peers |
npc_state_update | S→C | Broadcast an NPC’s updated position and state to the map |
movement_intent | C→S | Request movement to a target tile coordinate |
movement_applied | S→C | Confirm the authoritative movement result and updated position |
character_state_updated | S→C | Push a revisioned delta of changed character streams (delta clients only) |
ground_item_spawned | S→C | Notify the map that a ground item has become visible |
ground_item_removed | S→C | Notify the map that a ground item has been removed |
player_entered_map | S→C | Reserved — notify the map that a player has joined (not yet active) |
player_left_map | S→C | Reserved — notify the map that a player has departed (not yet active) |
world_resync_request | C→S | Request a fresh world snapshot after detecting a revision gap |
inventory_item_use_request | C→S | Request a primary use action on an inventory item |
inventory_item_use_response | S→C | Return the authoritative outcome of the use action |
inventory_item_drop_request | C→S | Request that an inventory item be dropped onto the current tile |
inventory_item_drop_response | S→C | Return the authoritative outcome of the drop action |
ground_item_pickup_request | C→S | Request pickup of a visible ground item on the current tile |
ground_item_pickup_response | S→C | Return the authoritative outcome of the pickup action |
equipment_item_unequip_request | C→S | Request that an equipped item be moved back to inventory |
equipment_item_unequip_response | S→C | Return the authoritative outcome of the unequip action |
logout_request | C→S | End the session explicitly and clear map presence |
reconnect_request | C→S | Attempt to restore a disconnected session within the grace window |
reconnect_response | S→C | Return the reconnect outcome and restored position |
Excluded from v1
The following feature areas are outside the scope of this protocol slice and have no messages inprotocol-v1.json:
- Chat
- Combat
- NPC interaction
- Storage
- Admin commands
player_entered_map and player_left_map are reserved for the next presence-delta slice. Current connect, disconnect, and reconnect flows still use full snapshots for map-membership reconciliation.