Props and Model Painting

Decoration versus interactive objects#

A map holds two kinds of model-shaped things, and it matters which one you make:

• Decoration - props and painted meshes. The client draws them; the server never sees them. They have no id, no actions, and they do not block movement unless you paint walkability flags under them. Trees, rocks, fences, clutter.
• Interactive objects - placed copies of an object definition. The server knows about them: they occupy whole tiles, block movement, and respond to right-click actions and scripts. Chests, doors, ore rocks, fishing spots.

Objects mode handles both from one palette. You pick a model, and the verb you use decides how it is stored:

Shortcuts are the defaults and can be changed in Settings > Keybinds. Interactive objects are covered in Regions and elements once they are on the map; this page covers getting models onto the map.

Objects mode layout#

Press Objects in the edit-mode toggle at the top-right of the viewport (F2). The tool column down the right edge of the viewport shows the six verbs above. The right panel shows the Models palette: every model used by this map, with a search box, Non-interactive / Interactive view buttons and a grid or list layout. Cards carry badges for how many copies are placed and how many are batched; in the Interactive view a card's badges are its object id and how many are on this map. The bottom panel is the Library (see below). A floating overlay in the bottom-right of the viewport shows the settings for whatever you are doing - placing, or the thing you have selected.

The Library#

The Library panel at the bottom of the Map Editor is the project's model catalogue. It has three tabs:

• Models - every 3D model in the project's model library, browsable by folder.
• Objects - the project's interactive object definitions (from objects.json). Click one to arm it for placement as an object.
• Prefabs - saved buildings. Click to stamp, double-click to open in the Building Editor.

To add models to the library:

• Press Add Models and pick .glb, .gltf, .obj, .fbx, .dae, .blend or .tscn files.
• Drag model files from your file explorer onto the panel.
• Press Import Pack to split a single .glb / .gltf containing many meshes (a modular kit) into one library model per mesh.

Models imported here start in a temporary store and are promoted into the project's assets/models/ folder the first time you place one, so an unplaced import never ships with the game. Right-click a model for Rename, Move to Root or Delete; right-click a folder for New Subfolder, Rename Folder or Delete Folder. Models imported through the Assets editor appear in the same library; see Models for how models are converted and stored.

Place single props#

1. In Objects mode, click a model in the Library's Models tab (or a card in the Models palette). The Place verb arms and a translucent hologram follows the cursor.
2. Adjust the placement settings in the footer under the viewport before clicking:

3. Click the terrain to place. The tool stays armed, so keep clicking to place more. Esc cancels placement.

The viewport overlay mirrors the important settings while placing - Rotation with 90-degree buttons, Scale, Fixed and Slope - and shows the tile under the cursor.

Each placement is one undo step (Ctrl+Z). Placing a model also registers it in the map's model list, which is what the Models palette shows.

Select, move and edit a prop#

Press Select (T) and click a prop. The footer shows Select: filters for Models (props), Interactive (objects) and Meshes (painted batches), and a Click: dropdown that is either Select or Delete.

• Move: press and drag. The prop moves with the cursor from wherever you grabbed it, honouring the grid snap setting; a click that does not move is just a selection. Interactive objects drag tile by tile instead.
• Rotate, scale, seat: the overlay shows the selected prop's tile, Rotation (a degrees box plus 90-degree buttons), Scale (0.05-20), and the Fixed and Slope checkboxes. Moves, rotation, scale and slope-alignment changes are undo steps.
• Make Interactive: replaces the decoration with an interactive object at the same spot, creating a definition if the model has none.
• Delete: the overlay's Delete button, the Delete key, or the Click: Delete mode.
• Ctrl+C copies the selected prop; Ctrl+V arms it for pasting at the next click.

With Meshes ticked, clicking a painted copy selects its whole batch (the overlay reads Batch <model> and N copies, painted) and offers Un-batch and Delete for the group. In Click: Delete mode, clicking a painted copy removes just that one instance.

Paint batched meshes#

Painting is for volume: a forest, a field of grass tufts, rubble. The brush scatters copies of one model and stores them as a single batch per model, which the client can draw in one call.

1. Select a model, then press Paint (I) - or tick Paint batched in the overlay, which does the same thing.
2. The brush settings bar under the viewport is the Terrain3D instancer bar:
   • Size - brush diameter in metres. Shift + mouse wheel adjusts it without leaving the viewport; Alt + wheel adjusts strength.
   • Strength - used as density: at 100% each stamp fills the brush area, lower values scatter sparsely.
   • Slope - only place on ground between these slope angles.
   • Height submenu: Height Offset and Random Height +/-.
   • Scale submenu: Fixed Scale (percent) and Random Scale +/- (default 20%).
   • Rotation submenu: Fixed Spin (Around Y), Random Spin (default 360, so copies face random ways), Fixed Tilt, Random Tilt +/- (default 10) and Align To Normal, which the overlay exposes as Slope.
   • Color submenu: Vertex Color, Random Hue Shift +/- and Random Darken for per-copy tinting.
