Configuration settings for the placement system's behavior and appearance. Controls preview display, multi-placement functionality, instance management, and other placement-related parameters. Runtime-instantiated: read every frame by placement services. Do not mark @tool.
Source: addons/grid_placement/systems/building/placement_settings.gd
Syntax
class PlacementSettings extends PlacementResourceMembers
| Name | Kind | Summary |
|---|---|---|
DRAG_PREVIEW_REFRESH_INTERVAL_TICKS | Field | Bulk previews revalidate external physics/rule changes periodically. |
preview_kept_script_types | Property | List of Script Global Class Names that will be kept for preview instances when placing objects in build mode.[br][br] [code]preview_kept_script_types[/code]: [i]Array[String][/i] - Script class names to preserve during preview creation |
add_placeable_instance | Property | Add a placeable instance component node automatically to any instance objects placed by the building system. This node holds a reference to the placeable that created it to reinstate the scene between level loads.[br][br] [b]WARNING:[/b] It does this using file_path to the placeable resource. Files can move around a lot so you may consider implementing an ID database for looking up Placeables instead during gameplay to avoid losing reference the ScenePlacementEntry file.[br][br] [code]add_placeable_instance[/code]: [i]bool[/i] - Whether to automatically add PlaceableInstance component to placed objects |
preview_instance_z_index | Property | The z index value to set preview instances to in order to control their rendering order. The preview ghost renders ABOVE the rule-check indicators (indicator_z_index) so the footprint overlays stay visible beneath the semi-transparent object while the object silhouette remains the visual focus. [code]preview_instance_z_index[/code]: [i]int[/i] - Z-index for preview instance display ordering |
indicator_z_index | Property | The z index applied to rule check indicators so validity feedback renders BENEATH the placement preview ghost (see [member preview_instance_z_index]). [code]indicator_z_index[/code]: [i]int[/i] - Z-index for rule check indicator display ordering |
default_cell_anchor_mode | Property | Game-wide 2D root seat for entries left at INHERIT. Explicit entry modes override this default. See ScenePlacementEntry.CellAnchorMode for mixed even/odd cell dimensions such as a centered 256x96 sprite on a 32px grid. |
drag_ghost_style | Property | How multi-cell object drags (line, rectangle outline/fill) render their ghost: tile-shaped markers on each valid placement cell, the span lines (drag line / rectangle outline / fill) without per-cell markers, or a translucent copy of the object's sprites on each valid cell with no markers or lines. Markers follow the TileSet shape (square, diamond or hex). |
drag_marker_texture | Property | Optional marker art for PER_OBJECT_MARKERS, stretched to one tile at each accepted placement anchor. Use transparent pixels to author any shape. Leave unset to draw the map's tile shape. OBJECT_GHOSTS uses object art instead. |
base_tile_paint_rules | Property | Global list of rules to validate for all tile paint actions. |
terrain_paint_requires_existing_cell | Property | When true, terrain painting requires an existing cell at the target position — terrain re-paints the map's surface instead of expanding into the void. When false (default, legacy behavior), painting empty space creates new cells.[br][br] [code]terrain_paint_requires_existing_cell[/code]: [i]bool[/i] - Gate terrain paints to occupied cells |
max_terrain_brush_cells | Property | Maximum cells a terrain brush operation (line, rectangle fill/outline, flood fill) can generate in a single action. Prevents frame spikes from unbounded drags. The runtime hard-ceiling is [constant BrushShapeGenerator.MAX_BRUSH_CELLS] regardless of this setting; the inspector value is clamped to [1, MAX_BRUSH_CELLS].[br][br] [code]max_terrain_brush_cells[/code]: [i]int[/i] - Per-action cell cap for terrain brush shapes |
max_object_drag_placements | Property | [code]max_object_drag_placements[/code]: [i]int[/i] - Per-gesture object-drag budget in whole-tile footprint units. The effective placement cap is this divided by the dragged entry's footprint tile count (at least 1), so a rectangle drag over a large area stays interactive for large-footprint pieces (a 7x5 smithy) instead of stamping hundreds of scenes in one frame. The drag ghost marks only the capped prefix, so preview and commit agree. |
preview_root_script | Property | Script to be added to the root of any preview instance node temporarily created by the building system after non-kept scripts are stripped out. Does not override an existing script in the root. |