# Third Collapse

A low-tech sci-fi MUD set on a terraformed asteroid. Runescape-style combat and skill progression, written in Go.

## Theme

Not generic fantasy. Takes place on a terraformed asteroid. Technology has regressed — people scrap and scavenge remnants of the old world. "Science" replaces Prayer, "Technology" replaces Magic. Scavenging replaces Runecrafting.

## Skills (21 total, all go from 1-99)

```
Combat:    Attack, Strength, Defense, Hitpoints, Ranged, Science, Technology
Gathering: Fishing, Woodcutting, Mining, Hunter, Scavenging
Production: Cooking, Smithing, Crafting, Fletching, Alchemy, Construction
Utility:    Thieving, Agility, Slayer
```

## Architecture

```
cmd/mud/              Entry point
internal/
  action/             Behavior system: gather/talk/use/toggle types, drop tables
  engine/             Tick scheduler (600ms)
  world/              Rooms, exits, ground items, mobs, object instance state
  player/             Character sheet, skills, XP, inventory, equipment
  combat/             Combat formulas, combat state tracking
  object/             ItemDef, ObjectDef, item/object stores
  net/                Telnet server, sessions, room-based player hub
  game/               Session handler, login flow, command dispatch, action tick
data/
  behaviors/          Behavior YAML files (gather, talk, use, toggle)
  drops/              Shared drop table YAML files
  rooms/              Room YAML files
  objects/            Object definition YAML files
  items/              Item definition YAML files
  mobs/               Mob definition YAML files
  help/               Help topic YAML files
  players/
    accounts/         Account YAML files (gitignored)
    characters/       Character YAML files (gitignored)
```

## Behavior System

Objects and mobs in rooms can have behaviors. Four types exist:

| Type | Verbs | Use |
|------|-------|-----|
| `gather` | mine, chop, 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 |
| `toggle` | pull, push | Levers, switches, gates — set world flags, conditional on existing values |

Behaviors are defined in `data/behaviors/<id>.yaml`. Objects reference them with `behavior: <id>`. Mobs can also carry `behavior: <id>` — StartAction falls back to mob lookup when no object matches.

### Condition System

Used by exits, talk options, on-enter scripts, and toggle 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 of conditions |
| `any_of` | Any sub-condition passes | Nested list of conditions |
| `not` | Invert the check | `not: true` |

### Node Actions (talk dialog)

Set on nodes in talk behaviors:

| 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 |

All fields in a single action are processed together.

### Accounts & Aliases

Accounts stored in `data/players/accounts/<name>.yaml`. Each account has:
- Password hash (sha256 + salt)
- Character list
- Alias map (`alias <name> <cmd>` — account-wide, shared by all characters)

Aliases resolve before built-in commands and support argument passthrough (`alias k kill` → `k man` expands to `kill man`).

### World

- Rooms are flat YAML files, read from disk on each access (live editing)
- Everything is YAML-driven — no database
- Exits support conditions (world flags, player flags, items, compound)
- Rooms support `on_enter` scripts with per-step conditions
- Objects can be `hidden: true` (interactable but not listed in room)

## Implemented

### Core Systems
- [x] Telnet server, account creation, hashed passwords, account/character management
- [x] 600ms tick engine driving all world simulation
- [x] Room-based player hub with enter/exit/action notifications
- [x] Single-login enforcement, disconnect timer
- [x] Player YAML persistence on every state change

### Commands
- [x] `look / l` — room rendering (mobs, objects, ground items, exits, players)
- [x] `look <target>` — examine mobs, objects, items, players, directions
- [x] `n/s/e/w/u/d` — movement (conditional exits, interrupts combat/actions)
- [x] `get / drop / drop all` — item pickup/drop with stacking, reservations
- [x] `say` — room chat (preserves case)
- [x] `score / inventory / equipment / exits` — character and world info
- [x] `style` — combat style selection (prefix matching)
- [x] `attack / kill <mob>` — combat with numbered targeting
- [x] `mine / chop / fish <object>` — gathering with numbered targeting
- [x] `use <object>` — crafting station interaction
- [x] `talk / speak / ask <target>` — NPC conversations (objects or mobs)
- [x] `pull / push <object>` — toggle interactions (levers, gates)
- [x] `alias <name> <cmd> / unalias <name>` — account-wide command aliases
- [x] `toggle [name]` — 8 character settings
- [x] `description / desc / help [topic] / quit`

### Combat
- [x] RSC-based formulas (attack/defense rolls, max hit)
- [x] Attack styles with bonuses and XP distribution
- [x] Equipment bonuses, HP tracking, death mechanics
- [x] Combat lock timer, movement interrupts combat
- [x] Mob/player regen (1 HP per 100 ticks)
- [x] Mob wandering, enter/leave/spawn notifications
- [x] Drop reservation system (100-tick owner lock on loot)

### Skills & Gathering
- [x] Mining (copper rocks, pickaxe, depletion/respawn, gem sub-table)
- [x] Fishing (wandering spots, non-depleting, fishing rod)
- [x] Tool system (tool_type + tool_speed on items, tool requirement on behaviors)
- [x] Shared drop tables (referenced by multiple behaviors)
- [x] 21 skill definitions with RSC XP table

### World & Data
- [x] Room, item, object, mob, behavior, drop table YAML loaders
- [x] Object instance tracking (depletion, wandering, respawn, broadcast)
- [x] 11 playable rooms with mobs, objects, spawns, and conditional exits
- [x] Conditional exits (world flags, player flags, items, compound conditions)
- [x] Room on_enter scripts with conditions
- [x] Hidden objects (interactable but not listed in room output)
- [x] Player-local flags vs world flags for multiplayer state separation
- [x] Compound conditions: all_of / any_of
- [x] Aligned ground item reservation display
- [x] Hidden object support (referenced in room descriptions, not auto-listed)

### Documentation
- [x] WORLDBUILDING.md — comprehensive guide with examples
- [x] AGENTS.md — repo structure for LLM context

## Data Format Reference

See WORLDBUILDING.md for full examples of every data type with explanations.

## Action Plan

### Phase 1: Core Skill Chains (breadth over depth)
- [ ] Woodcutting — tree objects + axes, same pattern as mining
- [ ] Cooking — fire/range object (`use` type), raw fish/meat → cooked food
- [ ] Smithing — furnace + anvil objects (`use` type), ore → bars → weapons/armor
- [ ] Fletching — fletching table object (`use` type), logs → arrow shafts/bows
- [ ] Equipment: bronze/iron weapons, axes, cooked trout, arrows, bows

### Phase 2: World Depth
- [ ] Shop system — talk node action for buy/sell interface with credits
- [ ] Bank system — deposit/withdraw items at bank booth objects
- [ ] Ranged combat — bows/crossbows/ammo, add Ranged to combat formulas
- [ ] Aggressive mobs — initiate combat on room entry
- [ ] Flee command
- [ ] Equipment skill requirements

### Phase 3: Polish
- [ ] Hunter, Thieving, Agility, Alchemy, Construction, Crafting, Scavenging
- [ ] Quest system (already supported via talk nodes + world/player flags)
- [ ] PvP combat, multi-combat zones
- [ ] ANSI color output
- [ ] Admin commands
- [ ] Persist ground items and mob state across restarts
- [ ] More rooms — flesh out the asteroid world