diff options
Diffstat (limited to 'building_guide/admin.md')
| -rw-r--r-- | building_guide/admin.md | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/building_guide/admin.md b/building_guide/admin.md new file mode 100644 index 0000000..4ec36c1 --- /dev/null +++ b/building_guide/admin.md @@ -0,0 +1,204 @@ +## Admin Commands + +Admin commands are available to accounts with `admin: true` set in their account YAML file +(`data/players/accounts/<name>.yaml`). Non-admin players see "Unknown command." when +attempting these, so their existence is hidden. + +### Enabling Admin + +Edit the account YAML and add `admin: true`: +```yaml +name: yourname +password_hash: sha256:... +characters: [...] +aliases: {} +colors: {} +options: {} +admin: true +``` + +The character must log out and back in for the change to take effect. + +### Commands + +#### goto +``` +goto <room_id> +``` +Instantly teleports you to the specified room by numeric ID. Cancels any active combat, +action, rest, enter sequence, or safespot. Your departure and arrival are broadcast to +players in both rooms. + +#### summon +``` +summon <player_name> +``` +Teleports a player to your current room. Their active state is cleaned up (combat, actions, +etc.) and they receive a notification. Case-insensitive name matching. + +#### dig +``` +dig <direction> [name] +``` +Creates a new room in the given direction (north/south/east/west/up/down) from your +current room. The new room ID is auto-generated as the lowest available integer at-or-above +the minimum room ID in the same directory as your current room's YAML file. + +Both the new room and your current room are updated with reciprocal exits. The admin is +teleported into the new room. The new room starts with a generic "A featureless room." +description and no spawns, mobs, or objects — edit its YAML file to flesh it out. + +If the direction would place the new room on a grid cell already occupied by an existing +room (a grid overlap), no new room is created. Instead, a two-way link is automatically +established between your current room and the existing room. + +Examples: +- `dig north` — creates a room north of you with auto-generated ID and name "New Room" +- `dig east "Dark Forest"` — creates a room east of you named "Dark Forest" + +#### undig +``` +undig <direction> +``` +Deletes the room in the given direction and removes all exits leading to it from +every room. Requires confirmation — type `UNDIG <direction>` to proceed, anything +else to cancel. The target room's name and ID are shown before deletion. A warning +is displayed if deleting the room would create orphaned (unreachable) rooms. + +Any players currently in the deleted room are teleported to your current room. + +#### close +``` +close <direction> +``` +Deletes an exit in the given direction from your current room. Also removes the +reciprocal exit from the target room if it points back to your room. + +#### swapid +``` +swapid <id> +swapid <id1> <id2> +``` +Swaps the numeric IDs of two rooms. The first form swaps your current room with +the given room ID. The second form swaps two arbitrary rooms. All exit references +across the entire world are updated automatically to keep the world consistent. + +#### room +``` +room <action> [args...] +``` +Modify the current room's data directly from inside the game. Type `room` alone +to see all available actions: + +| Action | Usage | Description | +|--------|-------|-------------| +| `name` | `room name <text>` | Set the room's name | +| `desc` | `room desc <text>` | Set the room's description | +| `addobj` | `room addobj <object_id>` | Add a referenced object (must exist in data/objects/) | +| `remobj` | `room remobj <object_id>` | Remove a referenced object | +| `addlocalobj` | `room addlocalobj <name> <description>` | Add a local object | +| `remlocalobj` | `room remlocalobj <name>` | Remove a local object | +| `hide` | `room hide <name_or_id>` | Hide all matching objects (referenced or local) | +| `unhide` | `room unhide <name_or_id>` | Unhide all matching objects (referenced or local) | +| `addmob` | `room addmob <mob_id>` | Add a mob spawn (must exist in data/mobs/) | +| `remmob` | `room remmob <mob_id>` | Remove a mob spawn | +| `addspawn` | `room addspawn <item_id> [qty] [respawn]` | Add an item spawn (must exist in data/items/) | +| `remspawn` | `room remspawn <item_id>` | Remove an item spawn | + +All room commands are admin-only. Referenced objects, mobs, and items are validated +before being added. + +#### god +``` +god +``` +Temporarily sets all your skills to level 99, prevents mobs from aggressing you, +allows walking through blocked exits, and makes you immune to hazard damage and +death. Does NOT persist across reconnects — your original stats are restored +automatically when you quit, disconnect, or use the `ungod` command. + +#### ungod +``` +ungod +``` +Restores your original skills and removes god-mode privileges. This also happens +automatically if you disconnect or quit while in god mode, so your inflated stats +are never saved to disk. + +#### setflag +``` +setflag <flag_name> [value] +``` +Sets a world flag. World flags are shared by all players and stored in memory (lost on +server restart). Setting a flag fires any triggers watching that flag. Values default to +`true` if omitted. Accepted value types: `true`/`false` (bool), integer, or string. + +#### setplayerflag +``` +setplayerflag <player_name> <flag_name> [value] +``` +Sets a player-specific flag on a character. Player flags are persisted to the character +YAML file and survive restarts. Setting a flag fires any triggers watching that flag. +The character is saved immediately. Values work the same as setflag. + +#### reload +``` +reload +``` +Reloads all data caches from disk. Use this after editing YAML files (items, objects, +mobs, drops, techs, modules, courses, hazards, triggers) to pick up changes without +restarting the server. Rooms already hot-reload automatically. + +The reload process: +1. Clears item, object, and mob definition caches +2. Rebuilds path indices for items, objects, mobs, drops, and rooms +3. Rebuilds the craft index +4. Reloads techs and modules +5. Reloads courses +6. Clears hazard caches +7. Clears and re-seeds triggers from disk + +Live state (mob instances, player data, ground items, active sequences) is NOT affected. + +#### shutdown +``` +shutdown <minutes> +shutdown cancel +``` +Schedules a graceful shutdown announcement. All online players receive a message every +30 seconds with the remaining time. When the countdown reaches zero, the server exits +immediately. Use `shutdown cancel` to abort a pending shutdown. + +#### inspect +``` +inspect +``` +Dumps detailed diagnostic information about your current room: +- Room ID, name, color, hazard, BlockTransport status +- All exits with conditions noted +- Objects (with local/global, hidden, and wander status) +- Mobs with wander intervals +- Item spawns with respawn timers +- On-enter step and trigger counts +- All world flags +- Your player flags +- Connected players in the room +- Live mob instances with HP + +### Workflow + +The typical admin worldbuilding workflow: + +1. **Lay out rooms:** Use `dig` to create connected rooms quickly. If `dig` would create a + grid overlap, a two-way link is created instead — no duplicate rooms. +2. **Flesh out rooms:** Use `room` commands to set names, descriptions, add objects/mobs/spawns + directly from inside the game. For deeper edits, edit the YAML files directly in + `data/rooms/` to add on-enter scripts, triggers, hazards, etc. +3. **Rearrange:** Use `swapid` to renumber rooms and `undig` to delete rooms you no longer want + (with full exit cleanup). Use `close` to remove individual exits. +4. **Reload:** Run `reload` to pick up YAML changes without restarting (rooms auto-reload). +5. **Test:** Use `goto` to jump around while debugging room connections and content. +6. **God mode:** Use `god` to test dangerous areas safely — full stats, no aggro, pass through + blocked exits. `ungod` restores normal state. +7. **Debug:** Use `setflag` / `setplayerflag` to test quest logic and conditional content. + Use `inspect` to check room state, flags, and triggers. |