Godot Raycasting Queries Agent Skill

Godot 4.7 Baseline

• Expert patterns in this skill target Godot 4.7+ (stable, 2026-06-18).
• Consult the Godot 4.7 migration guide when upgrading projects from 4.6.
• NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

Raycasting and Physics Queries

Physics queries allow for instantaneous detection of objects using lines (rays), volumes (shapes), or points.

Available Scripts

> MANDATORY for common paths — read before implementing (do not improvise query APIs from memory):

> - direct_space_state_raycast.gd — high-frequency intersect_ray without RayCast nodes.

> - query_exclusion_optimization.gd — RID exclude lists so casters never self-hit.

> - shapecast_ground_detection.gd — footing / volume casts when thin rays tunnel or miss.

>

> Do NOT Load every script below for one task. Open only the row that matches the decision table.

direct_space_state_raycast.gd

Expert usage of PhysicsDirectSpaceState2D/3D for bypassing node-based overhead in high-frequency queries.

shapecast_ground_detection.gd

Reliable ground/footing detection using volume-based ShapeCast instead of thin rays.

multiple_hit_piercing_ray.gd

Implementing piercing projectiles that detect and return multiple hits in a single line.

field_of_view_scanner.gd

AI sensor logic using a fan of raycasts to detect targets within a FOV cone.

raycast_reflection_logic.gd

Calculating bounces for lasers or bullets using collision normal reflection.

point_in_shape_query.gd

Checking for overlapping physics bodies at a single point (Explosion epicenters).

rest_info_3d_stuck_fix.gd

Using get_rest_info to detect stuck objects and resolve overlaps immediately.

mouse_pick_3d_query.gd

Converting 2D screen coordinates to 3D world rays for point-and-click interaction.

water_buoyancy_surface_calc.gd

Finding water surface height for buoyancy systems using high-to-low raycasting.

query_exclusion_optimization.gd

Optimizing performance by excluding specific RIDs (Resource IDs) from intersection checks.

NEVER Do in Physics Queries

• NEVER access direct_space_state outside of _physics_process() — The physics space can be locked or running on a separate thread; querying it in _process() is unsafe [1, 2].
• NEVER use ShapeCast when a thin RayCast is sufficient — Volume queries are significantly more expensive. Default to rays unless you need volumetric detection [3, 4].
• NEVER assume results return CollisionObject nodes — CSG shapes, GridMap, and TileMapLayer return themselves, not a generic physics body [5, 6].
• NEVER assume RayCast nodes update instantly — They update once per physics frame. If you move a node and query it immediately, you MUST call force_raycast_update() [3, 9].
• NEVER use complex visual meshes for physics queries — GPU-only data requires expensive thread locking to parse. Use simplified primitive collision shapes [10, 11].
• NEVER iterate results to find the first valid hit — Use collision_mask and collision_layer to filter queries at the server level for maximum performance.
• NEVER forget to exclude the caster — A ray starting from the center of a character will hit the character itself. Use query.exclude = [self.get_rid()] [20].
• NEVER use rays for small, fast detection areas — Rays can "tunnel" through thin walls if the frame rate drops. Use cast_motion or high-frequency stepping for bullets.
• NEVER query 1000+ rays individually in GDScript — Batch your queries or use the PhysicsServer directly in C++ if you reach extreme query counts.
• NEVER ignore the result.rid — RIDs are the fastest way to identify and exclude objects in subsequent queries, bypassing node-path lookups [20].

Query-Type Decision Table

Pick the cheapest API that answers the question. Always pair rays/shapes with RID exclude + masks (query_exclusion_optimization.gd).

| Need | Prefer | Cost | When | Script |

|------|--------|------|------|--------|

| Persistent sensor in the scene (ledge, aim assist debug) | RayCast2D/RayCast3D node | Low–med | Few casts; OK waiting one physics frame (or force_raycast_update()) | Scene node + NEVER rules |

| Hitscan / LOS / one-shot mid-frame ray | PhysicsDirectSpaceState*.intersect_ray | Low | High frequency, no permanent node | MANDATORY direct_space_state_raycast.gd |

| Footing, thick walls, melee volume | ShapeCast* / intersect_shape | Med–high | Thin ray tunnels or misses volume | MANDATORY shapecast_ground_detection.gd |

| Explosion / occupancy at a point | intersect_point | Low–med | Epicenter overlap list | point_in_shape_query.gd |

| Stuck / penetration resolve | get_rest_info | Med | Overlap recovery | rest_info_3d_stuck_fix.gd |

