Trace

Ray and hull trace results — hits, fractions, planes.

tr:DidHit():boolean

Whether the trace hit a surface.

tr:DidHitEntity():boolean

Whether the trace hit an entity.

tr:GetStartPos():Vector3

Start position of the trace.

tr:GetEndPos():Vector3

End position of the trace.

tr:GetFraction():number

Fraction of the trace travelled.

tr:GetHitbox():number

Hitbox index that was hit.

tr:GetEntity():Entity

Entity hit by the trace.

fraction:numberprop

Fraction travelled as a field.

entity:Entityprop

Hit entity as a field.

plane:Vector3prop

Hit plane normal.

contents:numberprop

Contents mask at the end point.

hitbox:numberprop

Hitbox index as a field.

hitgroup:numberprop

Hitgroup that was hit.

allsolid:booleanprop

Whether the trace started fully inside a solid.

startsolid:booleanprop

Whether the trace started inside a solid.

startpos:Vector3prop

Start position as a field.

endpos:Vector3prop

End position as a field.

Examples

Line-of-sight check

Press HOME to test whether you have a clear ray to the nearest enemy, and who blocks it.

callbacks.Register("CreateMove", function()
    if not input.IsButtonPressed(KEY_HOME) then return end

    local me = client.GetLocalPlayer()
    if not me:IsValid() then return end

    -- nearest living enemy
    local best, bestDist = nil, math.huge
    for _, ent in pairs(entities.GetPlayers()) do
        if ent:IsValid() and ent:IsAlive() and ent:GetTeam() ~= me:GetTeam() then
            local d = vector.Distance(me:GetAbsOrigin(), ent:GetAbsOrigin())
            if d < bestDist then best, bestDist = ent, d end
        end
    end
    if not best then
        print("no enemies")
        return
    end

    -- ray from your eye to their chest
    local tr = trace.Line(me:GetEyePosition(), best:GetAbsOrigin() + Vector3(0, 0, 64))
    if tr.fraction >= 0.99 or (tr:DidHitEntity() and tr:GetEntity():GetIndex() == best:GetIndex()) then
        print(string.format("clear LOS to %s", best:GetName()))
    else
        local blocker = tr:DidHitEntity() and tr:GetEntity():GetName() or "world"
        print(string.format("blocked by %s at %.1f%%", blocker, tr.fraction * 100))
    end
end)

Ground detection

Drops a ray straight down to find the floor below you, its height, and the surface normal.

local last = 0

callbacks.Register("CreateMove", function()
    local tick = globals.TickCount()
    if tick - last < 66 then return end
    last = tick

    local me = client.GetLocalPlayer()
    if not me:IsValid() then return end

    local tr = trace.Line(me:GetEyePosition(), me:GetEyePosition() - Vector3(0, 0, 2000))
    if tr:DidHit() then
        print(string.format("ground %.0f units below, normal (%.2f, %.2f, %.2f)",
            me:GetEyePosition().z - tr:GetEndPos().z, tr.plane.x, tr.plane.y, tr.plane.z))
    else
        print("nothing below")
    end
end)