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

# Trace

> Ray and bullet tracing.

Ray and bullet tracing.

## Ray traces

### line

```lua theme={null}
local result = trace.line(from, to [, skip])
local result = trace.line(from, to, { skip = ent, mask = trace.mask.visible })
```

| Field | Type | Description |
| - | - | - |
| `hit` | `bool` | Whether the ray hit anything |
| `fraction` | `number` | 0..1, how far along the ray |
| `position` | `vector` | Hit point |
| `normal` | `vector` | Surface normal |
| `entity` | `entity?` | Entity hit |
| `start_solid` | `bool` | Started inside geometry |
| `friction` | `number` | Surface friction (extended form) |

### hull

```lua theme={null}
local result = trace.hull(from, to, mins, maxs [, skip])
local result = trace.hull(from, to, mins, maxs, { skip = ent, mask = trace.mask.player })
```

Same result fields as `trace.line`.

## Bullet traces

### bullet

```lua theme={null}
local result = trace.bullet(from, to [, target, hitgroup])
```

| Field | Type | Description |
| - | - | - |
| `hit` | `bool` | Whether the bullet hit |
| `entity` | `entity?` | Entity hit |
| `damage` | `number` | Damage dealt |
| `penetrated` | `bool` | Whether the bullet penetrated a wall |
| `position` | `vector` | Final hit point |
| `range` | `number` | Distance traveled |
| `target_damage` | `number?` | Damage to specified target |
| `target_hit` | `bool?` | Whether the specified target was hit |

### damage

```lua theme={null}
local dmg = trace.damage(target, to [, hitgroup, from])
```

Autowall damage to a target entity. `hitgroup` defaults to 1 (head). `from` defaults to local eye position.

### can\_penetrate

```lua theme={null}
local ok = trace.can_penetrate(from, to)
```

### scale\_damage

```lua theme={null}
local scaled = trace.scale_damage(damage, hitgroup, target)
```

Scale raw damage by hitgroup multipliers for a target entity.

## Smoke

```lua theme={null}
local blocked, density = trace.smoke(from, to)
```

## Mask constants

| Constant | Value | Description |
| - | - | - |
| `trace.mask.visible` | `0x1C3003` | Visibility |
| `trace.mask.shot` | `0x1C300B` | Bullets |
| `trace.mask.player` | `0x1C1003` | Player collision |

## Example

```lua theme={null}
events.on('paint', function()
    local me = entity.local_pawn()
    if not me or not me:alive() then return end

    local eye = me:eye_position()
    for _, p in ipairs(entity.players()) do
        if p.pawn:alive() and p.pawn:is_enemy() then
            local head = p.pawn:hitbox(0)
            if head then
                local r = trace.line(eye, head, me)
                if not r.hit or r.entity == p.pawn then
                    -- visible
                end
            end
        end
    end
end)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.