1 files changed, 29 insertions, 0 deletions
diff --git a/internal/game/doc.go b/internal/game/doc.go
new file mode 100644
index 0000000..97814e9
--- /dev/null
+++ b/internal/game/doc.go
@@ -0,0 +1,29 @@
+// Package game is the core session handler, command dispatch, login flow,
+// and action system for the MUD.
+//
+// The Game struct holds all world state: room/world access, item/object
+// stores, mob instances, behavior definitions, the player hub, and the
+// tick engine. HandleSession routes incoming input through the login
+// state machine into the in-game command dispatch.
+//
+// Commands are dispatched via handleGameCommand in game.go, which
+// resolves account aliases before switching on the command word.
+// Most commands cancel the player's ongoing action (gathering, etc.).
+//
+// Action system: StartAction normalizes verbs, resolves object/mob
+// targets, loads behaviors, and routes to type-specific handlers.
+// Actions that take time (gather, use, burn, stoke) tick via
+// AdvanceActions, called each 600ms tick.
+//
+// Tick handlers: DisconnectTick, RegenTick, WanderTick, WoodcuttingTick,
+// and FireTick run each game tick to advance world simulation.
+//
+// File organization:
+//   cmd_*.go    — player command handlers (doLook, doMove, doGet, etc.)
+//   action_*.go — action lifecycle (startGather, advanceBurn, talk, toggle, etc.)
+//   login.go    — account creation, authentication, character management
+//   map.go      — BFS graph builder, tiny + full-map rendering
+//   tick.go     — per-tick world updates (disconnect, regen, wander, woodcutting)
+//   utils.go    — shared types and helper functions
+//   help.go     — help topic loading and display
+package game