| Pierce / multi-hit along a line | Repeated intersect_ray + exclude RIDs | Med | Projectiles that keep going | multiple_hit_piercing_ray.gd |

| Screen → world click | Camera project + intersect_ray | Low | Picking | mouse_pick_3d_query.gd |

3D Mouse Picking Example

func screen_point_to_ray():
    var space_state = get_world_3d().direct_space_state
    var mouse_pos = get_viewport().get_mouse_position()
    
    var origin = project_ray_origin(mouse_pos)
    var end = origin + project_ray_normal(mouse_pos) * 2000
    
    var query = PhysicsRayQueryParameters3D.create(origin, end)
    var result = space_state.intersect_ray(query)
    
    if result:
        return result.collider
    return null

Expert WHY (query timing & LOS)

• Physics step only — direct_space_state in _physics_process, not _process.
• Self-hit — query.exclude = [get_rid()] on rays from character center.
• NavMesh LOS — physics ray ≠ carved nav hole; path.size() == 2 on NavigationServer3D.map_get_path for strict mesh LOS (see deep dive).
• Surface types — collider.get_meta(&"surface_type") beats class/group checks for decals/footsteps.
• Compute GPU rays — out of scope; not a drop-in for gameplay intersect_ray.

Deep dive (load on demand)

NavMesh LOS validator, surface metadata, picking baseline, tunneling notes — references/query-elite-patterns.md.

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API;

> load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

• Ray-casting — Node RayCast* vs PhysicsDirectSpaceState* queries, result dictionaries, and exclude to avoid self-hits.
• Physics introduction — Collision layers/masks that filter every ray, shape, and point query at the physics server.
• Collision shapes (3D) — Why queries need primitive/convex shapes instead of visual meshes for reliable, cheap intersections.
• PhysicsDirectSpaceState3D — intersect_ray / intersect_shape / intersect_point / get_rest_info / cast_motion contracts for mid-frame space queries.
• PhysicsDirectSpaceState2D — 2D twin of direct space queries for LOS, hitscan, and point epicenters without permanent cast nodes.
• PhysicsRayQueryParameters3D — Mask, exclude RIDs, hit_from_inside, and collide-with flags for reusable ray parameter objects.
• PhysicsShapeQueryParameters3D — Shape RID + transform setup for volume casts, rest info, and stuck-overlap resolution.
• PhysicsPointQueryParameters3D — Point-in-shape overlap lists for explosion epicenters and occupancy checks.
• RayCast3D — Scene-tree cast nodes, collision exceptions, and when force_raycast_update() is required after moving.
• ShapeCast3D — Volume casts and force_shapecast_update() for footing/melee detection that thin rays miss.
• Camera3D — project_ray_origin / project_ray_normal for screen-to-world picking rays from the active camera.
• Mouse and input coordinates — Viewport mouse position vs canvas/world space before building a pick ray.

Related Skills

Prerequisites

• godot-project-foundations — Named physics layers and tick settings must exist before query masks and water/ground layer bits stay coherent.
• godot-gdscript-mastery — Typed query parameters, RID arrays, and _physics_process-only space access are language-level contracts this skill depends on.
• godot-2d-physics — 2D body/area layer matrices and when to prefer RayCast2D nodes vs direct space state for sensors.

Complements

• godot-physics-3d — 3D body types, CCD, and collision setup that determine what your rays and shape casts can actually hit.
• godot-characterbody-2d — Grounding, ledges, and coyote-time feel often consume ShapeCast/ray footing results from this domain.
• godot-input-handling — Physics-step click/aim sampling couples with mouse-pick rays and hitscan timing.
• godot-navigation-pathfinding — Physics LOS vs NavMesh path-straightness checks; keep obstacle carve and collision worlds consistent.
• godot-ai-navigation — FOV fans and vision sensors feed AI perception stacks that still need correct query masks/exclusions.
• godot-performance-optimization — Budgeting hundreds of rays, reusing query params, and knowing when node casts become SceneTree overhead.
• godot-debugging-profiling — Visualizing cast lines/shapes and diagnosing missed hits from mask, exclude, or update-timing mistakes.

Downstream / consumers

• godot-combat-system — Hitscan, piercing rays, and melee volumes resolve damage from query results produced here.
• godot-genre-shooter — Hitscan weapons, bullet pierce, and aim assist consume exclusion/mask recipes and multi-hit pierce loops.
• godot-monte-carlo-balancer — View distance, FOV ray counts, pierce max-hits, and query tick rate change fairness and difficulty; simulate those knobs instead of guessing.

Master

• godot-master — Library router and mirrored entry point for discovering raycasting/query patterns alongside sibling domains.