From a5588ca21b9b7804db7b3c37fc03c4763594076e Mon Sep 17 00:00:00 2001 From: Jared Miller Date: Sat, 14 Feb 2026 18:20:53 -0500 Subject: [PATCH] Add builder manual for content creation workflow --- docs/builder-manual.md | 408 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 docs/builder-manual.md diff --git a/docs/builder-manual.md b/docs/builder-manual.md new file mode 100644 index 0000000..e08a240 --- /dev/null +++ b/docs/builder-manual.md @@ -0,0 +1,408 @@ +# 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 ` - (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/.toml` +- Marked safe (no combat) +- Commands that only work in YOUR home zone: + - `terrain ` - paint the tile under your feet. Can't edit border walls. Common tiles: `.` grass, `~` water, `^` mountain, `T` tree, `,` dirt, `"` tall grass, `+` path + - `describe ` - set zone description (max 500 chars). Bare `describe` shows current. + - `furnish ` - place an item from your inventory as furniture at your position + - `unfurnish ` - pick furniture back up into inventory + +## Building Zones (Admin) + +### Creating a Zone +- `@dig ` - 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 ` - 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 ` - 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/.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 ` 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 ` (optional) +- `tags` - arbitrary tags list (optional) + +### Item Commands + +- `get ` / `take ` - pick up from ground +- `drop ` - drop to ground +- `inventory` / `i` - list what you're carrying +- `get from ` - take from container +- `put in ` - put into container +- `open ` / `close ` + +## 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 ` - 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 ` - 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 ` +- `ingredients` - list of thing template names (duplicates = need multiple) +- `result` - thing template name to spawn + +### Commands + +- `recipes` - list all recipes +- `recipes ` - show ingredients and result +- `craft ` - 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 ` - 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 ` - 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 ` - start conversation with an NPC +- `reply ` - choose a dialogue option + +### Other + +- `fly` - toggle flying +- `alias ` - create shortcut (e.g., `alias pr punch right`) +- `unalias ` - remove alias +- `play ` - play interactive fiction +- `edit` - in-world text editor +- `read ` - 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 ` | +| Create zone (admin) | `@dig ` | +| Paint mode (admin) | `@paint`, `brush `, `p` to toggle | +| Save zone (admin) | `@save` | +| Place thing (admin) | `@place ` | +| Home terrain | `terrain ` | +| Home description | `describe ` | +| Furnish/unfurnish | `furnish ` / `unfurnish ` | +| Spawn mob | `spawn ` | +| Inventory | `i` or `inventory` | +| Pick up / drop | `get ` / `drop ` | +| Craft | `craft ` | +| Recipes | `recipes` / `recipes ` | +| Score | `score` or `stats` | +| Skills | `skills` | +| Help | `help ` | +| Power | `power up/down/stop/` | +| Rest / Sleep | `rest` / `sleep` / `wake` | +| Attack | `punch left ` | +| Defend | `dodge left` | +| Reload content | `reload ` | +| Aliases | `alias ` / `unalias ` | + +## 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) +```