Ray
Cast rays and detect collisions with geometry.
What it does
Ray casts one or more rays from a point and finds where they first touch input geometry. Each ray reports a hit position, surface normal, distance, and a reflection direction, for driving particles, lasers, line-of-sight checks, or procedural bounce patterns. With Geometry unwired, rays collide with whatever else is visible in the scene.
Rays can fan out, as a flat 2D fan or a 3D cone or sphere of rays around one direction, and can ricochet off what they hit for a number of bounces, losing energy each time. Render Mode set to None returns the collision data with no visible ray.
When to use it
A laser, line-of-sight check, or ricochet effect
The point where a straight line from an origin first touches geometry, with its normal, distance, or reflection direction
A fan or spray of rays (2D fan, or 3D cone or sphere) sampling a scene
One ray per point in a points collection rather than a single scalar origin
| Parameter | Type | Default | What it does |
|---|---|---|---|
geometry | Collection | — | Geometry to collide with |
source_points | Collection or Vec3[] | — | Points collection to cast rays from (overrides origin parameter) |
origin | Vec3 | (0, 0, 0) | Ray origin position (XYZ). Set z=0 for purely 2D rays. |
direction | Vec3 | (1, 0, 0) | Ray direction (XYZ, normalized internally). Set z=0 for purely 2D rays. |
max_length | Number | 1000 | Maximum ray distance |
angle_offset | Number | 0 | Rotate ray direction by this angle (degrees, in XY plane) |
offset | Number | 0 | Start ray this distance from origin |
max_bounces | Number | 0 | Number of bounces (0 = no bounces, just stop at first hit) |
bounce_energy_loss | Number | 0 | Energy lost per bounce. 0 = perfect reflection, 1 = stop on first hit. (Was: 'damping'.) |
ray_count | Number | 1 | Number of rays to cast |
spread_angle | Number | 360 | Angular spread across all rays (degrees) |
ray_pattern | String | "Fan" | Flat 2D fan (XY plane) or a 3D sphere/cone of rays around the direction. One of: Fan, Sphere. |
max_steps | Number | 1 | Ray march steps for SDF collision |
hit_mode | String | "First Hit" | Closest hit only / per-ray intersection count / flat hit-records collection. One of: First Hit, Count Hits, All Hits. |
render_mode | String | "Tube" | None = data-only, no visual geometry built (fastest — for collision / attribute use, e.g. casting from a large particle cloud). Tube = 3D tube ribbons (preserves Z). Path = per-ray 2D CRC paths (Z dropped). One of: None, Tube, Path. |
stroke_width | Number | 1 | Thickness of the visible ray (tube diameter / stroke width). |
color | Color | rgba(1.00, 1.00, 1.00, 1.00) | Tube color for rays that hit (linear RGBA). |
miss_color | Color | rgba(0.50, 0.50, 0.50, 1.00) | Tube color for rays that miss (linear RGBA). Default is mid-gray; set alpha < 1 to fade misses. |
analytical | Boolean | true | Analytic: emit the ray visualization as a resolution-independent CRC collection. Turn off to sweep it into a Geometry mesh for the 3D scene. |
opacity | Number | 1 | Layer opacity (0 = transparent, 1 = opaque). Editable, wirable, keyframable. |
Gotchas
Max Steps, the distance-field ray-march step count, currently has no effect. Leave it at the default.
With Geometry left unwired, rays collide against last frame's scene. That keeps the graph free of same-frame cycles, and it means a shape added this frame is not hit until the next frame.
Wiring Source Points overrides the Origin parameter and casts one ray per point using the scalar Direction. Ray Count, the fan, and Spread Angle are all ignored in that mode.
Set Bounces to 0 for a first-hit ray. Raise Bounce Energy Loss toward 1 to make bounces die out quickly, or keep it near 0 for a near-perfect mirror ricochet.
Worked example
Add a Ray. Set Origin and Direction, or wire Source Points to cast one ray per point instead.
Wire a shape or mesh into Geometry, or leave it unwired to collide with the rest of the scene.
Raise Ray Count and Spread Angle to fan the ray into a spray; switch Ray Pattern to Sphere for a 3D cone instead of a flat fan.
Raise Bounces above 0 to have the ray ricochet off what it hits, and use Bounce Energy Loss to fade it out over successive bounces.
Read Hit Points, Hit Normals, or Reflected downstream to drive particles, or set Render Mode to None if you only need the collision data.