Physics Query
Query the physics world with a raycast, shape cast, closest-point, or overlap test.
What it does
Asks a live Physics World a spatial question and returns numbers, not geometry. It can cast a ray, sweep a shape, find the closest surface to a point, or count what overlaps a region. It reads against the same collider shapes (ball, box, capsule, cylinder) the physics solver uses, so what it reports matches what the simulation sees.
Results come out as plain values: whether it hit, where, the surface normal, the distance, which body it hit, how many colliders it found, and whether the origin started out already inside something. Wire those into an Expression, a trigger, or a transform.
When to use it
Line-of-sight, ground detection, a laser or bullet path: Raycast
Sweeping a ball or box through the scene, stopping at the first thing it touches: ShapeCast
The closest point on any collider surface to a position, and its distance: PointQuery
Counting or gathering everything inside a region, a blast radius, a trigger volume, a proximity check: Overlap
Testing whether a point started inside a collider, for spawn checks and containment tests
| Parameter | Type | Default | What it does |
|---|---|---|---|
world_id | String | "default" | Physics world identifier |
query_type | String | "Raycast" | Query type: Raycast, ShapeCast, PointQuery, Overlap |
origin_x | Number | 0 | Query origin X |
origin_y | Number | 100 | Query origin Y |
origin_z | Number | 0 | Query origin Z |
direction_x | Number | 0 | Direction X (Raycast/ShapeCast) |
direction_y | Number | -1 | Direction Y (Raycast/ShapeCast) |
direction_z | Number | 0 | Direction Z (Raycast/ShapeCast) |
max_distance | Number | 1000 | Maximum query distance |
query_shape | String | "Ball" | Shape for ShapeCast/Overlap: Ball, Cuboid |
query_radius | Number | 5 | Radius for Ball shape |
query_half_x | Number | 5 | Half-extent X for Cuboid shape |
query_half_y | Number | 5 | Half-extent Y for Cuboid shape |
query_half_z | Number | 5 | Half-extent Z for Cuboid shape |
opacity | Number | 1 | Layer opacity (0 = transparent, 1 = opaque). Editable, wirable, keyframable. |
Gotchas
World ID has to match the identifier used by the Physics World node feeding this query. When nothing hits, check that first.
Query Type and Query Shape are typed in as plain text (Raycast, ShapeCast, PointQuery, Overlap, and Ball, Cuboid for the shape). There is no dropdown yet, so match the spelling exactly.
Direction matters for Raycast and ShapeCast only. PointQuery and Overlap ignore it and use the origin position. The default direction points straight down, which suits ground checks and is easy to forget about for other query types.
Worked example
Add a Physics Query and set World ID to match the Physics World node.
Set Query Type to
Raycast, place Origin above the scene, and leave Direction pointing down to cast toward the ground.Read Hit and Hit Distance downstream to drive a landing effect, or wire Hit Point / Hit Normal into a transform to align something to the surface.
Switch Query Type to
Overlap, set Query Shape toBall, and raise Query Radius to instead count everything within reach of a point via Hit Count.