POST /raycast
Since 0.6
One ray { from, dir, … }, or several under { "rays": [...] }.
The body is read as JSON first and matched here rather than by Body, so a body of neither shape is told what the endpoint takes (RAYCAST_BODY) and not only which field was missing.
Request
Body fields
| field | default | Notes |
|---|---|---|
exclude | none | an entity id, or a list of them, the ray passes straight through. An id the scene does not have is a 404 |
exclude_tags | none | a tag, or a list; every entity carrying one is passed through too |
triggers | true | whether trigger volumes count as hits, as ctx.world.raycast has it |
Request body: RaycastRequest
POST /raycast request: one ray.
| Field | Type | Required | Description |
|---|---|---|---|
from | number[3] | yes | Ray origin in world space, [x, y, z]. origin is accepted for it: agents guessed { origin, direction, maxDistance } three runs in a row and were refused each time. |
dir | number[3] | yes | Ray direction. Need not be normalized, but must not be the zero vector. direction is accepted for it. |
max | number | no | Maximum distance in metres. Defaults to 1000. maxDistance and max_distance are accepted for it. |
exclude | string[] | no | Entity ids the ray passes straight through: an id or a list of them. A ray cast down from above the player starts outside its capsule and hits it first; "exclude": "player" sees past it. An id the scene does not have is a 404, so a typo is not a silent no-op. |
exclude_tags | string[] | no | Every entity carrying any of these tags is passed through as well: a tag or a list. excludeTags, as ctx.world.raycast spells it, is accepted for it. |
triggers | boolean | no | Whether trigger volumes count as hits. Default true, as ctx.world.raycast has it; pass false for a line of sight or a ground probe that should see through a volume. |
Request body: RaycastBatch
POST /raycast with { "rays": [ … ] }: several rays, cast on one frame, answered in order.
| Field | Type | Required | Description |
|---|---|---|---|
rays | RaycastRequest[] | yes | The rays, each the single-ray body. |
Response
Response: HitView
What a ray found. POST /raycast responds with this or with null.
| Field | Type | Present | Description |
|---|---|---|---|
entity | string | always | The entity the ray struck, by id. |
point | number[3] | always | World-space point of impact. |
normal | number[3] | always | Surface normal at the impact point. |
distance | number | always | Distance from from along the normalized direction, in metres. |
frame | integer | always | The frame the cast ran on. |
Example
curl -X POST "http://127.0.0.1:7700/raycast" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.