mud/docs/builder-manual.md

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:

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:

name = "chair"
description = "a simple wooden chair with a woven seat"
portable = true

Non-portable (furniture/fixture):

name = "fountain"
description = "a weathered stone fountain, water trickling into a mossy basin"
portable = false

Container:

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

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:

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

name = "punch"
description = "a close-range strike with the fist, quick but predictable"
move_type = "attack"
stamina_cost = 5.0
hit_time_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:

name = "dodge"
description = "a quick sidestep to evade incoming attacks"
move_type = "defense"
stamina_cost = 3.0
active_ms = 800
recovery_ms = 2700

[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
• hit_time_ms - (attacks) time in ms from initiation to impact
• active_ms - (defenses) how long defense blocks once activated, in ms
• recovery_ms - (defenses) lockout after active window ends, in ms
• 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/:

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)