Objects, prefabs and text

place_object

Place an object (prop) on the current map. Returns the new element id.

If you place a colourable asset WITHOUT a colour, the response comes back with colorable: true and mask_fraction, and its note says whether the object is a flat red shape or just has red accents. Colour is baked at placement, so the fix is to delete it and place it again with color.

x, y: woxel coordinates; defaults to map center. rotation: degrees.

Two different tints, do not confuse them: color or modulate.

place_objects

Place many objects at chosen positions in ONE call and ONE undo step.

Use it whenever you know where several things go: a row of tables, the dressing on a bar, eight trees ringing a clearing. Each entry takes the same arguments as place_object and behaves identically.

scatter_objects is for RANDOM arrangement over an area; this is for deliberate positions.

Up to 100 entries in objects. Every asset is checked before anything is placed, and if one entry fails the whole batch is rolled back, so the map never holds a half-finished batch whose ids you were not told.

Returns objects: one {id, position, layer} per entry, in the order you passed them, plus ids. Entries placed from a colourable asset with no color are listed in the note: those are flat red, and colour cannot be added afterwards.

One undo() reverses the whole batch while it is the latest operation. snap applies to every entry with an x and y; see get_snap_settings.

A batch placed entirely at scale 1.0 on quarter turns comes back with an arrangement_note: most placements read better with slight variation.

scatter_objects

Scatter objects randomly over a rectangular area, with jittered scale and rotation.

This is the tool to reach for when a space should look furnished or lived-in rather than placed-at-coordinates: foliage, rubble, crates, clutter, debris. Placing twenty objects individually reads as a grid; this does not.

scale_min / scale_max: random scale range per object. rotation_min / rotation_max: random rotation range in degrees.

Returns the ids placed, how many attempts it took, and a note if it could not fit the requested count.

place_prefab

Place one of Dungeondraft's pre-composed prefabs by name.

Call list_prefabs first to see what exists — names must match exactly.

Reach for this before hand-composing a common furnished unit. A tavern's tables, a market stall, a smithing setup or a well already exist as prefabs and will look better assembled than placed piece by piece.

ALWAYS pass x and y. A prefab otherwise lands wherever its author saved it, usually near the map's top-left corner. With x and y the prefab's centre lands there, and placement in the response reports what moved. If it still lands wrong, undo() removes the whole prefab in one step while it is the latest operation.

x, y: woxel point to centre the prefab on. Pass both or neither.

Placement transforms walls with their mounted portals, paths, roofs, patterns, objects, lights, freestanding portals, and text anchors (labels stay upright). Cave-generated walls and unsupported elements are listed in placement.skipped with reasons in placement.unsupported. Inspect those and the footprint before repeating. To shift or rotate the group afterwards, use move_elements with the returned ids — one call, one undo step.

modify_object

Modify an existing object's scale, rotation (degrees), color, shadow and/or light-blocking by id.

color is REFUSED: colour is baked at placement and cannot be changed afterwards, here or in Dungeondraft's own UI. Set it in place_object.

Unlike colour this IS changeable after placement, and it is how a map built before layers were assigned correctly gets repaired.

duplicate_object

Duplicate an object by id, offset by (dx, dy) woxels. Returns the new element id.

add_text

Add a text label at a woxel position. Returns the new element id and size.