From 1aba2bdd23aebed4032333e74aa553c40a31fcbd Mon Sep 17 00:00:00 2001 From: historia <[not public]> Date: Sun, 14 Jun 2026 21:07:26 -0400 Subject: refactor: added docs, split up some components in game package --- AGENTS.md | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index 624034b..2897be8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,18 +21,32 @@ Dependencies: `gopkg.in/yaml.v3`, `github.com/gorilla/websocket`. ``` cmd/mud/main.go Entry point — config loading, multi-listener, tick engine -internal/config/ YAML config (telnet, http, https listeners) -internal/net/ Conn interface (tcp + websocket), session state, hub, IAC echo -internal/game/ Login flow, command dispatch, input sanitization, all game logic -internal/action/ Behavior structs (GatherConfig, TalkConfig, etc.), Action, drop tables -internal/player/ Player struct, skills, inventory, XP, name/password validation -internal/world/ Room, MobDef, MobInstance, ObjState, ground items, wandering -internal/combat/ Combat state tracking, OSRS-style combat formulas -internal/object/ ItemDef, ObjectDef, item/object YAML loaders -internal/engine/ Tick scheduler — 600ms interval, subscriber pattern +internal/config/ YAML config (telnet, http, https listeners) + doc.go +internal/net/ Conn interface (tcp + websocket), session state, hub, IAC echo + doc.go +internal/game/ Login flow, command dispatch, input sanitization, all game logic + doc.go +internal/action/ Behavior structs (GatherConfig, TalkConfig, etc.), Action, drop tables + doc.go +internal/player/ Player struct, skills, inventory, XP, name/password validation + doc.go +internal/world/ Room, MobDef, MobInstance, ObjState, ground items, wandering + doc.go +internal/combat/ Combat state tracking, OSRS-style combat formulas + doc.go +internal/object/ ItemDef, ObjectDef, item/object YAML loaders + doc.go +internal/engine/ Tick scheduler — 600ms interval, subscriber pattern + doc.go ``` -`internal/game/` is the largest package and contains most command implementations as `cmd_*.go` and `action_*.go` files. +`internal/game/` is the largest package. Key files: + +| File | Purpose | +|---|---| +| `game.go` | Game struct, HandleSession state machine, command dispatch | +| `login_account.go` | Account auth, creation, password handling, main menu, account rename/purge | +| `login_char.go` | Character creation, connection, rename, delete | +| `cmd_*.go` | Command handlers (see Adding a New Command below) | +| `action.go` | StartAction, CancelAction, AdvanceActions, checkCondition | +| `action_*.go` | Action lifecycle per behavior type (gather, talk, use, toggle, burn) | +| `tick.go` | DisconnectTick, RegenTick, WanderTick, WoodcuttingTick | +| `map.go` | BFS graph builder, tiny map, full map, display utilities (strip, trim) | +| `types.go` | Shared types (EquipSlots, itemMatch, xpGain, deathDrop) | +| `utils.go` | Helper functions (plural, parseQty, parseChoiceIndex, formatPickupList, etc.) | +| `help.go` | Help topic YAML loading and display | ## Key Conventions @@ -44,7 +58,7 @@ internal/engine/ Tick scheduler — 600ms interval, subscriber pattern **Transport-agnostic.** The `Conn` interface (`internal/net/conn.go`) abstracts the transport layer. `tcpConn` wraps a raw `net.Conn` for telnet. `wsConn` wraps `gorilla/websocket.Conn` for the web client. Game code works with `*Session` regardless of transport. -**Input sanitization.** `HandleSession` strips Unicode control characters (ANSI escapes, nulls, etc.) from every input line before dispatch. Account/character names validated to `[A-Za-z0-9 ]{1,30}`. Input truncated to 1024 bytes. Password echo suppressed via IAC ECHO (telnet) and OSC sequences (web). WebSocket origin checked against host header. +**Input sanitization.** `HandleSession` strips Unicode control characters from every input line via `player.StripControlCharacters` before dispatch. Account/character names validated to `[A-Za-z0-9 ]{1,30}`. Input truncated to 1024 bytes. Password echo suppressed via IAC ECHO (telnet) and OSC sequences (web). WebSocket origin checked against host header. **Tick-driven.** The world runs on a 600ms tick. Combat, gathering, regen, wandering, respawns, shared depletion, woodcutting timers all advance per tick. See `cmd/mud/main.go` for the subscription loop. @@ -78,7 +92,7 @@ Actions that interact with objects/mobs route through `StartAction()` in `action 5. Place the object in a room YAML in `data/rooms/` 6. Create any resource items in `data/items/` -Set `xp` on the behavior to award XP on successful gathers. Set `shared_deplete` for tree-style depletion, or use per-drop `depletes: true` for rock-style depletion. +Set `xp` on the behavior to award XP on successful gathers. Set `deplete_timer` for tree-style depletion, or use per-drop `depletes: true` for rock-style depletion. ## Adding a New Production Skill @@ -134,7 +148,7 @@ Firemaking is implemented as standalone actions (not behavior-YAML-driven) in `i **Per-drop depletion** (mining, regular trees): Set `depletes: true` on a drop entry. The resource depletes on first successful gather of that drop. Rocks don't show despawn timers when not depleted. -**Shared depletion** (higher-tier trees): Set `shared_deplete: ` on the behavior. A shared timer counts down while anyone is chopping; when it hits 0, the next successful gather depletes the tree for all players. The timer regenerates back to max when no one is chopping. `WoodcuttingTick` manages this in `internal/game/tick.go`. +**Shared depletion** (higher-tier trees): Set `deplete_timer: ` on the behavior. A shared timer counts down while anyone is chopping; when it hits 0, the next successful gather depletes the tree for all players. The timer regenerates back to max when no one is chopping. `WoodcuttingTick` manages this in `internal/game/tick.go`. ## Data Files -- cgit v1.2.3