Building Prefabs

What a building prefab is#

A building prefab is a saved assembly of pieces: walls, floors, doors, furniture and clutter laid out on a tile grid across one or more floors. You build it once in the Building Editor, a clean 3D sandbox with no terrain, and then stamp copies onto any map from the Map Editor. Every stamp places the whole structure at once, so a village of twelve cottages is twelve clicks, not twelve hundred.

Prefabs live in assets/data/building_prefabs.json in your project. They are shared by every map, and a stamped copy is independent of the prefab: deleting or editing the prefab later never touches buildings you already placed.

A building can contain two kinds of parts, and they behave differently once stamped:

Use pieces for everything that is purely visual (walls, roofs, windows, beds) and objects for anything a player can click on (doors that open, chests, crafting stations). See Objects for how object definitions and their tile footprints work.

Opening the Building Editor#

The Building Editor is reached from the Map Editor's bottom Library panel:

1. Open a map and switch the viewport to Objects mode.
2. In the Library panel at the bottom, select the Prefabs tab.
3. Press the Building button (with the plus sign) to start a new building, or double-click an existing building card to edit it. Right-clicking a card offers Edit Building…, Rename… and Delete.

The editor replaces the Map Editor view. The Map button at the top-left of the left panel returns you to the Map Editor; your building stays in memory while you switch, but it is only written to disk when you press Save.

The New Building dialog#

Every new building starts by declaring its plot, the buildable area:

Press Create. The grid pad in the viewport is built at exactly that size, placement is kept on it, and only the declared floors are available. Each floor is 3 m tall, the same spacing the Map Editor uses for height layers.

The small RGB axis marker labelled origin on the pad's south-west corner (top-left when viewed top-down) is the prefab's anchor: when you stamp the building onto a map, this corner lands on the tile you click, and every piece is stored as an offset from it.

Layout of the editor#

• Left panel — the building name field and Save button, then a Scene tree listing every placed piece grouped by floor. A coloured dot marks the kind (piece or object) and an eye button hides a piece in the editor view. Click selects; Ctrl or Shift click selects several. Right-click a piece for Focus Camera, Rotate 90°, Move Up a Floor, Move Down a Floor and Delete; right-click a floor heading for Set as Active Floor and Copy Floor Up. Clear All removes every piece.
• Center — the 3D viewport. The View menu (top-left) switches between Perspective and Top-Down and offers Frame Building and Reset Camera. The Floor: row picks the active floor (Ground, 2, 3...), Copy up duplicates the active floor onto the one above, and Frame centers the camera on the whole building. The Tool: toggle at the top-right switches between Select, Place, Erase and Resize.
• Bottom bar — context controls for the active tool: the Place: mode (Free or Grid Snap), a Size: width × depth adjuster for the armed piece, the Plot: and Floors: spinboxes while resizing, and a Delete button while something is selected. A status line reports the piece count, active floor, plot size and whether the building has unsaved changes.
• Right panel — two tabs. Pieces lists the models already used in this building at the top and the full Model Library below it; Objects lists the objects used in this building and, below, the complete object palette (the same one Region mode places). Clicking any entry arms it for placement.

Floors above the active one are hidden and floors below are dimmed, so you can line up an upper storey against the one beneath it.

Placing pieces#

Arm a piece or object#

• From a model: on the Pieces tab, click a model in the Model Library (or drag it onto the "Used in this building" area). If the model has never been used as a piece before, the editor creates one silently, naming it after the model and estimating its footprint from the model's bounding box (1 to 20 tiles per side). The From Model… button opens the same flow as a dialog where you pick the model and type a Piece name.
• From an object definition: on the Objects tab, click an object in the Object Library. Its footprint comes from the definition and cannot be changed here; edit it in the Data Editor.

The armed piece follows the cursor as a translucent ghost, with a green footprint highlight on the active floor.

Place, run and fill#

Placement refuses tiles that would push the piece's footprint off the plot. While drag-placing, the status line counts the pieces about to be placed, and a rotation is chosen automatically to suit the direction of the run.

Free vs Grid Snap#

The Place: toggle in the bottom bar picks how pieces land:

• Grid Snap (default) snaps every piece to tile centers, and enables runs and rectangle fills.
• Free places the piece at the exact cursor position. The sub-tile offset is saved with the prefab and preserved when stamped, which is useful for clutter that should not sit on a grid. Collision still uses the tile the piece sits on.

Free mode only applies to pieces. Interactable objects always snap to a tile, and the Free button's tooltip says so while an object is armed.

Footprint adjuster#

While a piece (not an object) is armed in the Place tool, the Size: spinboxes show its width × depth in tiles before rotation. Change them to correct a footprint the bounding-box estimate got wrong; the ghost and the saved prefab pick up the new size.

Selecting, moving and erasing#

• Select tool (V): click a placed piece in the viewport or in the Scene tree. Drag to move it, press R to rotate it in place, Delete to remove it, Esc to deselect. With several pieces selected, dragging any of them moves the group and Delete removes them all.
• Erase tool (X): click or drag over placed pieces to remove them.
• Place tool (B): returns to placement.

