GridCellRaycaster3D

Camera ray-cast helper behind [GridPositioner3D]: resolves the GridMap cell (or a solid hit) under a screen-space cursor position. Given a Camera3D, a GridMap, and a screen position, it builds the ray from [method Camera3D.project_ray_origin] / [method Camera3D.project_ray_normal], checks physics solids, placed volumes, and the configured ground plane, and returns the nearest cell, or [member MISS] when nothing is hit. It is a stand-alone Node3D helper, not a positioner: mode gating, input, and lifecycle live in [GridPositioner3D]. (Named GridPositioner3DSpike before 6.2.)

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	The camera to ray-cast through. Set it at _ready(); it is not auto-discovered.
grid	Property	The grid cells are resolved on. Same pattern as `camera`.
ground_plane_y	Property	The y-coordinate (in grid-local space) of the ground plane the ray intersects. Default 0.0 = top face of the cell layer at y=0.
cursor_collision_mask	Property	Physics layers the cursor ray stops at before the volume/ground tiers. When the ray strikes a fitted solid (wall/door/floor collision) the cursor resolves from that hit, so aiming at an object targets the object instead of the floor behind it. Empty openings (window/doorway voids carry no collision) pass through to the tiers below — correct. Ghost previews carry no collision (the 3D service neuters them), so the ray never stops at its own preview. 0 disables the tier (volume/ground cascade only).
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 [constant 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
has_last_hit	Property	Winning hit of the most recent [method 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 ([code]null[/code] 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 [constant ObjectPlacementGeometry3D.NO_GROUND]) when the column has no ground. When valid, ground hits march the ray against these heights instead of the flat [member 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.
ray_from_screen_to_cell	Method
ray_from_screen_to_cell_occluded	Method
ray_origin	Property
ray_normal	Property
cell_from_ray	Method
dir	Property
world_to_grid	Property
solid_t	Property
solid_cell	Property
solid_hit	Property
best_volume_t	Property
best_volume_cell	Property
best_volume_entry	Property
best_volume	Property
volume	Property
entry	Property
t	Property
owner	Property
grid_origin	Property
grid_normal	Property
ground	Property
ground_cell	Property
ground_t	Property
t	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
saw_height	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
ray_intersection_point	Method
ray_ground_tracking_point	Method
cell_from_hit_point	Method