Height layers
Build bridges, platforms and upper floors above the terrain, paint their per-tile heights, place content on them, and see how they reach the server.
7 min read
What height layers are#
The terrain is one continuous surface, so it cannot describe a bridge over a river or the second storey of a house. Height layers add that: each layer is a separate sheet of per-tile height offsets that floats above the ground. Where a layer's offset is 0 it lies flat on the terrain; where you raise it, NPCs, objects and props assigned to that layer stand on the raised floor while the ground underneath stays where it is.
Every map has at least Layer 1, and the terrain itself is an invisible base beneath it. You can add up to 4 layers per map. Layers stack: a tile on Layer 2 sits at terrain height plus Layer 1's offset plus Layer 2's own offset, so raising a lower layer lifts everything above it.
| Layer | Colour | Starting height |
|---|---|---|
| Layer 1 | blue | 0 m (flat on the terrain); this is the ground layer everything is placed on by default |
| Layer 2 | green | 2 m above the layer beneath |
| Layer 3 | yellow | 2 m above the layer beneath |
| Layer 4 | red | 2 m above the layer beneath |
Use height layers for walkable elevation that is not part of the landscape: bridges, docks, balconies, rooftops, multi-floor buildings and dungeon mezzanines. For a hill or a cliff, sculpt the terrain instead (see Terrain).
Where the tools are#
Height layers are edited from Terrain mode. In the tool column, below the terrain sculpt tools, three amber-tinted buttons are the layer brushes:
| Tool | What it does |
|---|---|
| Raise Layer / Lower Layer | Adds to or subtracts from the active layer's offsets under the brush. Holding Ctrl flips raise and lower |
| Smooth Layer | Averages each tile's offset with its eight neighbours |
| Layer Height | Flattens the layer toward the Height value in the layer controls (both halves of the button do this) |
The layer tools deliberately have no default key, so they never collide with the terrain sculpt keys they mirror; click them in the tool column (or bind keys under Settings > Keybinds). Arming one does two things:
- View Height Layers switches on, so the wireframe overlays appear over the terrain. It switches off again when you leave Terrain mode. You can also toggle it by hand from the View menu.
- The layer controls appear inline in the brush settings bar, after the shared brush settings.
Layer controls#
| Control | Purpose |
|---|---|
| Layer: | Dropdown of the map's layers with their colour swatches. The selected one is the active layer, the one the brushes edit |
| + | Adds a new layer above the existing ones (disabled at 4 layers) |
| - | Deletes the active layer and every tile height on it (disabled when only one layer is left). Remaining layers are renumbered |
| Show: L1 to L4 | Per-layer overlay visibility, coloured to match. Hiding a layer only affects the editor view |
| Height: | Target for Layer Height: slider from -50 to 50 m, or type any value from -500 to 500 m in the box |
| Absolute | Off (default): Height is an offset added on top of the terrain. On: Height is the absolute world height the tile should end up at, and the editor works out the offset per tile |
Brush settings#
The layer brushes share the terrain brush: the brush shape picker, Size and Strength in the same bar, and Shift+wheel / Alt+wheel adjust them the same way. Two conversions are worth knowing:
- Size is a diameter in metres, as for terrain; with 0.5 m tiles a 5 m brush touches a circle about 10 tiles across.
- Strength maps to metres of height change per application: 100 % is 2 m at the brush centre, so the default 33 % moves a tile about 0.66 m per click, falling off toward the brush edge. For Layer Height the centre snaps toward the target quickly (strength is tripled) and the edges blend.
Each layer's overlay is a wireframe grid in the layer's colour, drawn 48 m around the camera and regenerated as you move; it follows the terrain contours plus the layer's offsets, so a raised platform reads as a floating sheet.
Procedure: build a bridge#
- Sculpt the river or gap first in Terrain mode so the ground is final; layer offsets are relative to it.
- Click + in the layer controls to add Layer 2. Pick it in Layer: so it is active.
- Arm Layer Height, set Height to the deck height above the banks (for example
3), and paint the span from bank to bank. Use a small Size and go tile by tile at the ends so the approach matches the bank height. - Arm Smooth Layer and stroke the approaches if you want a gentle ramp instead of a step. (For a precise linear ramp, the
set_height_layerMCP tool'srampoption is exact.) - Switch to Objects mode and place the bridge deck model on the layer: with the Place verb, set Height to Heights and pick Layer 2 in Layer:, then click along the span. Props placed this way re-seat themselves whenever the layer is repainted unless you mark them Fixed (see Props and model painting).
- Switch to Region mode, choose Layer 2 in the footer's Height Layer: dropdown, and paint any tiles beside the deck unwalkable with the Flags tool so nobody steps off the side.
- Save with
Ctrl+S.
Placing content on a layer#
Everything that stands on a map carries a layer index, and the editor reads the layer's offset under it to decide its height.
| What | Where you choose the layer |
|---|---|
| NPC spawners, locations, walkability flags | Region mode: the Height Layer: dropdown in the footer bar shown for every region tool except Select. The same dropdown decides which layer the flag brush paints and which layer the Unwalkable tiles count reports |
| Interactive objects | The same Height Layer: dropdown; it also applies to objects placed with the Object verb in Objects mode. Objects snap to whole tiles and take their height from the middle of their footprint on that layer |
| Props (single models) | Objects mode, Place verb: set Height: to Heights and pick the layer in Layer:. Terrain snaps to the ground and Fixed uses a set world height instead |
Entities already placed on a layer follow it: repainting the layer re-seats the objects and the non-Fixed props on it, and the client and server derive an entity's Y from "terrain height plus the layer offset at its tile", never from a stored height.
The layer list also sets what the Smart Navigation auto-fill in the Flags tab targets; see Regions and elements.
How layers reach the game#
Saving the map writes two files for layers:
| File | Contents |
|---|---|
assets/maps/<map>/height_layers.terrain | The full layer data: for every layer its name, colour, default height and a per-tile offset for each active region cell (64 x 64 tiles per cell). The client loads this to place players, NPCs and objects at the right height on a layer |
server/data/maps/flag_data/<map>.terrain | The walkability file. Each blocked tile carries a layer mask: bit 0 means blocked on Layer 1, bit 1 on Layer 2, and so on, so a tile can be open on the bridge and blocked on the ground beneath it (or the reverse). It also records the layer count and the active region cells |
Object spawns exported to server/data/maps/object_spawns/<map>.json include a height_layer_id (0 = Layer 1), and the server checks movement against that layer's mask. NPC spawns are exported without a layer and spawn on the ground layer.
With AI (MCP)#
Layers can be authored editor-free from the same files:
| Tool | Purpose |
|---|---|
create_height_layer | Adds a layer to a map with an optional name, color and default_height. A map from create_map starts with one layer |
set_height_layer | Sets a flat height or a linear ramp (axis, from, to) over a tile rectangle on an existing layer. layer is 1-based: 1 is Layer 1 |
set_tile_walkability | Blocks or unblocks tiles on a given layer bit (0 is the ground, Layer 1) |
read_terrain, sample_terrain, query_terrain_region | Report each layer's offsets per tile |
The three write tools accept dryRun: true. The MCP tools accept up to 7 layers, but the editor only loads the first 4, so stay within 4 for maps you intend to open in the editor.