The Mudbox guide

Getting started

1. Open Mudbox. Use the browser version, or the offline Windows build: keep all nine files together in one folder and double-click Mudbox.vbs (use Mudbox.bat if your system blocks scripts).
2. Place your first room. On an empty map, click Place first room. At any time you can also double-click empty ground to drop a room on that spot.
3. Grow the map. With a room selected, find the compass in the side panel and click a direction (N, NE, E and so on). Mudbox creates a new room that way and links the two with an exit in both directions.
4. Fill in the details. Rename rooms, write descriptions, set zones and flags, add objects and NPCs. Everything autosaves.
5. Export. Open Menu and choose Evennia .ev, then run the file in your game (see Running it in Evennia).

The map canvas

Drag empty ground to pan, and use the mouse wheel or the plus and minus buttons (bottom right) to zoom.

Minimap

Top right. It shows every room on the current floor, with a brass outline marking what your main view covers. Click anywhere on it to jump there.

Floors

The up and down chevrons at top left step through floor numbers (Z0, Z1, Z-1 and so on). Once more than one floor has rooms, a list of floor numbers appears underneath for quick jumping. The easiest way to make a new floor is the UP or DOWN exit button on a room, which creates a room directly above or below.

Search

Top right of the toolbar. Type part of a room name and click a result to jump straight to it, even on another floor.

Reading a room on the map

Editing a room

Click a room to select it and the side panel fills with its details.

Name

Becomes the room's name in Evennia.

Zone

One of eight colours. Zones colour-code the map and let you export one area at a time.

Room description

What players see when they look. Exported as the room's description.

Builder notes

Private notes for you. They stay in Mudbox and are never exported.

Evennia typeclass

Leave blank to use your game's default room class, or enter a path such as typeclasses.rooms.DarkRoom.

Tags

Free text for your own reference. It appears as a comment in the exported file but isn't applied in-game.

Flags

Dark, No-combat, Safe-zone and Outdoor. Each active flag is exported as a tag on the room (dark, no-combat, safe-zone, outdoor). What those tags actually do is up to your game's code.

Exits

The compass in the side panel has eight directions plus UP and DOWN. A brass button means an exit already exists that way.

• Click an empty direction to create a room there and link both ways. If a room already sits in that spot, Mudbox links to it instead.
• Click a brass direction to travel to the room on the other side.
• The exit list below the compass shows each exit with its destination and a coloured type badge. Click the badge to cycle the type. Click the cross to remove the exit (its return exit goes too).

Objects and NPCs

Select a room and scroll the side panel to Objects in this room and NPCs in this room. Each has an add button, and every item gets its own card.

Objects

• Name, aliases, typeclass, description, tags. Aliases are comma-separated and become Evennia aliases. A blank typeclass uses your game's default object class.
• Move to another room with the dropdown at the bottom of the card. The pin marks where it is now.
• Templates. Click the bookmark icon to save an object as a template. Saved templates appear under the add button in every room. Click a template's name to drop a fresh copy into the selected room, or click its cross to delete it.

NPCs

NPCs work the same way, with two extra notes fields, Dialogue and Behavior, for your own reference. They appear as comments in the exported file. For real branching conversations, use the Dialogue tab instead.

Rooms show a brass badge for their object count and a green badge for their NPC count. Deleting a room also deletes the objects and NPCs inside it.

Dialogue trees

Switch to the Dialogue tab at the top. A dialogue is a set of nodes. Each node is one line the NPC says, followed by the replies the player can pick. Each reply leads to another node or ends the conversation.

1. Create a dialogue. Click New dialogue in the left column and give it a name.
2. Attach it to an NPC. Pick one from the dropdown. This is a label for your own organisation, and it shows in the text and JSON exports.
3. Write the first line. New dialogues start with one node, marked start. Select it and edit NPC says.
4. Add replies. Click Add response, type what the player says, then choose where it goes from the dropdown: another node, or (end conversation).
5. Add more nodes with Add node and point replies at them. A reply can lead back to an earlier node, so conversations can loop. A reply can't point at its own node.

To change where the conversation begins, select a node and click Set as start node. You can't delete the start node. If you delete any other node, replies that led to it become conversation endings.

Exporting a dialogue

To use the .py file, save it in your game's world folder and start it from wherever your game triggers conversations:

from evennia.utils.evmenu import EvMenu
EvMenu(caller, "world.dialogue_old_fisherman", startnode="node_start")

Mudbox gives you the conversation. Hooking it up to an NPC, such as a talk command, is code in your own game.

Checking your map

Open Menu and choose Validate map before you export. The report lists:

• Isolated rooms: no exits in or out.
• One-way surprises: an exit whose destination has no way back, when you didn't mark it One-way.
• Broken links: an exit pointing at a room that no longer exists.
• Unreachable rooms: rooms you can't walk to from the first room you made.

Click any entry to jump straight to that room.

Exporting

