Lighting and map style tools

add_light

Add a light at a woxel position. Returns the new element id.

color: '#rrggbb' (default warm). energy: brightness.

range: the Range Dungeondraft's own Light tool shows, which its saved map and a VTT export record too. get_element and list_elements report it in the same units.

asset: optional Lights gradient/cookie texture path.

snap: 'none', 'grid' or 'auto'; see get_snap_settings.

set_ambient_light

Set the map's ambient light colour — the single biggest lever on mood.

A cold blue-grey reads as night or a dungeon; warm amber reads as lamplight or dusk; a neutral grey lets the placed sources carry the colour. A fresh map's white is flat glare rather than daylight, so decide rather than leave it. Whatever you pick, look at a render afterwards: the mood is yours, but every zone that hosts play has to read at the table. This is map-wide, not a placed light source (use add_light for those).

It is also functional, not just cosmetic: Universal VTT exports carry lighting into Foundry and similar tools, so this affects the map at its destination.

color: '#rrggbb'.

get_map_style

Read map-wide building wear and grid style from the world's actual textures.

Returns canonical names, texture paths, and available choices. A custom texture with no built-in name is reported as null with its path retained. Grid style chooses the line pattern; it does not toggle grid visibility.

No parameters.

set_map_style

Set optional finishing effects across the map, as one undoable edit.

building_wear: none, dust, grime, noise, scratched. Applies to building floors/walls across every level; use only when that global effect fits.

grid_style: dashes, dotted, narrow_line, thick_line. Changes the grid's line pattern, not whether the grid is visible or included in an export.

Omitted fields keep their current values. Both fields are validated before editing, and the response reads actual world textures. Use get_map_style before changing a map and inspect a screenshot/export afterwards. Undo and redo restore both values together, even after switching levels.

set_trace_image

Put a reference image under the map to trace over. Returns what applied.

For reconstructing an approved sketch, a published floor plan, or a hand-drawn dungeon. Load it, size it against the grid, drop its opacity so your own work reads over it, then build on top — and hide it before the final render, because it is a guide, not part of the map.

path: an ABSOLUTE path to an image on the machine running Dungeondraft.

scale: size multiplier. Set it so a known distance on the image matches the grid; guessing here is what makes a traced plan come out the wrong size.

opacity: 0 invisible, 1 opaque. Around 0.3-0.5 is usually enough to follow without drowning what you are drawing.

center: centre the image on the map.

clear: remove the trace image.

Loading an image shows it and clear hides it. visible says whether it is drawn now and image_size is null if the image did not load. Exports never include it.

The trace SAVES with the map: its absolute path, scale, opacity and position go into the file and it reloads next time. Anyone else who opens the map gets a path that doesn't exist on their machine, and a large reference makes every open slow. Call set_trace_image(clear=true) before the final save_map.

A path Windows can't open (260+ characters, typical of agent temp folders) is copied to a short path in the bridge's output folder first; the response says so under copied_from.