feat: admin accounts, god mode, OLC commands like dig/room, 'inline' objects changed to 'local' objects

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.