Objects, prefabs and text tools

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.

asset: an Objects asset path from list_assets(category='Objects'). x, y: woxel coordinates; defaults to map center. rotation: degrees.

sorting: 0=over, 1=under. snap: 'none', 'grid' or 'auto'; see get_snap_settings.

Two different tints, do not confuse them:

color: '#rrggbb', Dungeondraft's own colourable-asset colour — the same thing the app's colour picker sets. Only assets carrying the colourable attribute respond to it (including colorable carpets and crystals). On any other asset it is stored and never renders.

modulate: retained for compatibility, but nonempty values are refused because Dungeondraft does not preserve this tint when saving and reopening.

layer: which layer the object is drawn on — a VALUE, a multiple of 100 from -500 to 900 (also 1100, Above Lights, when get_status.unofficial_patch is loaded), not a menu index. 100 is the default and where most objects belong. Raise it to put something ON a surface: a floor pattern sits on 100, so a mug placed on 100 can be buried by it, while 200 puts the mug above. sorting only reorders siblings within one layer and cannot do this. The response reports the layer the object actually landed on.

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.

file: an absolute path to a JSON file of the same entries (a list, or {"objects": [...]}), up to 1000. Use it when a script computed the positions: write the file and pass its path instead of copying hundreds of entries into the call. The reply is compact: placed, id_ranges ([first, last] runs of ids) and colorable_without_color.

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.

assets: one or more Objects asset paths from list_assets(category='Objects'). Each placement picks one at random, so pass a few related assets for variety.

rect: [x, y, w, h] in woxels. 256 woxels = 1 tile.

count: how many to place (1-500). scale_min / scale_max: random scale range per object. rotation_min / rotation_max: random rotation range in degrees.

min_gap: minimum woxel distance between placements. Use it to stop clumping; too large for the area and you get fewer than count (the response says so).

color: optional '#rrggbb' applied to every placement, baked at placement and never changeable afterwards. Only colourable assets respond — see place_object.

seed: fixes the arrangement so a run is reproducible. Pass one when you want to adjust a single parameter and compare, rather than reshuffling everything.

layer: layer VALUE for every placement (multiple of 100, -500..900, or 1100 with the Unofficial Patch). Same meaning as in place_object; 100 is the default.

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.

name: exact prefab name from list_prefabs.

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

rotation: degrees to turn the whole prefab about its centre.

snap: snaps the centre x, y; see get_snap_settings.

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.

block_light: whether this object STOPS light passing through it. A drawn shadow and a light block are different things — a crate stack with a shadow but no block still lets a lantern light the room through it. Set it on anything solid enough to stand behind: crates, bookcases, screens, a wagon. get_element reports it back.

modulate: nonempty values are refused because the tint does not survive saving and reopening. 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.

layer: move an existing object to a layer VALUE (multiple of 100, -500..900, or 1100 with the Unofficial Patch). 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.

snap: rounds dx, dy to the nearest whole grid steps; see get_snap_settings.

add_text

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

size: font size in points (default ~32). color: '#rrggbb' (default black).

font: a DD font name; omit to keep the default font.