GridPositioner3D

Controls the on-grid cursor used by building/interaction systems in 3D. 6.0.0-3D-Surface (Wave B1.3): production 3D positioner, the public-facing 3D surface for placement targeting. The 3D positioner:

• Drives a [GridPlacementHost] via [_input] / [_physics_process] dispatch (parallel to the 2D positioner's contract)
• Resolves camera cursor → GridMap cell via [Camera3D] ray-cast + [GridMap.local_to_map] (via [GridPositioner3DSpike])
• Mirrors the 2D positioner's DI lifecycle ([resolve_placement_dependencies], [set_dependencies], [set_targeting_state]) Difference from the 2D positioner: the 2D positioner uses a [Camera2D] + canvas-transform projection; the 3D positioner uses a [Camera3D] + ray-cast to a ground plane (the spike's math). The 2D positioner also carries a full visibility reconciliation + recenter policy + diagnostic pipeline (965 lines) which is intentionally NOT mirrored in Wave B1; consumers of the 3D surface use the host's mode + visibility logic instead, parallel to how the 2D services were refactored in 6.0.0-S. No extends PlacementNode2D/3D: the 2D positioner does not extend the per-node DI base class either, and the 6.0.0-S refactor moved dependencies to the host + session model. Mirroring that means the 3D positioner is a stand-alone Node3D, not a custom base.

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

Syntax

class GridPositioner3D extends Node3D

Members

Name	Kind	Summary
cell_changed	Signal	Emitted when mouse targeting resolves a different GridMap cell.
cell_clicked	Signal	Emitted when a mouse button is pressed while targeting a valid cell. Consumers (e.g. [ObjectPlacementService3D] wiring) decide what a click means; the positioner stays placement-agnostic.
LOG_PREFIX	Field
MISS	Field	The sentinel returned by [method ray_from_screen_to_cell] when the ray misses the grid. Same contract as [GridPositioner3DSpike.SPIKE_MISS].
camera	Property	The active camera. Either set via [method configure] (preferred) or auto-resolved from the viewport if the positioner is the current camera's parent. The 2D positioner auto-resolves from [code]viewport.get_camera_2d()[/code]; the 3D version auto-resolves from [code]viewport.get_camera_3d()[/code] as a fallback.
grid	Property	The active target grid. Either set via [method configure] or resolved from the targeting state.
cursor_source	Property	Injected cursor-source callable. Returns a [Vector2] screen position (parallel to the 2D positioner's [code]cursor_source[/code]). Tests inject a fixed Vector2 for deterministic positioning.
input_processing_enabled	Property	Public flag & API for enabling/disabling input processing. Mirrors the 2D positioner's [code]input_processing_enabled[/code].
resolve_placement_dependencies	Method
set_input_processing_enabled	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_or_null	Method
ray_from_screen_to_cell	Method
get_spike	Method
move_positioner_by_tile	Method
get_runtime_issues	Method
validate_dependencies	Method
remove_self_as_positioner	Method