Skip to content

Building Game Worlds Guide

This guide covers everything you need to know about creating and managing game worlds in MAID, from basic room creation to procedural wilderness generation.

Table of Contents

Overview

MAID provides multiple approaches to world building:

  1. Manual Building - Create rooms one at a time using in-game builder commands
  2. Grid-Based Building - Use coordinates for structured layouts like towns or dungeons
  3. Procedural Generation - Generate wilderness areas on-demand as players explore
  4. Batch Creation - Script large areas using batch files

Choose the approach that fits your needs:

Approach Best For Complexity
Manual Small areas, unique locations Low
Grid-Based Towns, dungeons, structured areas Medium
Procedural Large wilderness, infinite exploration Medium
Batch Mass creation, world seeding High

Getting Started

Access Requirements

Building commands require the BUILDER access level. Contact your server administrator to get building permissions.

Basic Workflow

  1. Navigate to where you want to build (or create a starting room)
  2. Create rooms using @dig or @create
  3. Describe rooms with @describe
  4. Connect rooms with exits using @dig, @tunnel, or @link
  5. Organize rooms into zones with @zone

Essential Commands Quick Reference

@dig <direction> [= room_name]     - Create room and exit
@describe here <text>              - Set room description
@examine here                      - View room details
@tunnel <direction> <room>         - Connect to existing room
@zone assign <zone> here           - Add room to zone

Creating Rooms

Using @dig

The @dig command creates a new room connected to your current location:

@dig north = The Grand Hall

This creates: - A new room named "The Grand Hall" to the north - A bidirectional exit (north from here, south from there)

Without a name, the room gets a default name:

@dig east

Using @create

For rooms not connected to anything (isolated areas, limbo rooms):

@create room The Void

Then connect it later with @link or @tunnel.

Setting Room Descriptions

Use @describe for single-line descriptions:

@describe here A cozy tavern with worn wooden tables and a crackling fireplace.

For multi-line descriptions, use @edit:

@edit here/description

This opens the in-game VI-like editor. Type your description, then use :wq to save and quit.

Room Attributes

Set room properties with @set:

@set here/sector_type = "indoor"
@set here/light_level = 0.5
@set here/metadata.terrain = "stone"

Add room tags with @attribute:

@attribute here add safe_zone
@attribute here add no_teleport
@attribute here add shop

Dynamic Room Descriptions

For rooms that change based on time, weather, or season, add the ExtendedRoomComponent:

@component here add ExtendedRoomComponent

Then configure time variants:

@room time here night "The tavern is quiet, with only a few patrons."
@room time here noon "The lunch crowd fills every table."
@room season here winter "Frost clings to the windows."
@room weather here rain "Rain drums steadily on the roof."

See the Extended Room Features Guide for complete documentation.

Connecting Rooms with Exits

Standard Directions

MAID supports these directions:

  • Cardinal: north, south, east, west
  • Diagonal: northeast, northwest, southeast, southwest
  • Vertical: up, down
  • Special: in, out

Abbreviations work too: n, s, e, w, ne, nw, se, sw, u, d

Creating Exits with @dig

@dig creates bidirectional exits by default:

@dig north = Bedroom

Creates: - Exit "north" from here to Bedroom - Exit "south" from Bedroom to here

Connecting to Existing Rooms

Use @tunnel to connect to a room that already exists:

@tunnel east #550e8400-e29b-41d4-a716-446655440000
@tunnel west room:Market Square

One-Way Exits

For trapdoors, slides, or magical portals:

@link down #destination-uuid --oneway

Removing Exits

Remove an exit from your current room:

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

Exit Descriptions

Give exits custom descriptions:

@room exit here north "A heavy oak door leads north."

For dynamic exit descriptions (hidden doors, locked gates):

# In code or batch file
exit_desc = ExtendedExitDescription(
    direction="north",
    base_description="A passage leads north.",
    state_variants={
        ExitState.LOCKED: "A locked iron gate blocks the way.",
        ExitState.HIDDEN: "",  # Invisible until found
    },
    hidden_until={"perception": (">=", 15)},
)

Using the Grid System

The grid system provides coordinate-based room management with automatic exit creation and pathfinding. Use it for structured areas like towns, dungeons, or buildings.

Enabling Grid Mode

In a batch file or content pack:

from maid_engine.core.grid import GridManager, GridCoord

# Create grid manager with auto-exits
grid = GridManager(
    world=engine.world,
    auto_create_exits=True,
    allow_diagonals=True,
)

Creating a Grid Area

In-Game Command

@grid create 0 0 10 10

Creates a 10x10 grid of rooms with coordinates (0,0) to (10,10).

Programmatically

from maid_engine.core.grid import GridManager, GridCoord

def create_room(coord: GridCoord):
    room_id = uuid4()
    # Create room entity with the coordinate...
    return room_id

# Create 10x10 grid
rooms = grid.create_grid_area(
    GridCoord(0, 0),
    GridCoord(9, 9),
    room_factory=create_room,
)

Coordinate System

      Y+
      |
      |  (0,1)  (1,1)  (2,1)
      |  (0,0)  (1,0)  (2,0)
      +----------------> X+
  • X: East (+) / West (-)
  • Y: North (+) / South (-)
  • Z: Up (+) / Down (-)

Finding Paths

result = grid.find_path(start_room_id, end_room_id)

if result.found:
    print(f"Directions: {result.directions}")  # ['n', 'ne', 'e']
    print(f"Distance: {result.length}")
    print(f"Cost: {result.total_cost}")

Terrain Costs

Different terrain types affect pathfinding:

# Easy terrain
grid.register_room(room_id, GridCoord(0, 0), movement_cost=0.8)

