# Builder Manual

This is your reference for creating content in the MUD. Covers getting around, building zones, placing things, combat moves, mobs, crafting recipes. Keep this open while building - it's meant to be practical and scannable.

## Getting Around

- Movement: `n`, `s`, `e`, `w`, `ne`, `nw`, `se`, `sw` (or long forms like `north`)
- `look` or `l` - see the room (ASCII viewport with `@` as you, `*` as others)
- `home` - teleport to your personal home zone (created on first use, 9x9 grid)
- `home return` - go back to where you were before `home`
- `@goto <zone>` - (admin) teleport to any zone by name. Goes to spawn point. Examples: `@goto hub`, `@goto tavern`, `@goto overworld`
- Portals: step onto a portal tile to auto-teleport to another zone. Defined in zone TOML files.

Existing zones: overworld (1000x1000, toroidal, procedural terrain), hub, tavern, treehouse, flower

## Your Home Zone

- `home` creates a 9x9 zone with `#` walls and `.` grass on first use
- Saved to `data/player_zones/<name>.toml`
- Marked safe (no combat)
- Commands that only work in YOUR home zone:
  - `terrain <tile>` - paint the tile under your feet. Can't edit border walls. Common tiles: `.` grass, `~` water, `^` mountain, `T` tree, `,` dirt, `"` tall grass, `+` path
  - `describe <text>` - set zone description (max 500 chars). Bare `describe` shows current.
  - `furnish <item>` - place an item from your inventory as furniture at your position
  - `unfurnish <item>` - pick furniture back up into inventory

## Building Zones (Admin)

### Creating a Zone
- `@dig <name> <width> <height>` - creates a blank zone and teleports you there
- The zone starts as all `.` (grass) with `#` borders
- You're placed at (0,0)

### Painting Terrain
- `@paint` - toggle paint mode
- `brush <char>` - set what tile you're painting (e.g., `brush ~` for water)
- `p` - toggle between painting mode and survey mode
- In painting mode, every tile you walk over gets painted with your brush
- In survey mode, you move without painting (to get to a new area)

### Placing Objects
- `@place <thing>` - place a thing template at your current position
- Available thing templates: chair, bookshelf, chest, fountain, lamp, painting, rug, table, rock, sack, plank, nail

### Saving
- `@save` - saves current zone to `content/zones/<name>.toml`
- Home zones auto-save on furnish/unfurnish/terrain/describe

### Zone TOML Format

Here's the full format using the tavern as an example:

```toml
name = "tavern"
description = "a cozy tavern with a crackling fireplace"
width = 8
height = 6
toroidal = false
safe = true
spawn_x = 1
spawn_y = 1

[terrain]
rows = [
    "########",
    "#......#",
    "#......#",
    "#......#",
    "#......#",
    "####.###",
]

[terrain.impassable]
tiles = ["#"]

[[portals]]
x = 4
y = 5
target = "hub:14,7"
label = "the tavern door"

[ambient]
interval = 60
messages = [
    "the fire crackles and pops in the hearth",
    "a draft of cold air blows through the room",
    "you hear muffled conversation from patrons in the corner",
    "the smell of roasting meat and ale fills the air",
]
```

**Field Reference:**

- `name` - unique identifier, used by @goto and portal targets
- `description` - shown in the Where: header when you look
- `width`/`height` - grid dimensions
- `toroidal` - true = wraps at edges (overworld does this), false = walls at edges
- `safe` - true = no combat allowed
- `spawn_x`/`spawn_y` - where players land when teleporting in
- `[terrain]` - `rows` is a list of strings, each string is one row. Each character is a tile.
- `[terrain.impassable]` - `tiles` lists which characters block movement
- `[[portals]]` - each portal has x, y position, target as "zone_name:x,y", and a label
- `[ambient]` - interval (seconds) and messages (random pick) for atmospheric text
- Can also have `[[spawn_rules]]` for mobs (see Mobs section)

### Connecting Zones

Portals are the main way to connect zones. To make a two-way connection:

1. Add a portal in zone A pointing to zone B
2. Add a portal in zone B pointing back to zone A
3. Example: hub has `target = "tavern:4,5"` and tavern has `target = "hub:14,7"`

Portal target format: `"zone_name:x,y"` where x,y is the destination tile.

## Things (Items & Furniture)

