GridPositioner3D

The 3D placement cursor. Finds the GridMap cell under the mouse. Casts a ray from the camera through the mouse position and reports the cell it lands on, preferring objects that block cursor_collision_mask over the ground behind them. Assign session and it connects to the nearest GridPlacementHost on its own.

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

Syntax

class GridPositioner3D extends RefCounted

Members

Name	Kind	Summary
has_hit	Property	Where the cursor ray last landed: the point, surface normal, grid cell, and the object hit. has_hit is false when nothing was hit.
position	Property
normal	Property
cell	Property
collider	Property
cell_changed	Signal	Emitted when the cursor moves to a different cell. Passes MISS when the cursor leaves the grid, such as pointing at the sky.
cell_clicked	Signal	Emitted when a mouse button is pressed over a cell.
cursor_moved	Signal	Emitted on every mouse move over the grid, even within the same cell. Use it for things that depend on where in the cell the cursor is, such as which edge or face a piece mounts on.
LOG_PREFIX	Field
MISS	Field	Sentinel returned by ray_from_screen_to_cell() on a grid miss; same contract as [GridCellRaycaster3D.MISS].
camera	Property	Camera to cast from. When empty, the viewport's active camera is used.
grid	Property	GridMap to target. When empty, the level's target grid is used.
session	Property	The player session this cursor belongs to. When set, the cursor connects to the nearest GridPlacementHost when it enters the scene.
placer_root	Property	Optional actor this cursor places for (the player). In 3D the camera is not automatically the player's inventory owner, so this stays a separate reference. The session is the authority; leave empty for actor-free placement. Assigning it at runtime rebinds the session.
previous	Property
cursor_collision_mask	Property	Physics layers that stop the cursor ray, so pointing at a wall targets the wall instead of the floor behind it. Openings without collision, such as doorways, let the ray through. Set to none to always target the ground.
cell_stick_fraction	Property	Cell-boundary hysteresis for mouse picking, as a fraction of the smaller horizontal cell size. Vertical motion in a 45-degree isometric view maps to the cell diagonal; without a dead band the pick flips between the two cells straddling that diagonal. Set to 0 to disable.
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
get_terrain_target_cell_3d	Method
get_pick_observability	Method
restore_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
get_cursor_screen_position	Method