Configuration for [ObjectPlacementService3D]: preview tint colors and ground/support validation knobs. Runtime-instantiated: read every placement pass by ObjectPlacementService3D. Do not mark @tool.
Source: addons/grid_placement/systems/building/3d/object_placement_settings_3d.gd
Syntax
class ObjectPlacementSettings3D extends ResourceMembers
| Name | Kind | Summary |
|---|---|---|
valid_color | Property | Verdict color for VALID mount indicators. The preview ghost itself stays neutral when valid (it shows where the object lands); green verdicts live on the per-cell indicator quads. |
invalid_color | Property | Tint applied to the preview ghost AND the mount indicators when the pending placement is invalid. |
surface_offset | Property | Extra vertical offset added on top of the resolved support surface. |
require_ground_cell | Property | When true, the active support authority must resolve ground/support for the whole footprint according to the selected support policy. |
max_elevation_delta | Property | GridMap-only elevation tolerance retained for the legacy/default path. |
surface_support_mode | Property | Chooses which surface authority validates GRID CELL support. Presentation-only policy for 3D mount indicators. This never changes which mount is validated, the valid/blocked state, the resolved transform, commit behavior, or save/restore semantics — only how (and whether) the evaluated mount/support is drawn. Anchored on/just above the authoritative evaluated mount surface or slot with a normal depth relationship to the ghost. Same authoritative mount position/orientation, rendered prominently through/on top of the ghost (no depth test, raised priority). Suppress mount indicators; ghost valid/invalid tint still shows. Default remains the GridMap contract. Physics-backed support is opt-in so existing GridMap projects do not silently change placement semantics. |
max_ground_slope_degrees | Property | Maximum angle between a physics support normal and world-up. |
min_support_ratio | Property | Minimum fraction of sampled support points that must hit usable support. Individual entries can override this with ScenePlacementEntry.custom_min_support_ratio. |
max_support_planarity_error | Property | Maximum distance of any supported sample from the sampled support plane. |
world_up_clearance | Property | Maximum vertical relief a world-up structural piece may span. This is the one authoritative support-height threshold for physics-backed placement. |
require_center_support | Property | When true, an explicit footprint-center ray must hit support. |
max_unsupported_edge_ratio | Property | Maximum unsupported fraction allowed on any footprint edge. |
support_collision_mask | Property | Physics layers considered valid support. |
align_to_support_plane | Property | Optional presentation policy for small props. Structural entries should normally leave this false and remain world-up even on slopes. |
surface_scan_max_y | Property | Highest GridMap y layer probed when resolving a column's surface. |
surface_scan_min_y | Property | Lowest GridMap y layer probed when resolving a column's surface. |
indicator_presentation | Property | How 3D mount indicators are drawn. MOUNT_SURFACE (default) keeps them on the evaluated mount with normal depth; OVERLAY renders the same mount prominently through the ghost; HIDDEN suppresses indicators while ghost tint still communicates valid/invalid. Presentation only. |
default_attachment_requirement | Property | Default attachment strictness for profiles that INHERIT. OPTIONAL preserves historical free placement; REQUIRED makes INHERIT profiles demand their normal compatible attachment. |
default_corner_host_topology | Property | Default CORNER host-count policy for profiles that INHERIT: ANY_ONE accepts a single compatible host; TWO_ORTHOGONAL (default) keeps the strict historical two-perpendicular-hosts contract. |