# Difficult terrain
grid.register_room(room_id, GridCoord(1, 0), movement_cost=2.0)

# Impassable
grid.register_room(room_id, GridCoord(2, 0), blocked=True)

Grid Commands Reference

@grid create <min_x> <min_y> <max_x> <max_y>  - Create grid area
@grid info                                      - Show grid statistics
@grid block <x> <y> [z]                         - Block coordinate
@grid unblock <x> <y> [z]                       - Unblock coordinate
@grid room <x> <y> [z]                          - Show room at coordinate
@grid path <room1> <room2>                      - Find path between rooms
@grid export <filename>                         - Export grid to file
@grid import <filename>                         - Import grid from file

See the Grid System Guide for complete documentation.

Procedural Wilderness Generation

The wilderness system generates rooms on-demand as players explore, creating consistent terrain based on noise algorithms.

Enabling Wilderness

from maid_engine.world import WildernessManager, WildernessConfig, Landmark

config = WildernessConfig(
    seed=42,  # Same seed = same terrain
    min_x=-1000, max_x=1000,
    min_y=-1000, max_y=1000,
    cleanup_interval=300.0,  # Clean up empty rooms
    room_max_age=600.0,
)

wilderness = WildernessManager(world=engine.world, config=config)

Biomes

The terrain generator creates these biomes:

Biome Conditions Movement Cost
Plains Default moderate elevation 0.8
Forest Moderate moisture 1.0
Desert Hot and dry 1.5
Tundra Cold 1.5
Mountain High elevation 2.0
Swamp High moisture near water 2.0
Water Low elevation 3.0

Adding Landmarks

Landmarks anchor procedural terrain with fixed locations:

# Town that's always at (0, 0)
wilderness.add_landmark(Landmark(
    coord=(0, 0),
    name="Starting Town",
    room_id=town_room_id,  # Pre-existing room
    radius=5,
    biome_override="plains",
))

# Dungeon entrance
wilderness.add_landmark(Landmark(
    coord=(500, 300),
    name="Dragon's Lair",
    radius=3,
    description="A dark cave entrance looms ahead.",
    metadata={"dungeon_id": "dragons_lair"},
))

Wilderness Commands

@wilderness info                          - Show wilderness statistics
@wilderness biome <x> <y>                 - Show biome at coordinate
@wilderness preview <x> <y>               - Preview terrain
@wilderness landmark add <name> <x> <y>   - Add landmark
@wilderness landmark remove <x> <y>       - Remove landmark
@wilderness landmark list                 - List all landmarks
@wilderness cleanup                       - Manually trigger cleanup
@wilderness generate <x> <y>              - Force generate room

See the Wilderness System Guide for complete documentation.

Zone Management

Zones (or areas) group related rooms for organization, access control, and events.

Creating Zones

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

Assigning Rooms to Zones

@zone assign Darkwood Forest here
@zone assign "Town" room:Inn room:Market room:Tavern

Zone Information

@zone list                    - List all zones
@zone info Darkwood Forest    - Zone details (room count, players, etc.)

Zone Properties

Set zone-wide properties in batch files or code:

zone = Zone(
    name="Darkwood Forest",
    level_range=(5, 15),
    respawn_rate=300.0,
    pvp_enabled=False,
    flags={"outdoor", "wilderness"},
)

Zone-Based Features

Zones enable:

  • Level-appropriate spawns: Monsters scale to zone level range
  • PvP control: Enable/disable PvP per zone
  • Weather: Zones can have independent weather
  • Events: Zone-wide events (invasions, festivals)
  • Access control: Restrict entry by level or faction

Best Practices

Naming Conventions

Type Convention Example
Rooms Title Case "The Grand Hall"
Zones Title Case "Darkwood Forest"
Exits lowercase "north", "secret_door"
Tags snake_case "safe_zone", "no_teleport"

Organization Tips

  1. Plan before building: Sketch your area layout first
  2. Use zones early: Assign rooms to zones as you create them
  3. Consistent descriptions: Maintain a consistent tone and style
  4. Test navigation: Walk through your area as a player would
  5. Document landmarks: Keep notes on important locations

Performance Considerations

  • Batch creation: Use batch files for large areas
  • Wilderness limits: Set reasonable boundaries
  • Room cleanup: Enable wilderness cleanup for procedural areas
  • Grid size: Consider memory when creating large grids

Testing Your World

@goto #room-uuid            - Teleport to test locations
@find room name=*test*      - Find test rooms
@purge type:item --global   - Clean up test items

Example: Creating a Small Town

Here's a complete example of creating a town:

# Start at the center
@create room Town Square
@describe here The central square of the town, with a well at its center.
@zone create Riverside Town
@zone assign "Riverside Town" here
@attribute here add safe_zone
@attribute here add no_combat

# Create surrounding buildings
@dig north = The Rusty Tankard
@describe here A cozy tavern with a roaring fireplace.
@zone assign "Riverside Town" here
@dig up = Guest Rooms
@describe here A narrow hallway with doors to small guest rooms.
@zone assign "Riverside Town" here
@dig down   # Back to tavern
@dig south  # Back to square

@dig east = General Store
@describe here Shelves lined with various goods and supplies.
@zone assign "Riverside Town" here
@attribute here add shop
@dig west   # Back to square

@dig south = Town Gate
@describe here The main entrance to the town, flanked by two guards.
@zone assign "Riverside Town" here
@dig south = Forest Road
@describe here A dirt road leading into the dark forest.
# Don't add to town zone - it's wilderness

@dig north  # Back to gate
@dig north  # Back to square

@dig west = Temple of Light
@describe here A serene temple with stained glass windows.
@zone assign "Riverside Town" here
@attribute here add safe_zone
@attribute here add heal_point