### Existing Templates

chair, bookshelf, chest, fountain, lamp, painting, rug, table, rock, sack, plank, nail

### Creating New Templates

Add a `.toml` file in `content/things/`:

**Simple item:**
```toml
name = "chair"
description = "a simple wooden chair with a woven seat"
portable = true
```

**Non-portable (furniture/fixture):**
```toml
name = "fountain"
description = "a weathered stone fountain, water trickling into a mossy basin"
portable = false
```

**Container:**
```toml
name = "chest"
description = "a sturdy wooden chest with iron bindings"
portable = false
capacity = 5
closed = true
locked = false
aliases = ["box"]
```

**Fields:**

- `name` - identifier and display name
- `description` - what `look <thing>` shows
- `portable` - can it be picked up? (true/false)
- `aliases` - alternative names for targeting (optional)
- `capacity` - makes it a container with N slots (optional)
- `closed` / `locked` - container state (optional)
- `readable_text` - text shown by `read <thing>` (optional)
- `tags` - arbitrary tags list (optional)

### Item Commands

- `get <item>` / `take <item>` - pick up from ground
- `drop <item>` - drop to ground
- `inventory` / `i` - list what you're carrying
- `get <item> from <container>` - take from container
- `put <item> in <container>` - put into container
- `open <container>` / `close <container>`

## Mobs

### Existing Templates

- training_dummy - PL 200, stamina 100, no moves (punching bag)
- goblin - PL 50, stamina 40, knows punch and sweep, drops crude club and gold
- librarian - PL 50, stamina 50, NPC with schedule and dialogue

### Spawning

- `spawn <mob>` - spawn a mob at your position (e.g., `spawn goblin`)

### Creating New Mob Templates

Add a `.toml` file in `content/mobs/`:

```toml
name = "goblin"
description = "a snarling goblin with a crude club"
pl = 50.0
stamina = 40.0
max_stamina = 40.0
moves = ["punch left", "punch right", "sweep"]

[[loot]]
name = "crude club"
chance = 0.8
description = "a crude wooden club"

[[loot]]
name = "gold coin"
chance = 0.5
min_count = 1
max_count = 3
```

**Fields:**

- `name` / `description` - identity
- `pl` - power level (health + damage scaling)
- `stamina` / `max_stamina` - fuel for moves
- `moves` - list of combat moves it can use (must match move names including variant, e.g., "punch left")
- `[[loot]]` - each entry: `name`, `chance` (0.0-1.0), optional `description`, `min_count`, `max_count`

### Zone Spawn Rules

Add to a zone TOML to auto-spawn mobs:

```toml
[[spawn_rules]]
template = "goblin"
max_count = 3
region = { x_min = 2, x_max = 12, y_min = 2, y_max = 12 }
```

## Combat Moves

### Existing Moves

Attacks: punch (left/right), roundhouse, sweep
Defenses: dodge (left/right), parry, duck, jump

### Creating New Moves

Add a `.toml` file in `content/combat/`:

**Attack with variants:**

```toml
name = "punch"
description = "a close-range strike with the fist, quick but predictable"
move_type = "attack"
stamina_cost = 5.0
timing_window_ms = 1800
damage_pct = 0.15

[variants.left]
telegraph = "{attacker} retracts {his} left arm..."
announce = "{attacker} throw{s} a left hook at {defender}!"
resolve_hit = "{attacker} connect{s} with a left hook!"
resolve_miss = "{defender} dodge{s} {attacker}'s left hook!"
countered_by = ["dodge right", "parry high"]

[variants.right]
telegraph = "{attacker} retracts {his} right arm..."
announce = "{attacker} throw{s} a right hook at {defender}!"
resolve_hit = "{attacker} connect{s} with a right hook!"
resolve_miss = "{defender} dodge{s} {attacker}'s right hook!"
countered_by = ["dodge left", "parry high"]
```

**Simple defense:**

```toml
name = "dodge"
description = "a quick sidestep to evade incoming attacks"
move_type = "defense"
stamina_cost = 3.0
timing_window_ms = 800

[variants.left]

[variants.right]
```

**Fields:**

