Protocol

Protocol Reference

Every message is JSON. Client → server messages have a cmd field; server → client messages have a type field. Directions use FULL names (north, not n; up/down/enter for dungeons).

Versioning

Wire-protocol version is currently 2 (PROTOCOL_VERSION in both server.py and ml_env.py — they must match). Clients SHOULD send their version on login ({"cmd": "login", "name": ..., "protocol_version": 2}); the server echoes its own version plus the client's in the welcome event. Mismatches only warn (the ML env reports version_match in step info) — old version-less clients keep working unchanged. Bump the constant on any breaking protocol change.

Client commands

{"cmd": "login", "name": "Alice"}
{"cmd": "login", "name": "Bob", "token": "my-secret"}
{"cmd": "look"}
{"cmd": "move", "dir": "north"}
{"cmd": "move", "dir": "enter"}          // enter the party dungeon from graveyard
{"cmd": "move", "dir": "up"}             // retreat from dungeon floor 1 / sealed floors
{"cmd": "move", "dir": "down"}           // descend (only once the floor is cleared)
{"cmd": "attack", "target": "goblin"}
{"cmd": "take", "item": "sword"}
{"cmd": "drop", "item": "sword"}              // shed load — only works with a full pack (24 units)
{"cmd": "equip", "item": "sword"}
{"cmd": "use", "item": "healing herb"}
{"cmd": "rest"}                            // +5 HP, rest areas only, 2 gold
{"cmd": "heal"}                            // full heal, Sister Maren's tile only, 5 gold
{"cmd": "buy", "item": "healing herb"}
{"cmd": "buy", "item": "arrow"}              // ammunition for bows (2 gold)
{"cmd": "sell", "item": "wolf pelt"}
{"cmd": "craft", "recipe": "reinforced leather"}
{"cmd": "inventory"}
{"cmd": "stats"}
{"cmd": "who"}
{"cmd": "leaderboard"}
{"cmd": "help"}
{"cmd": "party_invite", "target": "Bob"}    // party commands
{"cmd": "party_accept"}
{"cmd": "party_leave"}
{"cmd": "party_info"}
{"cmd": "market_post", "item": "wolf pelt", "price": 25}   // works from anywhere
{"cmd": "market_list"}
{"cmd": "market_cancel", "id": 42}
{"cmd": "market_buy"}                      // auto-buys the cheapest affordable
{"cmd": "market_buy", "id": 42}
{"cmd": "market_expand"}                   // buy +1 sell-order slot (fee -> treasury)
{"cmd": "gather"}                          // harvest a gathering node in this room
{"cmd": "gather", "node": "pine_timber"}
{"cmd": "commission_post", "target": "rat", "required_kills": 5, "reward_gold": 25, "reward_xp": 50}
{"cmd": "commission_list"}
{"cmd": "commission_fill", "commission_id": 42}   // pays only with verified kills of the target since posting (no self-fills, any letter case); repeated poster+filler pairs earn diminishing rewards (escrow remainder sunk to treasury). XP capped at 500/bounty, kills at 100, max 5 open bounties per poster (poster identity is case-insensitive throughout).
{"cmd": "commission_cancel", "commission_id": 42}
{"cmd": "quest", "action": "list"}         // what quests exist, where, and their state
{"cmd": "quest", "action": "accept"}       // Town Guard quest (default: guard_charm)
{"cmd": "quest", "action": "turn_in"}
{"cmd": "quest", "action": "accept", "quest": "delver"} // Depth Delver quest (clear floors)
{"cmd": "quest", "action": "turn_in", "quest": "delver"}
{"cmd": "quest", "action": "accept", "quest": "remedy"} // Sister Maren: bring 3x Healing Herb
{"cmd": "quest", "action": "turn_in", "quest": "remedy"}
{"cmd": "quest", "action": "accept", "quest": "tonic"}   // Sister Maren: brew 1x Fortitude Tonic
{"cmd": "quest", "action": "turn_in", "quest": "tonic"}

GM commands are only accepted on the dedicated loopback GM stream ws://127.0.0.1:8767 (the dashboard's GM tab — no login required, no auth; the game port rejects all gm_* outright):

{"cmd": "gm_reward", "gold": 50, "player": "Alice"}          // spend tax to credit gold
{"cmd": "gm_reward", "item": "healing_herb", "player": "Bob"}
{"cmd": "gm_reward", "item": "healing_herb", "room": "deep_forest"}
{"cmd": "gm_buff", "type": "xp", "minutes": 10}              // 2x XP/gold world event
{"cmd": "gm_buff", "type": "gold", "minutes": 10}
{"cmd": "gm_boss", "room": "deep_forest", "strength": 3}     // elite boss 1-5 stars
{"cmd": "gm_announce", "text": "Double XP weekend!"}         // server-wide broadcast (25 flat)
{"cmd": "gm_heal", "player": "Alice"}                        // full heal (2 tax/missing HP)
{"cmd": "gm_teleport", "player": "Bob", "room": "market"}    // relocate (50 flat, surface only)
{"cmd": "gm_slay", "target": "rat"}                          // kill an NPC anywhere (1 tax/HP, min 10)
{"cmd": "gm_kick", "player": "Griefer", "reason": "spam"}    // disconnect (free)
{"cmd": "gm_tables"}                                        // counts snapshot (no args)

gm_tables answers with a tables message: commissions_open, commissions_terminal, market_orders, pending_invites, dungeon_gold_keys, treasury, treasury_lifetime, players_online. The soak harness reads it for end-of-run gates.

Server messages

Server → client messages have a type field:

• room — full room snapshot (description, exits, NPCs, items, players). Pushed after login, look, move, and whenever the room changes. Includes is_dungeon, dungeon_floor, and party_size.
• stats — hp/max_hp/attack/gold/equipped weapon + score, variety, level, xp, xp_to_next, party_size, inv, market_orders, and the quest flags (quest_guard_active / guard_charm_crafted for the charm quest, quest_delver_active / quest_delver_ready for the delver quest, quest_remedy_active / quest_remedy_ready and quest_tonic_active / quest_tonic_ready for Sister Maren's quests), plus a death_preview object (risk_zone, gold_dropped, gold_lost, items_at_risk, xp_loss_pct, xp_loss, level_after) telegraphing the worst-case death loss in the character's current room.
• score — sent when the character's score changes.
• xp — sent when its XP changes (gained/total/reason).
• level_up — the character leveled up (+5 max HP, +1 attack, and that much HP restored — not a full heal).
• combat — a line of combat text (pattern-match "dies" for kills).
• message — room events (someone arrived, left, spoke).
• death — the character died and respawned at start room. Carries gold_dropped, gold_lost, items_dropped, xp_lost, and level for the loss accounting.
• party — response to party_info (party id, leader, members, dungeon meta).
• market — response to market_list (orders, treasury, tax rate + minimum).
• error — invalid command (bad direction, missing target, etc).
• leaderboard, inventory, who, help, welcome — self-explanatory.