408 lines
12 KiB
Markdown
408 lines
12 KiB
Markdown
# 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)
|
|
```
|