GridCellRaycaster3D

Finds the GridMap cell under a screen position by casting a ray from the camera. Used by GridPositioner3D. The ray checks physics objects first, then placed objects, then the ground plane, and returns the first cell it finds, or MISS.

Source: addons/grid_placement/systems/grid_targeting/grid_positioner/3d/grid_cell_raycaster_3d.gd

Syntax

class GridCellRaycaster3D extends RefCounted

Members

Name	Kind	Summary
camera	Property	Camera to cast from. Must be assigned. Not exported: GridPositioner3D owns the inspector knob and passes this in when it builds the raycaster.
grid	Property	GridMap to find cells on. Must be assigned.
ground_plane_y	Property	Height of the ground plane, in the GridMap's local space. 0 is the top of the bottom cell layer.
prefer_plane	Property	When true the cursor resolves ground_plane_y and ignores every surface under it. A storey selector, not a fallback: every 3D demo wires a level height source, which makes the plane unreachable otherwise (measured: aiming at storey 3 over the rooms level resolved the ground at (4, 0, 2)).
cursor_collision_mask	Property	Physics layers that stop the 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.
ground_extent_bypass	Property	When true the ground tier resolves any cell the ray crosses on the ground plane, ignoring the painted-extent bound. GridPositioner3D sets this while a terrain is selected: that bound keeps object hover out of the void, but painting terrain is how ground comes to exist, so a brush has to address bare plane. Bounded to the painted box, a patch could only grow one ring at a time and a new area could never be started.
plain_ground	Property	When true, a ray that strikes the side of a tall column below its top resolves the ground-plane cell under the pointer instead of the struck column. CELL placement and terrain painting need the empty cell behind a ring; INFO/MOVE/DEMOLISH and socket entries keep the side target.
last_screen_pos	Property	Last pick evidence for diagnostics and tests.
last_pick_cell	Property
last_volume_owner_cell	Property	Owner cell (the piece's own anchor) of the volume the last pick resolved through, or MISS when the pick came from physics or the ground. The hit cell alone cannot name a wide piece: its margins and pick shell map to whoever edge cell the ray entered.
last_ground_cell	Property	Ground column under the cursor — the cell the player reads as "aimed" — independent of which piece the ray struck. A stacking preview aims this cell on the next storey, so a piece wider than the one below lands where the player points instead of being pulled onto the host's anchor.
last_march_cell	Property
last_march_from_side	Property
last_ground_plane_cell	Property
MISS	Field	Sentinel returned when the ray misses the grid. The test asserts on `== MISS` rather than `== null` to make the contract explicit and to avoid Godot's null-Variant ambiguity.
cell	Property	Where a ray first crosses the ground: the cell and the world distance along the ray, or MISS and INF.
t	Property
last_ray_origin	Property	World-space ray of the most recent screen-to-cell call. The positioner mirrors it to the targeting state so hover identity resolves the record the ray hit, not the oldest record overlapping the cell column.
last_ray_dir	Property
last_pick_tier_3d	Property	Which tier of cell_from_ray() decided the most recent pick: physics (exact collider), volume (grown pick boxes), ground (marched or plane crossing), plane (legacy prefer_plane path), or miss. Restated on every pick like the owner cell; miss paths keep the default. Read-only tier label for failure evidence — the commit path never branches on it.
has_last_hit	Property	Winning hit of the most recent cell_from_ray(): one ray, one hit. Socket picks (wall edge/corner/top) resolve from the SAME hit the cell came from instead of firing an independent ground-plane ray that ignores physics and volumes. Physics wins record the exact hit + face normal; volume wins the box entry + entry-face normal; ground wins the crossing with an up normal. Cleared on miss (no stale socket input).
last_hit_position	Property
last_hit_normal	Property
last_hit_cell	Property
last_hit_collider	Property	The collider behind a physics-tier win (null for volume and ground wins, which have no physics body). Socket consumers reject a hit whose collider is not placement-relevant (set dressing, player) instead of resolving a socket from it.
placement_relevance_filter	Property	Optional placement-relevance predicate for physics candidates: called with each candidate CollisionObject3D, must return [bool]. An invalid callable accepts every candidate (legacy). The positioner wires this to its registry/grid check so rocks, dressing, and other unregistered bodies can never win the socket ray.
surface_height_source	Property	Surface-height source for cursor ground hits: a Callable taking a Vector3i column cell (x, 0, z) and returning the world-space surface height as a float, or a non-finite value (such as ObjectPlacementGeometry3D.NO_GROUND) when the column has no ground. When valid, ground hits march the ray against these heights instead of the flat ground_plane_y seed plane; when invalid the legacy plane math runs exactly as before. The 3D positioner wires the live placement support surface so the cursor and commits agree on "the ground".
SURFACE_MARCH_MAX_STEPS	Field	Hard cap on marched columns per ground hit (failsafe; horizon-grazing rays over empty columns would otherwise march to the far plane).
IRRELEVANT_SKIP_MAX	Field	Hard cap on placement-irrelevant bodies skipped per physics pick (failsafe; a dense rock pile in front of the aim must not re-query unboundedly — past the cap the volume/ground tiers take over).
SURFACE_CELL_EPSILON	Field	A surface caps the cell below it: crossings are mapped a hair under the surface so row-boundary tops (cube faces) resolve the item underneath instead of the empty row above, regardless of float noise.
VOLUME_CORE_EPS	Field	Step past the shrunk-box entry when mapping a volume hit to its cell (then clamped back inside, so oblique rays cannot punch through a thin box into the far neighbor).
VOLUME_SHRINK_MIN_SIZE	Field	Volumes thinner than this after shrinking keep the legacy entry+nudge reading: there is no core to re-enter.
GROUND_EXTENT_RING	Field	Cells beyond the painted extent that an empty ground cell may still resolve to, so the next tile can start at the edge of a level.
ray_from_screen_to_cell	Method
ray_from_screen_to_cell_occluded	Method
ray_origin	Property
ray_normal	Property
picked	Property
cell_from_ray	Method
dir	Property
world_to_grid	Property
grid_origin	Property
grid_normal	Property
plane	Property
solid_t	Property
solid_cell	Property
solid_hit	Property
best_volume_t	Property
best_volume_cell	Property
best_volume_entry	Property
best_volume_owner	Property
best_volume	Property
volume	Property
entry	Property
t	Property
owner	Property
ground	Property
ground_cell	Property
ground_t	Property
get_last_pick_evidence	Method
t	Property
local_hit	Property
candidate	Property
world_hit	Property
cell_size	Property
pos	Property
d	Property
xi	Property
zi	Property
step_x	Property
step_z	Property
t_delta_x	Property
t_delta_z	Property
frac_x	Property
frac_z	Property
t_max_x	Property
t_max_z	Property
t	Property
steps	Property
t_next	Property
y_enter	Property
y_exit	Property
h_world	Property
h_local	Property
d_enter	Property
d_exit	Property
tc	Property
local_hit	Property
map_hit	Property
candidate	Property
world_hit	Property
world_t	Property
side_hit	Property
side_cell	Property
side_t	Property
plane	Property
plane	Property
ray_intersection_point	Method
ray_ground_tracking_point	Method
cell_from_hit_point	Method