Skip to content

Building Commands Reference

This guide provides a comprehensive reference for all in-game building commands available to MAID builders and administrators. Building commands allow you to create, modify, and manage the game world directly from within the game.

Table of Contents

Access Levels

Building commands require elevated access levels:

Level Commands Available
BUILDER @create, @destroy, @dig, @describe, @set, @examine, @component, @teleport, @find, @zone, @copy
ADMIN All builder commands plus @purge, @batch, @reload, @profile, @memory, @timing
SUPERADMIN All commands including @rollback and system-critical operations

Your access level is set by server administrators via the @grant command or the Admin API.

Target Resolution

Most building commands require specifying a target entity. MAID supports several targeting syntaxes:

Basic Targets

Syntax Description Example
here The room you're currently in @describe here
me or self Your character entity @examine me
#<uuid> Entity by its UUID @examine #550e8400-e29b-41d4-a716-446655440000
<name> Entity by name (current room) @examine sword

Extended Targets

Syntax Description Example
<name>.<n> Nth entity with that name @examine sword.2
<name> in <container> Entity inside a container @examine sword in chest
room:<name> Room by name @goto room:Town Square
player:<name> Player by username @teleport player:Bob here
npc:<name> NPC by name @examine npc:shopkeeper

Path Targets

For setting nested values, use dot notation:

@set target/path.to.field = value

Examples: 

@set sword/damage.base = 10
@set npc/ai.behavior = "patrol"
@set room/metadata.terrain = "cave"

Entity Creation

@create

Create a new entity in the game world.

Syntax: 

@create <type> <name> [= template]

Entity Types: - item - Physical items (weapons, armor, consumables) - npc - Non-player characters - room - Rooms/locations - exit - Room exits/doors - container - Containers (chests, bags) - object - Generic interactable objects

Examples: 

@create item Iron Sword
@create npc Guard Captain
@create container Wooden Chest
@create item Health Potion = potion_template

Using Templates:

Templates are predefined entity configurations: 

@create item Longsword = weapons/longsword
@create npc Merchant = npcs/generic_merchant

List available templates: 

@create --list-templates
@create item --list-templates

@copy

Clone an existing entity.

Syntax: 

@copy <target> [new_name]

Examples: 

@copy sword
@copy sword Sword of Flames
@copy #550e8400-e29b-41d4-a716-446655440000 Clone

The new entity is created in your current room.

Entity Modification

@destroy

Delete an entity from the game world.

Syntax: 

@destroy <target> [--force]

Options: - --force - Delete even if entity has contents or is referenced

Examples: 

@destroy sword
@destroy #550e8400-e29b-41d4-a716-446655440000
@destroy chest --force

Note: Players cannot be destroyed with this command. Use player management commands instead.

@describe

Set or view an entity's description.

Syntax: 

@describe <target> [description_text]

Examples: 

@describe here                           # View current room description
@describe here A cozy tavern with...     # Set room description
@describe sword A gleaming blade...      # Set item description

For multi-line descriptions, use the @edit command or leave the text blank to open the in-game editor.

@name

Rename an entity.

Syntax: 

@name <target> <new_name>

Examples: 

@name sword Blade of Destiny
@name here The Grand Hall
@name npc Bob the Builder

@set

Set an attribute value on an entity.

Syntax: 

@set <target>/<path> = <value>

Value Types: - Strings: "text" or 'text' or unquoted - Numbers: 42 or 3.14 - Booleans: true or false - Lists: [1, 2, 3] or ["a", "b"] - Dicts: {"key": "value"} - Null: null or none

Examples: 

@set sword/damage = 10
@set sword/damage.base = 5
@set sword/damage.type = "slashing"
@set npc/hostile = true
@set room/metadata.terrain = "cave"
@set item/value = 100
@set container/locked = true
@set container/key_id = "#550e8400..."

@attribute

Manage entity tags/attributes.

Syntax: 

@attribute <target> <add|remove|list> [attribute_name]

Examples: 

@attribute sword list                # List all tags
@attribute sword add magic           # Add 'magic' tag
@attribute sword add cursed          # Add 'cursed' tag
@attribute sword remove cursed       # Remove 'cursed' tag
@attribute npc add friendly          # Mark NPC as friendly

