ObjectPlacementService3D | Grid Placement Docs

Scene-free 3D object placement service ( v1, ground snapping). Owns the preview ghost, validity evaluation, and placement commit for 3D sessions. Production addon code (not demo code) because valid/invalid preview feedback is core placement UX every 3D consumer needs; demos and games only wire it to their positioner/UI. Validity rules (evaluated in order, all must pass): 1. an active [ScenePlacementEntry] with a packed_scene is selected 2. no footprint cell is already occupied by a placed object 3. every footprint column has resolvable ground on the GridMap (when [member ObjectPlacementSettings3D.require_ground_cell]) 4. the surface elevation delta across the footprint stays within [member ObjectPlacementSettings3D.max_elevation_delta] ("too steep") 5. the entry's [PlacementSnapProfile3D] adjacency requirement is met (when [member PlacementSnapProfile3D.require_adjacent_snap]) Ground resolution: each footprint column is scanned top-down through the GridMap ([member ObjectPlacementSettings3D.surface_scan_max_y] .. [member ObjectPlacementSettings3D.surface_scan_min_y]); the first occupied cell's mesh AABB top is the walkable surface, so slabs, full blocks, and stacked blocks all resolve without per-item configuration. Objects rest on the HIGHEST surface under their footprint. Cell items are assumed unrotated (v1); socket-level snapping is . Visual feedback decision (see the draft guide): the ghost's meshes are TINTED via material_override (valid/invalid colors from settings) instead of spawning 2D-style indicator cubes. In 3D, per-cell indicator geometry occludes the scene and duplicates draw work; the tinted ghost communicates validity, final position, and footprint in a single visual.

Source: addons/grid_placement/systems/building/3d/object_placement_service_3d.gd

Syntax

class ObjectPlacementService3D extends RefCounted

Members

Name	Kind	Summary
`object_placed`	Signal	Emitted after a successful [method try_place_at] commit.
`preview_validity_changed`	Signal	Emitted when the preview ghost flips between valid and invalid.
`active_entry_changed`	Signal	Emitted when the authoritative active entry changes, including clears (null). Observers such as the catalog selection UI must render this state instead of tracking their own parallel selection.
`MISS`	Field	Sentinel matching [constant GridPositioner3D.MISS].
`NO_GROUND`	Field	Returned by [method resolve_surface_height] when a column has no ground.
`configure`	Method
`get_settings`	Method
`is_configured`	Method
`set_active_entry`	Method
`get_active_entry`	Method
`update_preview_cell`	Method
`is_preview_valid`	Method
`get_preview_cell`	Method
`clear_preview`	Method
`rotate_preview`	Method
`get_preview_yaw_steps`	Method
`preview_yaw_degrees`	Method
`validate_cell_map`	Method
`footprint_is_entirely_void`	Method
`validate_cell`	Method
`try_place_report`	Method
`populate_surface_metadata`	Method
`try_place_at`	Method
`is_cell_occupied`	Method
`get_placed_node`	Method
`get_family_at`	Method
`get_placed_count`	Method
`is_edge_occupied`	Method
`is_face_registered`	Method
`is_face_occupied`	Method
`validate_edge`	Method
`update_preview_edge`	Method
`try_place_at_edge`	Method
`validate_face`	Method
`update_preview_face`	Method
`try_place_at_face`	Method
`instance_id`	Property
`projections`	Property
`provider_faces`	Property
`projections`	Property
`provider_faces`	Property
`result`	Property
`yaw_steps`	Property
`cells`	Property
`profile`	Property
`key`	Property
`edge_key`	Property
`profile`	Property
`face_key`	Property
`face_key`	Property
`occupancy_key`	Property
`world_aabb_for_mount`	Method
`unregister_placed_node`	Method
`unregister_placed_node_local`	Method
`local_snapshot`	Property
`world_record`	Property
`snapshot`	Property
`update_placed_node`	Method
`old_grid_cell`	Property
`new_grid_cell`	Property
`profile`	Property
`family`	Property
`cells`	Property
`edge_profile`	Property
`height_band`	Property
`dispose`	Method
`clear_placement_registries`	Method
`snapshot_placement_state`	Method
`restore_placement_state`	Method
`rehydrate_cell_object`	Method
`yaw_steps`	Property
`profile`	Property
`family`	Property
`cells`	Property
`mount`	Property
`rehydrate_edge_object`	Method
`mount`	Property
`profile`	Property
`rehydrate_face_object`	Method
`mount`	Property