Undo and redo are available throughout with Ctrl+Z and Ctrl+Y (or Ctrl+Shift+Z), up to 100 steps.

Floors#

Switch floors with the Floor: buttons, the number keys 1 to 5, or Page Up / Page Down. Copy up copies every piece on the active floor onto the floor above and moves you there, which is the quickest way to start a second storey from the ground-floor walls. The button is disabled on the top floor of the plot; raise the floor count with the Resize tool first.

Resizing the plot#

Choose the Resize tool and either:

• drag a plot edge directly in the viewport (the hovered edge lights up), or
• type exact values into the Plot: width × depth and Floors: spinboxes in the bottom bar.

Typing keeps the south-west origin fixed and grows to the east and north. Both methods clamp so that no placed piece can end up outside the plot or above the top floor, and the limits stay at 48 × 48 tiles and 5 floors.

Camera#

The viewport uses the Map Editor's camera rig, so it handles the same way:

Tool shortcuts are muted while the right mouse button is held, so flying with Q and E never rotates a piece.

Saving a building#

1. Type a name in the field at the top-left. Saving is refused without one, and with no pieces placed.
2. Press Save or Ctrl+S.
3. If a different building with that name already exists, you are asked whether to overwrite it.

The building is written to assets/data/building_prefabs.json and a confirmation tells you where to stamp it from. Piece positions are stored relative to the plot's origin corner, so the tile you later click on the map is exactly that corner.

When a saved building is reopened and some of its objects no longer exist in the Data Editor, those pieces are skipped and the editor tells you how many.

Stamping a building onto a map#

From the Library (Objects mode)#

1. In the Map Editor, switch to Objects mode and open the Library's Prefabs tab.
2. Click a building card. The Building tool (K) in the toolbar arms itself and a ghost of the whole building follows the cursor. The card's tooltip reports the piece count.
3. Rotate the ghost in quarter turns with Q and E (rebindable under Settings). A quarter turn swaps the footprint's width and depth.
4. Left-click to place. Each further click places another copy anchored at the clicked tile.
5. Press Esc, or pick another tool, to stop stamping.

A stamp is all-or-nothing: if any tile of the building would land outside the terrain, nothing is placed and a warning is logged, so you never end up with half a house to clean up.

From the Selection tab (Region mode)#

Region mode reaches the same prefab library through the marquee tool:

1. In Region mode choose the Select Tiles tool and drag a rectangle on the map.
2. The Selection tab on the right ends with a Building Prefabs section: pick a building from the dropdown and press Stamp to arm it.
3. Save Selection as Prefab goes the other way: it captures every placed object and every decorative prop whose anchor tile lies inside the rectangle and saves them as a new building under the name you enter. This is the quickest way to turn something you built directly on a map into a reusable prefab.

What a stamp does to the map#

• Object pieces become interactable object spawns on the map, with the interaction type use, a 2-tile interaction radius and persistence enabled. They export to the server with the map's other objects, so players can use them.
• Pieces become batched props in the map's props.bin, centered over their footprint and seated on the terrain height at that spot plus 3 m per floor.
• If the building has upper floors and the map lacks the matching height layers, they are created automatically (Ground at 0 m, then Floor 2, Floor 3... at 3 m steps). See Height layers.
• The whole stamp is one undo step: Ctrl+Z removes the entire building.
• The map is marked modified; save it with Ctrl+S to write the changes and regenerate its server exports (see Map files and export).

The prefab file#

assets/data/building_prefabs.json holds every building in the project:

{
  "version": 1,
  "prefabs": [
    {
      "name": "small-cottage",
      "width": 12,
      "depth": 12,
      "floors": 2,
      "pieces": [
        {
          "kind": "prop",
          "prop_id": "2KED8XR1YSD4",
          "model_path": "res://assets/models/2KED8XR1YSD4_Wall/Wall.scn",
          "name": "Wall",
          "tile_width": 2,
          "tile_depth": 1,
          "dx": 0,
          "dz": 0,
          "rotation_y": 90.0,
          "height_layer_id": 0
        },
        {
          "object_id": 7,
          "dx": 3,
          "dz": 0,
          "rotation_y": 0.0,
          "height_layer_id": 0,
          "interaction_type": "use",
          "interaction_radius": 2.0,
          "script_on_interact": "",
          "is_persistent": true,
          "custom_properties": {}
        }
      ]
    }
  ]
}

With AI (MCP)#

• list_building_prefabs lists every saved building with its declared plot, real footprint, how many pieces are objects versus props, and any object_id the project no longer defines.
• stamp_building_prefab places a building on a map in one call: map, prefab, tileX and tileZ (the south-west corner), an optional rotation_y that must be a multiple of 90, an optional base_height_layer to lift every storey (for stamping onto an existing roof), and dryRun to preview the writes. Missing height layers are created the same way the editor does it.

Buildings themselves can only be authored in the Building Editor or captured from a map with Save Selection as Prefab; there is no MCP tool that creates one. See the MCP tools reference for the full list.