3. Click or drag to paint. Hold Ctrl and click or drag to erase painted copies under the brush. Alt + click is an eyedropper that re-arms the brush with the model under the cursor.

A paint stroke is one undo step. Erasing with Ctrl is not undoable, so erase carefully.

Batch and un-batch#

You can convert between the two storage styles without re-placing anything. Right-click a model card in the Models palette:

• Batch N copies merges that model's individual props into a painted batch. A prop that was Fixed stays fixed inside the batch; everything else becomes glued to the terrain.
• Un-batch N copies turns a batch back into separate props you can select and move. Above 200 instances the editor asks for confirmation, because every copy becomes its own node and large maps slow down.

The same Un-batch button appears in the overlay when a batch is selected.

Fixed versus following, and Align to Slope#

When you sculpt a hill after placing a hundred trees on it, you do not want to re-seat every tree by hand. The editor therefore records, per placed copy, how it relates to the surface it sits on:

• Following (the default for props - the Fixed box is off): the copy re-snaps to the terrain or its height layer whenever that surface is edited, keeping the vertical offset it was placed with. Terrain brush strokes, terrain undo and redo, and height-layer edits all trigger the refresh, and the map re-seats everything once more when it finishes loading, so terrain changed outside the editor (for example by an MCP bake) settles on open.
• Fixed: the copy keeps the exact height it was placed at no matter what happens underneath. Use it for things that must not sink or float when the ground moves - a platform on posts, a floating crystal.
• Align slope / Slope: the copy's up axis follows the surface normal at its spot. When a following copy is re-seated, it is re-tilted to the new slope while keeping its own yaw, scale and any hand adjustments.

The refresh is derived from the terrain and is never an undo step of its own: undoing the terrain edit puts the props back where they were.

This metadata does not fit in props.bin, whose format is frozen at version 2 because the game client rejects any other version. It is written to a sidecar, maps/<name>/props_meta.json, in the same save pass with the same model keys and instance order. Per copy it stores follow, surface (terrain or layer), layer, offset, align and the last applied normal. A map where nothing follows or aligns has no sidecar at all, and a sidecar that is missing or out of step with props.bin (for example after an external tool rewrote only the binary) degrades to "everything fixed" rather than moving anything. See Map files and export.

Make a model interactive#

You can create an interactive object without leaving the map:

1. Arm a model, then tick Interactive in the viewport overlay. If the model already has an object definition it arms as that object straight away; otherwise a small form opens.
2. Fill in Name (seeded from the model's name), the Footprint in tiles wide (east) by deep (north) (1-20 each, estimated from the model's bounding box), whether it Blocks movement, and the right-click actions. The form starts with an Open action; + Action adds more from the presets Examine, Open, Close, Search, Take, Use, Climb, or Type your own....
3. Press Create Object. The definition is written to both assets/data/objects.json and server/data/objects.json and receives an id; from then on, deeper changes are made in the Data Editor (the overlay's Edit... button jumps there).
4. Click the map to place it. Objects snap to tile centres and face one of four directions; Q / E cycle the facing and the overlay shows a compass picker instead of a degrees box.

Unticking Interactive does not delete the definition; it only means the next click places plain decoration again. The Object verb and the Interactive checkbox are two ways of saying the same thing, so picking one sets the other.

Selecting an area#

Area (Y) drags a tile rectangle. The overlay reports Area W x D tiles with its tile range and a count of what is inside, and offers Save as Building (everything in the rectangle becomes a prefab you can stamp elsewhere) and Delete. Ctrl+C / Ctrl+V copy and paste the rectangle's contents, rotating the paste with Q / E.

Visibility and saving#

The View menu's View Props and View Meshes toggles hide individual props and painted batches respectively, which helps when placing NPCs or flags under dense scenery. Prop and batch edits mark the map modified; Ctrl+S writes props.bin (and props_meta.json when needed) next to the map scene.

With AI (MCP)#

place_props places decorative props on a map without the editor: explicit placements (tile or world position, rotation_y, scale) and/or a deterministic scatter rectangle (count, seed, jitter, random_rotation, scale_range, spacing, avoid_blocked). multimesh defaults to true (batched); set it to false for a few hero props you want to move by hand later. replace: true drops the model's existing instances first. Heights are sampled from the generated terrain, so run generate_terrain first, and use get_map_layout to see what is already placed. For anything a player can click, use place_object_on_map instead.