Everything lives under Menu. Dialogue exports are in the Dialogue tab.

After you click an export, a banner appears at the bottom of the screen with a download link. Click that link to save the file. It works this way so downloads still go through in locked-down browser windows.

Exporting one zone

Once you use more than one zone colour, a zone dropdown appears in the Export section. Choose a zone before clicking Evennia .ev to export only its rooms. Exits that cross into other zones are skipped and listed as comments at the end of the file, so you can see where each seam is when you build the next zone.

The ASCII map

[1]-[2]  [3]^
  |
[4]-[5]  [6]v

Each room is a numbered block with a legend underneath. Lines show exits: - and | for the compass directions, / and \ for diagonals. A ^, v or * after a room means it has an exit up, down or both.

Running it in Evennia

1. Pick your start room. The export begins at the room you have selected, or the first room of the chosen zone.
2. Export with Menu, then Evennia .ev, and save the file into your game's world folder, for example mygame/world/mymap.ev.
3. Run it in-game as a builder or superuser:

   @batchcommand mymap

   The dotted form world.mymap also works. The file runs in automatic mode and prints each command as it goes, so keep an eye out for errors.
4. Connect it to your world. The start room is a brand-new room and isn't linked to Limbo or anything else you already have. Add that link yourself, for example by standing in an existing room and using @open to point an exit at the new start room.

What the file contains

# Evennia batch-command file generated by Mudbox
@dig Town Square
# created start room
@tel Town Square
# moved into start room
@tel Town Square
# back to Town Square
@tunnel n = Market
# dug n to Market
@tel Market
# moved into Market

Rooms are created with @dig and @tunnel, loops and shortcuts with @open, descriptions with @desc, flags with @tag, and objects and NPCs with @create/drop.

Duplicate room names

Evennia finds rooms by name while the file runs, so two rooms called "New Room" would send the builder to the wrong place. In the exported file, repeats are renamed "New Room (2)", "New Room (3)" and so on. Your Mudbox map is untouched, but those suffixed names are what you'll see in-game. The top of the file lists every rename with its coordinates. If you'd rather have clean names, rename the rooms in Mudbox first.

Not done for you

• Locked and hidden exits get a reminder comment, not an actual lock or hiding.
• Tags, NPC dialogue notes and NPC behavior notes are comments for reference.
• Anything rooms or objects do in play comes from your game's code. Mudbox builds the structure.
• Rooms that can't be reached from the start room are skipped, and the end of the file names them.

To start over on a test game, wipe it and run the file again. Running the same file twice in one game builds a second copy of everything.

Saving, backups and undo

Autosave

Every change is saved in your browser as you go. The indicator at the top right of the canvas shows Saving and then Saved.

Where your data lives

Saved work belongs to one browser, one profile and one address. The hosted site and the offline app each keep their own copy, and clearing your browser data erases it. Export JSON for backups and to move work between them.

Importing

Menu, then Import JSON loads a Mudbox backup and replaces what's on screen. Dialogue JSON exports are for other engines and can't be imported.

Undo and redo

Use the toolbar arrows, or Ctrl+Z and Ctrl+Shift+Z. Fast bursts of typing count as one step. Undo covers rooms, exits, objects, NPCs, templates and the map title. It doesn't cover dialogues or your theme.

New Map

Clears rooms, objects and NPCs after you confirm, and the confirmation is itself undoable. Your templates and dialogue trees stay.

Themes

Open Menu and use the Theme dropdown to switch between Blueprint, Forest Ledger, Crimson Archive, Slate & Steel and Violet Codex. Your choice is remembered in your browser, and SVG exports use whichever theme is active.

Mouse and keys

Troubleshooting

The batch ran but my NPCs didn't appear.

The NPC's typeclass probably doesn't exist in your game, and Evennia carries on after the error. Clear the typeclass field to use the built-in Character fallback, or enter a class path that really exists.

The whole batch failed as one broken command.

Something removed the # comment lines between commands. Re-export the file, and if you edit it by hand, keep a # line between every pair of commands.

I clicked export and nothing happened.

Look at the bottom of the screen for the download banner, and click the link in it.

My map was gone when I came back.

Saved work is tied to one browser, profile and address. Check you're in the same one as before, then restore from a JSON backup if needed.

Import says it couldn't read the file.

Import only accepts a Mudbox JSON backup from Menu, then JSON, not a dialogue JSON.

I can't link two rooms that aren't touching.

Exits join neighbouring grid cells only. Move the rooms closer, or add a connecting room between them.

Known limits

• SVG and ASCII exports cover one floor at a time, the one you're viewing.
• Rooms connect to grid neighbours, up, and down. There are no portal-style exits between distant rooms yet.
• Locks and hidden exits are reminders in the export, not applied for you.
• Dialogue trees aren't covered by undo and aren't part of the .ev file.
• The offline launcher is for Windows. The browser version runs anywhere.