# AGENTS.md

The House of Icarus — a Runescape-like sci-fi MUD written in Go. Data-driven via YAML files. No database, no ORM.

Set on a terraformed asteroid where technology has regressed. "Technology" replaces Prayer, "Science" replaces Magic, Scavenging replaces Runecrafting.

## Build & Run

```bash
make build          # go build -o tc ./cmd/mud
make run            # build + run with DATA_DIR=./data
make test           # go test ./... -timeout 60s
make vet            # go vet ./...
```

Binary accepts `--config <path>` (defaults to `config.yaml`). If no config found, starts telnet on :4000.

Dependencies: `gopkg.in/yaml.v3`, `github.com/gorilla/websocket`.

Config:
```yaml
game:
  tick_length: 600       # ms per game tick (default 600, min 50)
```

## Package Map

```
cmd/mud/main.go         Entry point — config loading, multi-listener, tick engine
internal/
  config/               YAML config (telnet, http, https listeners)
  net/                  Conn interface (tcp + websocket), session states, hub, IAC echo
  game/                 Login flow, command dispatch, input sanitization, all game logic
  action/               Behavior structs (GatherConfig, TalkConfig, etc.), Action, drop tables, SuccessChance
  player/               Player struct, skills, inventory, XP (RSC table), name/password validation, accounts
  world/                Room, MobDef, MobInstance, ObjState, ground items, wandering, drop tables
  combat/               Combat state tracking, OSRS-style combat formulas
  object/               ItemDef, ObjectDef, item/object YAML loaders, EquipSlot, WeaponType, ItemStats
  engine/               Tick scheduler — configurable ms interval, subscriber pattern, ToTicks()
  color/                xterm-256 color system with auto ANSI downgrade, numeric palette (0-255), gradients, inline tags
```

`internal/game/` is the largest package. Key files:

