lily/mudserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add TOML reference docs for all world data types

Browse Source 
- world/MANIFEST.md: manifest.toml and directory layout
- world/races/RACES.md: race schema (stats, body, natural, resistances, etc.)
- world/classes/CLASSES.md: class schema (base_stats, growth, hidden, guild)
- world/guilds/GUILDS.md: guild schema and [growth]
- world/spells/SPELLS.md: spell schema and types
- world/town/REGION.md: region.toml
- world/town/rooms/ROOMS.md: room schema and exits
- world/town/npcs/NPCS.md: NPC schema, race/class resolution
- world/town/objects/OBJECTS.md: object schema and [stats]

Made-with: Cursor
This commit is contained in:
AI Agent
2026-03-14 16:40:09 -06:00
parent 7b6829b1e8
commit e5e7057650
9 changed files with 588 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
world/town/REGION.md Normal file
View File

@@ -0,0 +1,28 @@
# Region TOML Reference
Each region is a directory under `world/` (e.g. `world/town/`) containing a `region.toml` file. The directory name is the region ID (e.g. `town`). Room, NPC, and object IDs in this region are prefixed with `"<region>:"` (e.g. `town:tavern`).
## Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name of the region (e.g. for logs or future use). |
Additional keys (e.g. `description`) may be present in the file; only `name` is required by the loader.
## Example
```toml
name = "Thornwall"
description = "A fortified trading town at the crossroads of the known world."
```
## Region contents
Place TOML files in these subdirectories of the region folder:
- `rooms/*.toml` — room definitions (see `rooms/ROOMS.md`)
- `npcs/*.toml` — NPC definitions (see `npcs/NPCS.md`)
- `objects/*.toml` — object definitions (see `objects/OBJECTS.md`)
The server loads all regions whose folder contains a `region.toml` file.

89
world/town/npcs/NPCS.md Normal file
View File

@@ -0,0 +1,89 @@
# NPC TOML Reference
Each file in a region’s `npcs/` folder (e.g. `world/town/npcs/`) defines one NPC template. The NPC ID is `"<region>:<filename_stem>"` (e.g. `barkeep.toml` in region `town` → `town:barkeep`). Race and class are resolved at **spawn time** (and again on respawn if not fixed); omit them for random selection.
## Top-level fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Display name. |
| `description` | string | Yes | — | Shown when the player looks at or examines the NPC. |
| `room` | string | Yes | — | Full room ID where the NPC appears (e.g. `"town:tavern"`). |
| `base_attitude` | string | No | `"neutral"` | One of: `friendly`, `neutral`, `wary`, `aggressive`, `hostile`. Hostile NPCs auto-engage players in the room. |
| `faction` | string | No | — | Optional faction ID for attitude grouping. |
| `race` | string | No | — | Race ID (e.g. `"race:beast"`, `"race:human"`). If omitted, a random non-hidden race is chosen at each spawn/respawn. |
| `class` | string | No | — | Class ID (e.g. `"class:peasant"`, `"class:rogue"`). If omitted, the race’s `default_class` is used, or a random compatible non-hidden class. |
| `respawn_secs` | integer | No | — | If set, the NPC respawns this many seconds after death. Race/class are re-rolled on respawn unless fixed above. |
| `dialogue` | table | No | — | See below. |
| `combat` | table | No | — | If set, the NPC can be attacked and has combat stats. If omitted, the NPC has default combat stats when attacked. |
## `[dialogue]`
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `greeting` | string | No | — | Line shown when a player uses `talk` on this NPC (only if attitude allows talking). |
## `[combat]`
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `max_hp` | integer | Yes | — | Maximum HP. |
| `attack` | integer | Yes | — | Attack value. |
| `defense` | integer | Yes | — | Defense value. |
| `xp_reward` | integer | No | `0` | XP awarded when the NPC is killed. |
## Examples
**Fixed race/class (e.g. animal):**
```toml
name = "Giant Rat"
description = "A mangy rat the size of a small dog."
room = "town:cellar"
base_attitude = "hostile"
race = "race:beast"
class = "class:creature"
respawn_secs = 60
[combat]
max_hp = 25
attack = 6
defense = 2
xp_reward = 15
```
**Random race, fixed class (e.g. barkeep):**
```toml
name = "Grizzled Barkeep"
description = "A weathered man with thick forearms."
room = "town:tavern"
base_attitude = "friendly"
[dialogue]
greeting = "Welcome to The Rusty Tankard."
```
(No `race` or `class` → random race each spawn, default class from race, e.g. Peasant for humanoids.)
**Fixed class, random race:**
```toml
name = "Shadowy Thief"
description = "A cloaked figure lurking in the darkness."
room = "town:dark_alley"
base_attitude = "aggressive"
faction = "underworld"
class = "class:rogue"
respawn_secs = 90
[combat]
max_hp = 45
attack = 12
defense = 6
xp_reward = 35
```
## Display
`look <npc>` and `examine <npc>` show the NPC’s **resolved** race and class (from the current spawn instance).

