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. 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 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 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 cell_changed MISS transitions only.
LOG_PREFIX	Field
MISS	Field	Sentinel returned by ray_from_screen_to_cell() on a grid miss; same contract as [GridCellRaycaster3D.MISS].
camera	Property	Active camera, set via configure() or auto-resolved from viewport.get_camera_3d().
grid	Property	Active target grid, set via configure() or resolved from the targeting state.
session	Property	Session this positioner serves. When set, _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 input_processing_enabled.
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