| File | Purpose |
|---|---|
| `game.go` | Game struct, HandleSession state machine, command dispatch, ProcessQueuedCommands |
| `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 for each command (see Commands section) |
| `action.go` | StartAction, CancelAction, AdvanceActions, checkCondition, verbAliases, verbSkill |
| `action_*.go` | Action lifecycle per type (gather, talk, use, production) |
| `action_burn.go` | Burn/stoke firemaking (standalone, not behavior-YAML-driven) |
| `action_search.go` | Search bird's nests for loot |
| `action_room.go` | RunEnterSteps (on_enter scripts), BroadcastRespawns |
| `action_state.go` | ActionType consts, ActionState struct, Description() for look display |
| `action_default_target.go` | Smart auto-selection for gather/attack |
| `tick.go` | DisconnectTick, RegenTick, WanderTick, SharedDepletionTick, MoveTick, VisualTick, TechTick |
| `map.go` | BFS graph builder, tiny map, full map, display utilities (strip, trim) |
| `types.go` | EquipSlots, itemMatch, xpGain, deathDrop |
| `utils.go` | Helper functions (plural, parseQty, parseChoiceIndex, formatPickupList, etc.) |
| `help.go` | Help topic YAML loading and display |
| `color.go` | colorMode(), colorize(), colorTag() helpers |
| `table.go` | Unicode/ASCII table rendering for score/option/help/crafting menus |
| `tech.go` | TechDef struct, 25 hardcoded tech definitions, techLevelBonus, applyTechProtection, totalTechBonus |
| `cmd_tech.go` | doTech, toggleTech, doTechList, doTechQuick — technology command handlers |
| `cmd_stats.go` | doStats — equipment bonus totals, attack roll, max hit display |
| `cmd_clean.go` | doClean — background herb cleaning (Pharmacy) |
| `cmd_mix.go` | doMix — potion mixing via production system (Pharmacy) |
| `cmd_shop.go` | handleShopInput — buy/sell/browse/leave in shop interface |
| `action_steal.go` | doSteal, startSteal, advanceSteal — thieving action lifecycle |
| `cmd_sneak.go` | doSneak, SneakTick — sneak toggle + guard watch notifications |
| `action_clean.go` | advanceClean — background clean action lifecycle |
| `equip_stats.go` | playerEquipBonuses — sums all equipped items into one ItemStats |
| `aggro.go` | checkAggro — aggressive mob attack on room enter |
| `cmd_bank.go` | handleBankInput — deposit/withdraw/browse in bank interface |
| `cmd_construct.go` | doConstruct — construction production command at workbench |
| `cmd_estate_directory.go` | startEstateDirectory, lookEstateDirectory — player house directory, homeowner scanning, teleport |
| `course.go` | CourseStore, CourseConfig, ObstacleDef, ObstacleInfo — agility course YAML loader, room-to-obstacle lookup, obstacleVerbs |
| `cmd_agility.go` | doObstacle — agility obstacle command handler |
| `action_agility.go` | startObstacle, advanceObstacle, obstacleFail, calcFailChance — 3-phase obstacle lifecycle |
| `hacking.go` | HackingMinigame interface, HackingSession, terminalDefs, handleHackingInput, endHacking, hackingXP |
| `hacking_wumpus.go` | WumpusGame — Hunt the Rogue AI (20-node dodecahedron, probes, hazards) |
| `hacking_mastermind.go` | MastermindGame — Code Breaker (4-digit cipher, 10 guesses, feedback) |
| `hacking_liars_dice.go` | LiarsDiceGame — Signal Bluff (hidden dice bidding vs AI, wilds, exact calls) |
| `cmd_jack.go` | doJack, findTerminalInRoom — jack into terminals command handler |

## Key Conventions

**YAML-driven.** Rooms, items, objects, mobs, behaviors, drops are YAML files under `data/`. Read from disk on every access — edit a room description and it takes effect immediately, no restart.

**Live state.** Player data (characters, accounts) is written to YAML on every state change. Ground items, mob instances, and object states live in memory only and are lost on restart.

**No database.** Everything is flat YAML files. Account passwords use sha256 + 16-byte random salt.

**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 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 + loopback.

**Tick-driven.** The world runs on a configurable tick (default 600ms). Combat, gathering, regen, wandering, respawns, shared depletion, fire ticks all advance per tick.

**Fractional ticks.** All YAML timer fields (tool_speed, speed, base_wait, deplete_timer, etc.) accept `float64` values. `engine.ToTicks(base)` probabilistically rounds to an integer — a tool_speed of 4.5 means each action cycle has a 50% chance of 4 ticks and 50% of 5 ticks.

**Concurrency.** Every state-bearing package uses its own `sync.Mutex`:
- `world.World` — groundItems, objStates, seeded, objMoves
- `world.MobStore` — defs, instances
- `action.Store` — cache
- `engine.Engine` — subscribers
- `Game` — charsMu (loggedInChars map)
- `combat` — combatants, mobTargets

The pattern is: lock, snapshot/unmarshal, unlock, then process. The engine creates a subscriber snapshot each tick.

## Two State Systems

- **World flags** (`set_flags` / checked with `flag`): Shared by all players. A door opened by one player is open for everyone.
- **Player flags** (`set_player_flags` / checked with `player_flag`): Per-character, saved to character YAML. Quest progress, dialog history.

## Data Files

```
data/rooms/<id>.yaml      Room definitions (exits, objects, mobs, spawns, on_enter)
data/items/<id>.yaml      Item definitions (stats, equip_slot, tool_type, burn_ticks, search_table, etc.)
data/mobs/<id>.yaml       Mob definitions (combat stats, drops, behavior — NO wander config)
data/objects/<id>.yaml    Object definitions (name, behavior, hidden, inroom_description, removal_item, props)
data/behaviors/<id>.yaml  Behaviors (gather, talk, use)
data/drops/<id>.yaml      Shared drop tables (weighted item lists)
data/help/<id>.yaml       Help topics
data/recipes/<id>.yaml    Recipe definitions (cooking, crafting, smithing, etc.)
data/players/accounts/    Account YAML (gitignored)
data/players/characters/  Character YAML (gitignored)
```

Wander config (`wander_rooms`, `wander_interval`) is set per-instance in room YAML — mob defs are generic. Mobs wander via legal (unconditioned) room exits; objects teleport between rooms in their list.

See `worldbuilding_guide/` for full YAML format reference with examples.

## Inline Color Tags

Room descriptions (and prompts) support inline color tags using `{spec}text{/}` syntax. Untagged text in room descriptions uses the `room_desc` color target.

```yaml
description: "On the table lies a {182 bold}mysterious vase{/} with a rose in it."
```

Tag spec format matches the color command: `{<0-255> [bold] [dim] [underline]}text{/}`.

Gradients are supported: `{g:196,82}gradient text{/}`. Multi-stop: `{g:45,39,59}three stops{/}`.

Gradients interpolate in RGB space across the xterm-256 palette. In ANSI mode, each character maps to the nearest ANSI color.

Item and object YAML `color` fields also support gradient syntax: `color: "g:196,208,226"`.

## Commands

### Instant (execute immediately, no queue)
| Command | Description |
|---------|-------------|
| `say <text>` | Room chat (preserves case from raw input) |
| `score` / `sc` | Character stats and skills |
| `inventory` / `i` / `inv` | Inventory contents (28 slots) |
| `equip` / `eq` / `equipment` / `wear` / `wield` | View or change equipped items (no args = view, with args = equip) |
| `look` / `l` | Room view (mobs, objects, ground items, exits, players) |
| `look <target>` / `l <target>` | Examine mobs, objects, items, players, directions |
| `exits` | List available exits |
| `help [topic]` | Help topics from data/help/ |
| `map` | BFS ASCII map centered on player |
| `option` / `options [name] [value]` | Account-wide settings (see Option System) |
| `alias <name> <cmd>` | Account-wide command alias with arg passthrough |
| `unalias <name>` | Remove an alias |
| `description` / `desc` | Set custom player description |
| `prompt <value>` | Set custom per-character command prompt |
| `queued` | Show pending tick actions |
| `color` / `colors [target] [value]` | Customize display colors (account-wide) |
| `color reset <target>` | Reset a color target to server default |
| `color <target> off` | Disable color for a specific target |
| `colortable` | Display xterm-256 color reference chart |
| `style <name>` | Set combat style: accurate, aggressive, defensive, balanced (prefix match) |
| `stats` | Show total equipment bonuses, attack type, attack roll, max hit |
| `tech [name]` / `t` | Toggle tech on/off, `tech list` shows all, `tech quick <name>` sets quick tech |

### Free (stackable, execute before active)
| Command | Description |
|---------|-------------|
| `equip` / `wear` / `wield <item>` | Equip item to correct slot. `equip all` auto-equips best per slot |
| `remove` / `unwear` / `unwield <item>` | Unequip item back to inventory. `remove all` unequips everything |
| `eat <item>` | Eat food to heal (3-tick cooldown, can eat during combat) |
| `fletch [item]` | Fletch logs/items into bows, arrows, etc. (background action) |
| `clean [herb]` | Clean grimy herbs (background action, Pharmacy skill) |

### Active (replaces previous active, queued per tick)
| Command | Description |
|---------|-------------|
| `n` / `s` / `e` / `w` / `u` / `d` | Movement (multi-tick, equipment-dependent speed, flee during combat) |
| `get` / `take` / `grab` / `pick <item>` | Pick up item from ground (reservation-aware) |
| `get all` / `get all <name>` | Pick up all (or matching) items |
| `drop <item>` | Drop item to ground |
| `drop all` / `drop all <name>` | Drop all (or matching) items |
| `attack` / `kill <mob>` | Combat with numbered targeting and smart default |
| `mine` / `chop` / `cut` / `fish <object>` | Gathering with smart default (verbAliases map to "gather") |
| `use <item> [on/with] <target>` | Universal item interaction: recipes, crafting, gathering shortcuts |
| `cook <item>` | Cook raw food on a fire or cooking range (Cooking skill) |
| `smelt [item]` | Smelt ore into bars at a furnace (Smithing skill) |
| `smith [item]` | Smith bars into items at an anvil with a hammer (Smithing skill) |
| `mix [item]` | Mix potions from unfinished potions and reagents (Pharmacy skill) |
| `talk` / `speak` / `ask <target>` | NPC conversations (objects or mobs with behavior) |
| `pull` / `push <object>` | Interact with objects (shortcut for use) |
| `search <item>` | Search bird's nests / searchable items (rolls on search_table) |
| `burn [item]` | Start a fire (smart default: auto-select single log type) |
| `stoke [item]` | Add logs to existing fire for XP |
| `walk <room_number>` | BFS pathfinding to a room by number |
| `walk <directions>` | Direction sequence like `3n2e1u` (capped by agility level) |
| `construct` / `make [item]` | Construction: make planks or furniture at a workbench (Active, production system) |
| `bank` / `use bank` | Open bank interface at a bank booth (deposit, withdraw, browse, leave) |
| `scramble` / `jump` / `swing` / `balance` / `climb` / `crawl` / `vault` / `leap` / `slide` | Agility obstacle verbs (Active, per-room validation) |
| `jack` / `jackin [terminal]` | Jack into a terminal for hacking minigames (Active) |
| `quit` | 10-tick rest sequence, then return to menu (blocked during combat) |

## Command Dispatch

`handleGameCommand()` in `internal/game/game.go`:
1. Cancel rest timer
2. Resolve account aliases (alias expansion BEFORE command lookup — can shadow built-ins)
3. Classify command (Instant / Free / Active / Unknown)
4. Instant runs immediately; Free/Active queue for next tick

## Tick-Based Action Queue

`ProcessQueuedCommands` runs each tick:
1. Clears stale ActionState from one-tick actions (move, get, drop)
2. Executes all free commands per player in queued order
3. Executes all active commands sorted globally by timestamp (first-to-queue wins conflicts)
4. Advances walk sequences (one step per tick)
5. Flushes pending shared depletions

**Conflict resolution:** multi-player attack on same mob or get on same item — first to queue wins (timestamp-order). Shared depletion defers to award all successful gatherers on depletion tick.

**ActionState** tracks player activity for `look` display. Timed actions (gather, combat, burn, stoke, use, rest, walk) persist until interrupted. One-tick actions (move, get, drop) clear after one tick.

Queue feedback controlled by `queue_silently` option (default on).

## Action System

Actions that interact with objects/mobs route through `StartAction()` in `action.go`:
1. Normalizes verb via `verbAliases` map (mine/chop/fish/cut → gather, talk/speak/ask → talk)
2. Multiple object types → "That's ambiguous, which one?"
3. Searches object instances in room (numbered targeting via `N.name`)
4. Falls back to mob instances if no object matches
5. Loads the behavior from YAML
6. Routes to type-specific handler (startGather, startTalk, startUse)

The `verbSkill` map maps verb → skill name for default target resolution:
- mine → mining, chop/cut → woodcutting, fish → fishing

### Action Types

| ActionType | Trigger | Description |
|---|---|---|
| `gathering` | mine/chop/cut/fish | Resource gathering with skill checks, tool reqs, depletion |
| `combating` | attack/kill | Combat with attack/defense rolls |
| `using` | use | Crafting — consume items, produce output |
| `talking` | talk/speak/ask | NPC conversation trees with choices/conditions/actions |
| `burning` | burn | Firemaking startup (3 phases) |
| `stoking` | stoke | Adding logs to existing fire |
| `searching` | search | Search bird's nests / items with search_table |
| `resting` | quit | 10-tick rest before disconnect |
| `walking` | walk | Multi-step movement (one dir per tick) |
| `moving` | n/s/e/w/u/d | Multi-tick movement state |
| `picking_up` | get | One-tick pickup state |
| `dropping` | drop | One-tick drop state |
| `cooking` | cook | Cooking food on fire/range |
| `smelting` | smelt | Smelting ore into bars at furnace |
| `smithing` | smith | Smithing bars into items at anvil |
| `cleaning` | clean | Cleaning grimy herbs (background action) |
| `mixing` | mix | Mixing potions (Pharmacy) |
| `constructing` | construct/make | Construction via production system (workbench) |

### Behavior Types (YAML-driven)

| Type | Verbs | Use |
|---|---|---|
| `gather` | mine, chop, cut, fish | Resource gathering with skill checks, tool requirements, depletion/respawn |
| `use` | use | Crafting stations — consume items, produce output, optional skill checks |
| `talk` | talk, speak, ask | NPC conversation trees with choices, conditions, actions |

### Behaviors Not in YAML (hardcoded)

| Action | File | Description |
|---|---|---|
| burn | `action_burn.go` | 3-phase firemaking: drop log → try burn → skill check → create fire object |
| stoke | `action_burn.go` | Add logs to fire, XP per log, increments fire quality |
| search | `action_search.go` | Search items with search_table, consumes one, rolls on drop table |
| cook | `action_production.go` | Recipe-driven cooking on fire/range stations |
| smelt | `action_production.go` | Recipe-driven smelting of ore into bars at furnace |
| smith | `action_production.go` | Recipe-driven smithing of bars into items at anvil (requires hammer) |
| steal | `action_steal.go` | Thieving: pickpocket mobs, steal from objects, guard watching, sneak mode |

### GatherConfig Fields

| Field | Description |
|---|---|
| `skill` | Skill name for level check |
| `level` | Required level |
| `xp` | XP per successful gather |
| `base_wait` | Base ticks per action cycle |
| `tools` | Required tool_type list |
| `bait` | Required bait item |
| `success` | SuccessFormula (base + per_level, capped) |
| `drops` | Weighted drop entries (item_id, table ref, depletes, quantity, message, level, xp) |
| `respawn_timer` | Ticks until depleted object respawns |
| `deplete_timer` | Ticks for shared depletion (trees) |
| `nest_chance` | 1/N chance for bird's nest alongside normal drop |
| `gather_message` | Custom "You gather..." message |
| `depleted_message` | Custom "The rock is depleted" message |
| `exhausted_message` | Custom "The tree falls" message |
| `fail_message` | Custom failure message |
| `respawn_broadcast` | Broadcast message when object respawns |

### SuccessChance Formula

`SuccessChance(cfg SuccessFormula, level int, requiredLevel int) float64`:
```
chance = cfg.Base + (level - requiredLevel) * cfg.PerLevel
clamped to [0, cfg.Cap]
```

### Node Actions (talk dialog)

| Field | Effect |
|---|---|
| `set_flags` | Sets world flags (global) |
| `set_player_flags` | Sets player-local flags (per-character, saved to YAML) |
| `give_item` | Gives an item to inventory |
| `take_item` | Removes an item from inventory |
| `teleport` | Moves player to a room ID |
| `heal` | Restores hitpoints |
| `cost` | Deducts credits from player |
| `shop` | Opens a buy/sell interface (see Shop section) |

### Condition System

Used by exits, talk options, on-enter scripts, and use_interactions checks:

| Field | Scope | Example |
|---|---|---|
| `flag` | World (shared by all players) | `flag: gate_open` |
| `player_flag` | Per-character (quest progress) | `player_flag: finished_tutorial` |
| `has_item` | Player inventory check | `has_item: bronze_key` |
| `all_of` | All sub-conditions must pass | Nested list |
| `any_of` | Any sub-condition passes | Nested list |
| `not` | Invert the check | `not: true` |

### Firemaking (burn/stoke)

See `internal/game/action_burn.go`.

**Burn flow (3 phases):**
- Phase 0 (inventory only): Drops 1 log to ground, outputs "You drop the X and begin to make a fire..."
- Phase 1: "You try burning the X on the ground..." (waits tool_speed ticks)
- Phase 2: Skill check (chance = 0.5 + (level - fireLevel) * 0.02, capped [0.05, 0.95]). On success creates `fire` object (quality = log's burn_ticks), gives XP, broadcasts. On fail retries Phase 1.

**Stoke flow:** 10-tick loop → "You throw X onto the fire", gives XP, adds burn_ticks/2 to fire quality. Ends when out of item.

**Fire objects:** Created via `World.AddObjInstance()`, tracked by `ObjState.Quality`. Each tick `FireTick()` decrements quality; at 0, `RemoveObjInstance()` cleans up and drops `removal_item` (e.g., ashes).

**Fire tools:** `matches` (stackable, consumed), `firesteel` (non-consumable), `lighter` (quality-based, `MaxQuality: 100`, decreases per use). Tool search: main hand → inventory.

**Item fields for firemaking:** `burn_ticks`, `fire_level`, `fire_xp`, `quality`, `max_quality`.

## Two Depletion Mechanics

**Per-drop depletion** (mining, regular trees): Set `depletes: true` on a drop entry. The resource depletes on first successful gather of that drop.

**Shared depletion** (higher-tier trees): Set `deplete_timer: <ticks>` 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. Timer regenerates when no one is chopping. Managed by `SharedDepletionTick` in `tick.go`.

## Ground Item System

- `DropDespawnTicks = 1000` — dropped items despawn after 1000 ticks
- `ReserveTicks = 100` — mob loot is reserved for the killer for 100 ticks
- Items with same ID in the same room are NOT merged — each entry has independent despawn timer
- Spawn items respawn after their respawn delay; nearby matching items are merged on respawn
- Despawn timers visible via `despawn` option; reserve info via `reserve` option

## Combat System

**Attack types.** Weapons have an `attack_type` field (stab/slash/crush/ranged/science). The attack type determines which of the player's 5 attack bonuses is used for accuracy and which of the mob's 5 defense bonuses is used. Equipment stats use per-type fields: `stab_attack`, `slash_attack`, `crush_attack`, `science_attack`, `ranged_attack` (and matching defense fields).

**OSRS accuracy formula.** `HitChance(attackRoll, defenseRoll)` uses a continuous probability curve: if `a > d`, chance = `1 - (d+2)/(2*(a+1))`; otherwise `a/(2*(d+1))`. Equal rolls ≈ 50% hit chance.

**Ranged combat.** When `weapon_type` is "ranged", uses Ranged level for attack rolls, `ranged_attack` for accuracy, `ranged_strength` from ammo for max hit. Consumes 1 ammo per attack. If ammo runs out, combat ends. XP: 75% Ranged, 25% Hitpoints (all styles).

**Aggressive mobs.** Mobs with `aggressive: true` auto-attack players entering their room (1-tick delay). Only aggros if `playerLevel <= mobLevel * 2` (OSRS rule). Checked on room enter and login via `checkAggro()`.

**Equipment requirements.** Items can have `requirements: { attack: 20, defense: 10 }`. Checked in `doWear` and `doWearAll` before equipping. Displayed when examining items.

**Technology in combat.** Active tech boosts (Clarity, Amplifier, etc.) add percentage-based level bonuses to attack/strength/defense/ranged. Protection techs (Kinetic Barrier, Projectile Screen, Neural Firewall) reduce incoming damage by 40%. Dead Man's Switch deals 25% max HP damage to the mob on player death.

**Fleeing combat:** Players can move in any direction to attempt to flee. Movement takes the normal tick delay (default 4, reduced by equipment). During the countdown, the mob continues attacking. If the mob lands a hit, the escape fails ("Can't escape!") and combat resumes. If no hit lands, the player escapes. With Cape of Agility, fleeing is instant. The `run_countdown` option shows tick-by-tick countdown messages.

**Death mechanic:** Player drops credits to ground. If player has >3 items (inventory + equipment), the 3 most valuable are kept and rest are dropped. Player teleports to room 1 at full HP. All active techs deactivated on death.

**XP formula:** `baseXP = dmg * 4`, distributed by attack style:
- Accurate: 75% Attack, 25% Hitpoints
- Aggressive: 75% Strength, 25% Hitpoints
- Defensive: 75% Defense, 25% Hitpoints
- Balanced: 25% each Attack/Strength/Defense/Hitpoints
- Ranged (all styles): 75% Ranged, 25% Hitpoints

**Mob combat level:** `base = (def + hp) / 4`, `offensive = max(melee=(atk+str)/4, ranged=rng*3/8, science=sci*3/8)`, `level = floor(base + offensive)`.

**Player combat level:** Ranged-or-melee dominant calculation. Includes Technology (0.25) and Science (0.125).

**Mob respawn:** Default 30 ticks. Broadcasts spawn messages if `mob_spawn` option is on.

**Mob DropTable:** `Remains` (guaranteed drop item), `Loot` (weighted DropEntry table).

## Option System

Account-wide options set via `option <name> <value>`. Options are stored in the account YAML and shared by all characters on the same account.

| Option | Type | Default | Description |
|---|---|---|---|
| `description` | bool | true | Long room descriptions when moving |
| `tiny_map` | string | "right" | off/right/left — mini-map display |
| `xp_drops` | bool | true | XP drop messages |
| `exits` | bool | true | Long exit display in look |
| `mob_enter` | bool | true | Messages when mobs enter the room |
| `mob_leave` | bool | true | Messages when mobs leave the room |
| `mob_spawn` | bool | true | Messages when mobs spawn |
| `reserve` | bool | true | Show full reserved item details |
| `depletion` | bool | false | Show depletion and despawn timers |
| `despawn` | bool | false | Show ground item despawn timers |
| `color` | string | "xterm256" | none/ansi/xterm256 — color output mode |
| `mapwidth` | int | 30 | Map viewport width |
| `mapheight` | int | 20 | Map viewport height |
| `mappadding` | string | "none" | none/x/y/xy — blank-row stripping |
| `automap` | bool | false | Show map automatically after moving |
| `queue_silently` | bool | true | Suppress queue messages |
| `room_desc_width` | int | 70 | Room desc line wrap width |
| `unicode` | bool | true | Unicode box-drawing characters |
| `run_countdown` | bool | false | Show countdown messages when fleeing combat |
| `visual_ticks` | bool | false | Display a tick marker every game tick |
| `visual_tick_count` | int | 0 | Cycle length for tick counter (0 = no counter) |
| `visual_tick_text` | string | "TICK" | Text displayed for visual ticks |

Prompt is NOT an option — it is a per-character setting via the `prompt` command. Default: `"> "`. `prompt none` sets it to blank. Stored in character YAML as `prompt:`.

Prompt variables: `%h` (HP), `%H` (max HP), `%b` (battery), `%B` (max battery), `%c` (credits), `%i` (free slots), `%s` (style short), `%S` (style long), `%m` (mob HP), `%M` (mob max HP), `%X_<skill>` (XP), `%x_<skill>` (XP to next).

New accounts are asked "Should I disable color? [y/N]" after password creation. Pressing enter defaults to No (xterm256 enabled). Choosing Y sets color to "none".

## ItemDef Fields

From `internal/object/item.go`:

| Field | Description |
|---|---|
| `id` | Unique identifier |
| `name` | Display name |
| `aliases` | Alternate name prefixes for matching |
| `description` | Item description |
| `value` | Credit value |
| `stackable` | Can stack in inventory |
| `equip_slot` | head/neck/torso/legs/hands/feet/back/ammo/main_hand/off_hand/ring |
| `weapon_type` | "melee" / "ranged" / "science" |
| `attack_type` | "stab" / "slash" / "crush" / "ranged" / "science" |
| `stats` | Per-type attack/defense bonuses, strength, ranged strength, science damage, technology bonus |
| `speed` | Attack speed |
| `requirements` | Skill level requirements to equip (e.g., `{attack: 20, defense: 10}`) |
| `tool_type` | Tool type string for gather requirements |
| `tool_speed` | Speed bonus for gathering |
| `burn_ticks` | Burn duration for firemaking |
| `fire_level` | Required firemaking level |
| `fire_xp` | XP for burning |
| `quality` | Default quality (e.g., lighter butane) |
| `max_quality` | Maximum quality |
| `search_table` | Drop table for searching this item |
| `search_misc_table` | Secondary drop table |
| `search_ticks` | Ticks per search action |
| `search_message` | Custom search message |
| `made_from` | MadeFrom entries for item-on-item combinations (byproducts supported) |
| `ticks` | Ticks per production cycle for MadeFrom combines (default 2) |

## ObjectDef Fields

From `internal/object/object.go`:

| Field | Description |
|---|---|
| `id` | Unique identifier |
| `name` | Display name |
| `behavior` | Behavior ID for interaction |
| `hidden` | Interactable but not shown in room listing |
| `inroom_description` | Custom "A X is here." text |
| `removal_item` | Item dropped when instance is removed (fire → ashes) |
| `description` | Text shown when examining the object (supports `{quality}` placeholder for quality-based objects) |
| `use_interactions` | List of item-on-object interactions with conditions and actions (see worldbuilding guide) |

## World ObjState Fields

From `internal/world/world.go`:

| Field | Description |
|---|---|
| `DefID` | Object definition ID |
| `Name` | Display name |
| `Index` | Index for duplicate objects in same room |
| `RoomID` | Current room |
| `Depleted` | Resource is depleted |
| `DepleteTimer` | Ticks until respawn |
| `SharedMax` | Max shared depletion timer |
| `SharedTimer` | Current shared timer value |
| `WanderRooms` | Rooms for object wandering |
| `WanderInterval` | Ticks between wanders |
| `Quality` | Fire quality, resource health, etc. |
| `JustRespawned` | Flag for respawn broadcast |

## Session States

From `internal/net/server.go`:

| State | Purpose |
|---|---|
| `StateAccountName` | Entering account name |
| `StatePassword` | Entering password |
| `StateNewAccountPass` | Setting password for new account |
| `StateNewAccountConfirm` | Confirming password |
| `StateColorChoice` | New account: "Should I disable color?" |
| `StateMenu` | Main menu |
| `StateNewCharName` | Naming new character |
| `StateRenameAccount` | Renaming account |
| `StateRenameChar` | Selecting character to rename |
| `StateRenameCharName` | Entering new character name |
| `StateDeleteChar` | Confirming character deletion |
| `StatePurgeAccount` | Confirming account purge |
| `StateGame` | In-game command mode |
| `StateChangeDescription` | Setting player description |
| `StateTalk` | NPC conversation input |
| `StateDropAllConfirm` | Confirming `drop all` |
| `StateRecipeChoice` | Recipe/product selection table menu (number or name input, enter cancels) |
| `StateHowMany` | "How many?" production count prompt |
| `StateSmithProduct` | Smith product selection with numbered table (#, name, or partial name input) |
| `StateShop` | Buy/sell/browse in shop (buy, sell, browse, leave commands) |
| `StateBank` | Bank interface (deposit, withdraw, browse, leave commands) |
| `StateHacking` | Jacked into a terminal running a minigame |
| `StateColorChoice` | New account color preference |

## Adding a New Skill

1. Add `SkillName` constant + entry in `AllSkills` + `SkillAbbr` in `internal/player/player.go`
2. Create a gather behavior YAML in `data/behaviors/`
3. Create an object YAML referencing that behavior in `data/objects/`
4. Create an item for the tool in `data/items/` (with `tool_type`)
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 `deplete_timer` for tree-style depletion, or use per-drop `depletes: true` for rock-style depletion.

## Adding a New Production Skill

Production skills (cooking, smelting, smithing) share a unified system in `action_production.go`:

1. Create recipe YAMLs in `data/recipes/` with the new `type` (e.g., `type: fletching`)
2. Create a station object in `data/objects/` if needed
3. Add a `cmd_<skill>.go` command handler following the `cmd_cook.go` pattern
4. Add the command to `classifyCommand()` and `executeCommand()` in `game.go`
5. Add the action type string to `AdvanceActions` in `action.go`
6. Add a case in `startProductionFromRecipe()` for default messages

The unified production cycle handles: "How many?" prompt, start message, timed loops, success/fail rolls, XP, output quantity, stackable stacking, byproducts, and end message. Tool requirements (e.g., hammer for smithing, needle for crafting) are checked in the command handler before calling `promptHowMany`.

## Adding a New Command

1. Add a `cmd_*.go` file in `internal/game/` with the handler
2. Add a case in `handleGameCommand()` and entry in `classifyCommand()` in `internal/game/game.go`
3. Update `data/help/` YAML files

## Skills (23 total, 1-99, RSC XP table)

| Category | Skills |
|---|---|
| Combat | Attack, Strength, Defense, Hitpoints, Ranged, Science, Technology, Assassin |
| Gathering | Fishing, Woodcutting, Mining, Hacking, Scavenging, Farming, Thieving |
| Production | Cooking, Smithing, Crafting, Fletching, Pharmacy, Construction, Firemaking |
| Utility | Agility |

Implemented: Mining, Fishing, Woodcutting, Firemaking, Cooking, Smithing (smelting + smithing), Fletching, Pharmacy (herb cleaning + potion mixing), Technology (25 techs, battery drain, 1-tick flicking, combat integration), Construction (planks, furniture, player houses), Agility (3 obstacle courses, 9 verbs, lap tracking), Hacking (3 minigames, terminals, StateHacking). The rest are stubs (skill defined, XP tracked, but no behaviors/objects/items yet).

## Places to Be Careful

- `StartAction` searches objects first, then mobs. A mob must have `behavior:` set on its YAML def to be interactable.
- Exits changed from `map[ExitDir]int` to `map[ExitDir]ExitDef` — old `north: 2` still works via custom `UnmarshalYAML`. Same pattern for `RoomMob`.
- `checkCondition` is the single condition evaluator — used by exits, talk options, on-enter scripts, and use_interactions checks.
- Object `Hidden: true` means the object doesn't appear in room listings but is still interactable.
- Alias expansion happens before command dispatch and can shadow built-in commands.
- `say` preserves case (alias expansion preserves case, dispatch extracts original input text).
- `get`, `drop`, and `quit` cancel the player's active action (gathering, use, etc.).
- `findGroundMatches` and `findInventoryMatches` support bidirectional prefix matching — `"iron ax"` matches `"iron axe"`.
- Mob wander config is per-instance in room YAML via `RoomMob`, not on `MobDef`.
- Walk distance capped by agility level (`len(dirs) > agilityLevel`).
- `wear all` auto-equips the highest-value item per slot from inventory.
- `remove all` unequips everything if inventory has room.
- Movement takes multiple ticks (default 4, reduced by Graceful set and Cape of Agility). Cape of Agility makes movement instant (1 tick). Graceful pieces each reduce by 0.25 ticks; full set bonus adds 0.5 for 2 ticks total. Cape overrides Graceful.
- During combat, movement is a flee attempt. Mob hits during the countdown abort the flee ("Can't escape!").
- Level-up messages output `*** You are now level N <skill>! ***` across all skills that gain XP.

Skills provide specialized instructions and workflows for specific tasks.