GridPositioner3D

Controls the on-grid cursor used by building/interaction systems in 3D. 6.0.0-3D-Surface (Wave B1.3): production 3D positioner. Drives a [GridPlacementHost] via [_input] / [_physics_process] dispatch, resolves the camera cursor to a GridMap cell via [Camera3D] ray-cast + [GridMap.local_to_map] (through [GridCellRaycaster3D]). It self-configures from its exported session ([set_dependencies], [set_targeting_state]); the host's consumer binder skips positioners. Difference from the 2D positioner: 2D uses [Camera2D] + canvas-transform projection; 3D uses [Camera3D] + ray-cast to a ground plane. The 2D visibility/recenter/diagnostic pipeline is intentionally not mirrored; consumers use the host's mode + visibility logic instead. No extends PlacementNode2D/3D: this is a stand-alone Node3D, matching the 2D positioner, which does not extend the per-node DI base either.

Source: addons/grid_placement/systems/grid_targeting/grid_positioner_3d.gd

Syntax

class GridPositioner3D extends RefCounted

Members

Name	Kind	Summary
has_hit	Property	The last cursor pick: where the ray landed, the surface normal, the grid cell, and the collider it hit. [member has_hit] is false on a miss.
position	Property
normal	Property
cell	Property
collider	Property
cell_changed	Signal	Emitted when mouse targeting resolves a different GridMap cell, or [constant MISS] when the ray leaves the grid (sky/void). Consumers clear hover feedback on MISS; the dedupe guard suppresses repeat emits.
cell_clicked	Signal	Emitted when a mouse button is pressed while targeting a valid cell. Consumers decide what a click means; the positioner stays placement-agnostic.
cursor_moved	Signal	Emitted on EVERY mouse motion that resolves a valid cell, including same-cell repeats the [signal cell_changed] dedupe suppresses. Socket mounts (edge/face/corner/top) vary within a cell, so consumers refresh them here; without this the hover froze at the cell-boundary pick while the shared hit moved on, and the click re-picked fresh (ghost jump). Void keeps the [signal cell_changed] MISS transitions only.
LOG_PREFIX	Field
MISS	Field	Sentinel returned by [method ray_from_screen_to_cell] on a grid miss; same contract as [GridCellRaycaster3D.MISS].
camera	Property	Active camera, set via [method configure] or auto-resolved from [code]viewport.get_camera_3d()[/code].
grid	Property	Active target grid, set via [method configure] or resolved from the targeting state.
session	Property	Session this positioner serves. When set, [method _ready] self-configures and registers with the nearest [GridPlacementHost].
cursor_collision_mask	Property	Physics layers the cursor ray stops at before the volume/ground tiers (forwarded to the raycaster). 1 = fitted solids (walls/doors/floors); 0 disables the physics tier (volume/ground cascade only).
cursor_source	Property	Injected cursor-source callable returning a [Vector2] screen position; tests inject a fixed value for deterministic positioning.
ui_policy	Property	Policy answering pointer-over-UI for press gating. Games whose UI never drives viewport hover, and headless tests (hover needs a display), replace this with a custom [PositionerUIPolicy].
input_processing_enabled	Property	Enables/disables input processing; mirrors the 2D positioner's [code]input_processing_enabled[/code].
get_current_cell	Method
set_input_processing_enabled	Method
refresh_cell_from_mouse	Method
is_input_ready	Method
are_dependencies_ready	Method
set_dependencies	Method
set_targeting_state	Method
move_to_viewport_center_tile	Method
move_to_cursor_center_tile	Method
ray_from_screen_to_cell	Method
ray_from_screen_to_cell_occluded	Method
get_last_pick_hit	Method
is_placement_relevant_collider	Method
get_raycaster	Method
get_runtime_issues	Method
validate_dependencies	Method
remove_self_as_positioner	Method