> ## Documentation Index
> Fetch the complete documentation index at: https://lua.starline.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace

> Run ray and hull traces and test line segments for smoke.

Ray and hull sweeps against the game world.

```lua theme={"dark"}
local pawn = entity.GetLocalPlayer()
local from = pawn.m_pGameSceneNode.m_vecOrigin + Vector(0, 0, 64)
local to   = from + Vector(0, 0, -128)

local hit = trace.Shape(from, to, { ignore = pawn })
if hit.hit then
    print("hit", hit.entity, "at", hit.position, "n =", hit.normal)
end
```

## Shape

```lua theme={"dark"}
local hit = trace.Shape(from, to [, opts])
```

Line trace from `from` to `to`.

## Hull

```lua theme={"dark"}
local hit = trace.Hull(from, to, mins, maxs [, opts])
```

Sweeps a box (`mins`..`maxs`, local to the ray) between the two points. Mins and maxs must differ.

## Smoke

```lua theme={"dark"}
local blocked = trace.Smoke(from, to [, max_density])
```

Returns `true` if the line passes through enough smoke to block vision. `max_density` defaults `1.0`. Smoke volumes aren't in the trace world, so `Shape` and `Hull` go straight through them — test this separately.

## opts

| Key               | Default                         |                                            |
| ----------------- | ------------------------------- | ------------------------------------------ |
| `mask`            | `trace.MASK_SHOT`               | any of the mask constants, or a raw number |
| `ignore`          | none                            | entity to ignore                           |
| `ignore_alt`      | none                            | second entity to ignore                    |
| `collision_group` | `trace.COLLISION_GROUP_DEFAULT` | integer                                    |

## Result

Returned as a plain table:

| Field            |                                     |
| ---------------- | ----------------------------------- |
| `hit`            | boolean, `fraction < 1.0`           |
| `fraction`       | `0..1` along the ray                |
| `entity`         | hit entity, or `nil` if world       |
| `hitgroup`       | hitgroup id, `0` when no hitbox hit |
| `normal`         | `Vector`, surface normal            |
| `position`       | `Vector`, impact position           |
| `end_pos`        | `Vector`, where the ray ended       |
| `start_in_solid` | boolean                             |

## Constants

| Masks                    | Collision groups                |
| ------------------------ | ------------------------------- |
| `trace.MASK_SHOT`        | `trace.COLLISION_GROUP_DEFAULT` |
| `trace.MASK_SOLID`       | `trace.COLLISION_GROUP_PLAYER`  |
| `trace.MASK_PLAYERSOLID` | `trace.COLLISION_GROUP_DEBRIS`  |
| `trace.MASK_ALL`         |                                 |
| `trace.MASK_VISIBLE`     |                                 |