Common tags: - magic, cursed, blessed - Item properties - hostile, friendly, neutral - NPC disposition - hidden, invisible - Visibility - locked, trapped - State flags - quest_item, unique - Special markers

Room and Exit Management

@dig

Create a new room with an exit from your current location.

Syntax: 

@dig <direction> [= room_name]

Directions: north, south, east, west, up, down, northeast, northwest, southeast, southwest, in, out

Examples: 

@dig north                      # Create unnamed room to the north
@dig north = The Grand Hall     # Create named room
@dig up = Tower Rooftop
@dig in = Hidden Chamber

The command automatically creates bidirectional exits.

@tunnel

Connect your current room to an existing room.

Syntax: 

@tunnel <direction> <room_id_or_name>

Examples: 

@tunnel north #550e8400-e29b-41d4-a716-446655440000
@tunnel east room:Market Square
@tunnel down The Dungeon

Create an exit to a destination.

Syntax: 

@link <direction> <destination> [--oneway]

Options: - --oneway - Create only a one-way exit (no return)

Examples: 

@link north #550e8400...
@link portal room:Magic Chamber --oneway

Remove an exit from the current room.

Syntax: 

@unlink <direction> [--both]

Options: - --both - Also remove the reverse exit from the destination

Examples: 

@unlink north           # Remove exit, keep reverse
@unlink north --both    # Remove both directions

Zone Management

Zones (or areas) are collections of rooms that share properties or belong to a logical region.

@zone create

Create a new zone.

Syntax: 

@zone create <name> [description]

Examples: 

@zone create Darkwood Forest
@zone create "The Haunted Mansion" A spooky mansion on the hill.

@zone assign

Assign rooms to a zone.

Syntax: 

@zone assign <zone_name> [room_targets...]

Examples: 

@zone assign Darkwood Forest here           # Assign current room
@zone assign "Town" room:Inn room:Market    # Assign multiple rooms
@zone assign Castle #550e8400...            # Assign by UUID

@zone list

List all zones.

Syntax: 

@zone list

@zone info

Get information about a zone.

Syntax: 

@zone info <zone_name>

Shows: room count, player count, metadata, room list.

@zone rename

Rename a zone.

Syntax: 

@zone rename <old_name> <new_name>

@zone delete

Delete a zone (rooms remain, but become unassigned).

Syntax: 

@zone delete <zone_name> [--force]

Component Management

Components are data containers that define entity behavior and properties.

@component list

List components on an entity.

Syntax: 

@component <target> list

Example: 

@component sword list

Output: 

Components on 'Iron Sword':
  - ItemComponent
  - DamageComponent
  - DescriptionComponent

@component add

Add a component to an entity.

Syntax: 

@component <target> add <component_type> [json_data]

Examples: 

@component sword add HealthComponent
@component sword add DamageComponent {"base": 10, "type": "slashing"}
@component npc add AIComponent {"behavior": "patrol", "aggro_range": 5}

@component remove

Remove a component from an entity.

Syntax: 

@component <target> remove <component_type>

Examples: 

@component sword remove CursedComponent
@component npc remove AIComponent

Common Components

Component Description Fields
HealthComponent Health/HP max_hp, current_hp
ManaComponent Magic points max_mana, current_mana
DamageComponent Damage dealing base, type, dice
ArmorComponent Damage reduction armor_class, resistances
InventoryComponent Item storage capacity, items
PositionComponent Location room_id, x, y, z
AIComponent NPC behavior behavior, aggro_range, patrol_path
QuestComponent Quest data quest_id, stage, objectives

Search and Navigation

@examine

Get detailed information about an entity.

Syntax: 

@examine <target> [component_name]

Examples: 

@examine sword                    # Full entity details
@examine sword DamageComponent    # Specific component
@examine here                     # Current room details
@examine me                       # Your character

@stat

Quick statistics summary.

Syntax: 

@stat <target>

Shows: type, tags, component count, location, basic stats.

@find

Search for entities by type and filters.

Syntax: 

@find <type> [filters...]

