GridPositioner3D | Grid Placement Docs

Draft — Unreleased:This page is in active development. APIs, class names, and behavior may change before the release is finalized. Use it as a preview of what's coming — not as a stable integration target.

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`	Event	Emitted when mouse targeting resolves a different GridMap cell.
`cell_clicked`	Event	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
`click`	Property
`clicked_cell`	Property
`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
`viewport`	Property
`screen_center`	Property
`move_to_cursor_center_tile`	Method
`screen_pos`	Property
`ray_from_screen_to_cell_or_null`	Method
`cell`	Property
`ray_from_screen_to_cell`	Method
`get_spike`	Method
`move_positioner_by_tile`	Method
`grid_ref`	Property
`get_runtime_issues`	Method
`issues`	Property
`validate_dependencies`	Method
`issues`	Property
`remove_self_as_positioner`	Method
`viewport`	Property
`viewport`	Property
`result`	Property
`world_hit`	Property
`cell`	Property
`grid_ref`	Property

Source

addons/grid_placement/systems/grid_targeting/grid_positioner_3d.gd

Plugin docs root:gdscript/plugins/grid_placement_dev/docs