- `name` - command name (what the player types)
- `description` - shown in help/skills
- `move_type` - "attack" or "defense"
- `stamina_cost` - stamina consumed per use
- `timing_window_ms` - how long the window is open (attacks: time to defend, defenses: commitment time)
- `damage_pct` - fraction of attacker's PL dealt as damage (attacks only)
- `[variants.X]` - each variant becomes a separate command: "punch left", "punch right"
- POV templates: `{attacker}`, `{defender}`, `{s}` (third person s), `{es}`, `{his}`, `{him}`, `{y|ies}` (irregular conjugation)
- `countered_by` - list of defense moves that counter this attack variant
- Unlock conditions (optional): `unlock_type = "kill_count"`, `unlock_value = 10` (need 10 kills to learn)

### Hot Reloading

- `reload <name>` - reload a combat move or command TOML without restarting the server
- Example: `reload punch` after editing punch.toml

## Crafting Recipes

### Existing Recipes

- wooden_table: 3 planks + 2 nails = table

### Creating New Recipes

Add a `.toml` file in `content/recipes/`:

```toml
name = "wooden_table"
description = "Craft a sturdy table from planks and nails"
ingredients = ["plank", "plank", "plank", "nail", "nail"]
result = "table"
```

**Fields:**

- `name` - recipe identifier
- `description` - shown in `recipes <name>`
- `ingredients` - list of thing template names (duplicates = need multiple)
- `result` - thing template name to spawn

### Commands

- `recipes` - list all recipes
- `recipes <name>` - show ingredients and result
- `craft <name>` - craft it (consumes ingredients from inventory, spawns result)

## Other Useful Commands

### Stats & Info

- `score` / `stats` / `profile` - character sheet (PL, stamina, K/D, time played, unlocked moves)
- `skills` - list combat moves (shows locked/unlocked)
- `commands` / `cmds` - list all available commands
- `help <command>` - detailed info on any command or move
- `client` - show terminal/protocol capabilities

### Power System

- `power up` - spend stamina to raise PL toward max (tick-based, visible aura)
- `power down` - drop PL to minimum (hide from scouters)
- `power <number>` - set PL to exact value
- `power stop` - cancel ongoing power-up

### Recovery

- `rest` - toggle resting (faster stamina recovery, can still see room)
- `sleep` / `wake` - toggle sleeping (fastest recovery, blind to room events)

### Social

- `talk <npc>` - start conversation with an NPC
- `reply <number>` - choose a dialogue option

### Other

- `fly` - toggle flying
- `alias <name> <command>` - create shortcut (e.g., `alias pr punch right`)
- `unalias <name>` - remove alias
- `play <story>` - play interactive fiction
- `edit` - in-world text editor
- `read <thing>` - read a readable object
- `quit` / `q` - leave the game

## Quick Reference

| What | Command |
|------|---------|
| Move | `n` `s` `e` `w` `ne` `nw` `se` `sw` |
| Look | `look` or `l` |
| Go home | `home` / `home return` |
| Teleport (admin) | `@goto <zone>` |
| Create zone (admin) | `@dig <name> <w> <h>` |
| Paint mode (admin) | `@paint`, `brush <char>`, `p` to toggle |
| Save zone (admin) | `@save` |
| Place thing (admin) | `@place <thing>` |
| Home terrain | `terrain <tile>` |
| Home description | `describe <text>` |
| Furnish/unfurnish | `furnish <item>` / `unfurnish <item>` |
| Spawn mob | `spawn <mob>` |
| Inventory | `i` or `inventory` |
| Pick up / drop | `get <item>` / `drop <item>` |
| Craft | `craft <recipe>` |
| Recipes | `recipes` / `recipes <name>` |
| Score | `score` or `stats` |
| Skills | `skills` |
| Help | `help <command>` |
| Power | `power up/down/stop/<number>` |
| Rest / Sleep | `rest` / `sleep` / `wake` |
| Attack | `punch left <target>` |
| Defend | `dodge left` |
| Reload content | `reload <name>` |
| Aliases | `alias <name> <cmd>` / `unalias <name>` |

## Content File Locations

```
content/
  combat/       - attack and defense move definitions
  commands/     - TOML command metadata
  mobs/         - mob templates
  recipes/      - crafting recipes
  things/       - item and furniture templates
  zones/        - zone definitions
  dialogue/     - NPC dialogue trees

data/
  player_zones/ - saved home zones (auto-generated)

worlds/
  earth/        - world config (seed, dimensions)
```