Filters: - name=<pattern> - Match name (supports wildcards) - tag=<tag> - Has specific tag - room=<room> - In specific room - zone=<zone> - In specific zone - limit=<n> - Limit results

Examples: 

@find item                           # All items in current room
@find item name=*sword*              # Items containing "sword"
@find npc tag=hostile                # All hostile NPCs
@find item zone="Darkwood Forest"    # Items in zone
@find room name=*Inn* limit=10       # Rooms with "Inn" in name

Complex entity queries with multiple conditions.

Syntax: 

@search <query>

Query Syntax: 

type:item AND (tag:magic OR tag:rare) AND damage.base>10

Examples: 

@search type:item AND tag:weapon
@search type:npc AND tag:hostile AND zone:"Dungeon"
@search type:room AND player_count>0

@teleport

Move an entity to a new location.

Syntax: 

@teleport <target> <destination>

Examples: 

@teleport player:Bob here              # Bring player to you
@teleport npc:Guard #550e8400...       # Move NPC to room
@teleport me room:Town Square          # Teleport yourself

@goto

Move yourself to a location.

Syntax: 

@goto <location>

Examples: 

@goto #550e8400-e29b-41d4-a716-446655440000
@goto room:Town Square
@goto player:Bob                       # Go to player's location

Advanced Editing

@edit

Open the in-game VI-like text editor for multi-line content.

Syntax: 

@edit <target>/<field>

Examples: 

@edit here/description       # Edit room description
@edit npc/dialogue           # Edit NPC dialogue
@edit item/examine_text      # Edit item examine text

Editor Commands: - :w - Save - :q - Quit - :wq - Save and quit - :q! - Quit without saving - i - Insert mode - ESC - Command mode

Administration

@purge

Mass delete entities matching criteria.

Syntax: 

@purge <filter> [--force] [--global]

Options: - --force - Skip confirmation - --global - Search all rooms (not just current) - --dry-run - Show what would be deleted

Examples: 

@purge type:item tag:junk              # Delete junk items in room
@purge type:npc tag:hostile --global   # Delete all hostile NPCs
@purge name:*test* --dry-run           # Preview deletion

@batch

Execute commands from a batch file.

Syntax: 

@batch <file> [options]

Options: - --code - Execute as Python code instead of commands - --dry-run - Validate without executing - --continue - Continue after errors

Examples: 

@batch world_setup.batch
@batch migration.batch --dry-run
@batch custom_script.py --code

See Batch File Format for file syntax.

Batch File Format

Batch files contain commands to execute sequentially.

Command Format

# This is a comment
@create room Town Square
@describe here The central square of the town.
@dig north = Market Street

Variables

# Define variables
$town_square = @create room Town Square

# Use variables
@describe $town_square The central square of the town.
@dig north from:$town_square = Market Street

Conditionals

# Simple conditions
@if exists room:Town Square
    @echo "Town Square already exists"
@else
    @create room Town Square
@endif

Loops

# Create multiple items
@for $i in 1..10
    @create item Potion $i
@endfor

# Create from list
@for $name in ["Inn", "Market", "Temple"]
    @create room $name
@endfor

Python Code Mode

With --code flag, execute Python directly:

# world_setup.py
from maid_stdlib.commands.building import create_room, dig

# Create town
town_square = create_room("Town Square", "The central square.")
dig(town_square, "north", "Market Street")
dig(town_square, "south", "City Gate")

# Create NPCs
for i in range(5):
    create_npc(f"Guard {i}", town_square, {"hostile": False})

Tips and Best Practices

Naming Conventions

  • Use descriptive names: Iron Sword not sword1
  • Use consistent casing: Town Square (title case for rooms)
  • Avoid special characters in names

Organizing Zones

  • Group related rooms into zones
  • Use zones for access control and events
  • Name zones clearly: Darkwood Forest, Castle Dungeon

Component Management

  • Don't add unnecessary components
  • Use templates for consistent entity setup
  • Document custom component data structures

Testing Changes

  • Use --dry-run when available
  • Test in a development area first
  • Keep backups using @batch export

Performance

  • Avoid creating too many entities at once
  • Use @find with filters to limit searches
  • Clean up unused entities periodically

See Also