80
world/town/objects/OBJECTS.md Normal file
View File

@@ -0,0 +1,80 @@
# Object TOML Reference
Each file in a region’s `objects/` folder (e.g. `world/town/objects/`) defines one object type. The object ID is `"<region>:<filename_stem>"` (e.g. `rusty_sword.toml` in region `town` → `town:rusty_sword`).
## Top-level fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Display name. |
| `description` | string | Yes | — | Shown when the player looks at or examines the object. |
| `room` | string | No | — | Full room ID where the object is placed (e.g. `"town:forge"`). If omitted, the object does not appear in the world until given by script or placed elsewhere. |
| `kind` | string | No | — | Flavour/legacy: e.g. `"weapon"`, `"armor"`, `"consumable"`. If `slot` is not set, `weapon` → `main_hand`, `armor` → `torso` for equip. |
| `slot` | string | No | — | Equipment slot name (e.g. `"main_hand"`, `"off_hand"`, `"torso"`, `"head"`). Must be a slot the equipper’s race has. If set, overrides `kind` for slot choice. |
| `takeable` | boolean | No | `false` | If `true`, players can take the object and put it in inventory. |
| `stats` | table | No | — | See `[stats]` below. |
## `[stats]`
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `damage` | integer | No | — | Weapon damage bonus when equipped in a weapon slot. |
| `armor` | integer | No | — | Armor bonus when equipped in an armor slot. |
| `heal_amount` | integer | No | — | HP restored when the object is **used** (consumable). The object is consumed on use. |
## Examples
**Weapon (explicit slot):**
```toml
name = "Rusty Sword"
description = "A battered iron blade with a cracked leather grip."
room = "town:cellar"
kind = "weapon"
slot = "main_hand"
takeable = true
[stats]
damage = 6
```
**Shield:**
```toml
name = "Iron Shield"
description = "A dented but serviceable round shield."
room = "town:forge"
slot = "off_hand"
takeable = true
[stats]
armor = 4
```
**Consumable:**
```toml
name = "Healing Potion"
description = "A small glass vial filled with a shimmering red liquid."
room = "town:temple"
kind = "consumable"
takeable = true
[stats]
heal_amount = 30
```
**Non-takeable (e.g. scenery):**
```toml
name = "Stone Fountain"
description = "A worn fountain, water trickling quietly."
room = "town:town_square"
takeable = false
```
## Equipment and races
- A race defines which slots it has (see `world/races/RACES.md`). Equipping fails if the race does not have the object’s `slot`.
- If `slot` is omitted, `kind = "weapon"` defaults to `main_hand`, `kind = "armor"` to `torso`; other kinds have no default slot.
- Items are treated as fitting any race that has the slot (no size restriction).

33
world/town/rooms/ROOMS.md Normal file
View File

@@ -0,0 +1,33 @@
# Room TOML Reference
Each file in a region’s `rooms/` folder (e.g. `world/town/rooms/`) defines one room. The room ID is `"<region>:<filename_stem>"` (e.g. `town_square.toml` in region `town` → `town:town_square`). Exits reference these full IDs.
## Top-level fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Room title shown to players. |
| `description` | string | Yes | — | Room description. Can be a multi-line string (`"""..."""`). |
| `exits` | table | No | `{}` | Map of direction → room ID. Direction keys are lowercase (e.g. `north`, `south`, `east`, `west`, `up`, `down`). Values are full room IDs (e.g. `"town:tavern"`). |
## Example
```toml
name = "Town Square"
description = """\
You stand in the heart of Thornwall. A worn stone fountain sits at the \
center, water trickling quietly. Cobblestone paths branch in every \
direction."""
[exits]
north = "town:tavern"
east = "town:market"
west = "town:temple"
south = "town:dark_alley"
```
## Notes
- NPCs and objects are placed in rooms via their own TOML: NPCs have a `room` field, objects have a `room` field. The server builds room contents from those references.
- Exits can point to rooms in other regions; use the full ID (e.g. `"dungeon:entrance"`).
- The world `manifest.toml` must list a valid `spawn_room` ID that exists.