util.TraceLine

table util.TraceLine( table traceConfig )

Description

Performs an infinitely thin, invisible Ray Trace (or "Trace") in a line based on an input Trace Structure table and returns a Trace Result table that contains information about what, if anything, the Trace line hit or intersected.

Traces intersect with the Physics Meshes of Solid, Server-side, Entities (including the Game World) but cannot detect Client-side-only Entities.
For a way to detect Client-side Entities, see ents.FindAlongRay.

Traces do not differentiate between the inside and the outside faces of Physics Meshes. Because of this, if a Trace starts within a Solid Physics Mesh it will hit the inside faces of the Physics Mesh and may return unexpected values as a result.

See util.TraceHull for a "box" type trace.

You can use r_visualizetraces set to 1 (requires sv_cheats set to 1) to visualize traces in real time for debugging purposes.

Arguments

1 table traceConfig

A table of data that configures the Trace.

For the table's format and available options see the Trace structure page.

Returns

1 table

A table of information detailing where and what the Trace line intersected, or nil if the trace is being done before the GM:InitPostEntity hook.

For the table's format and available options see the TraceResult structure page.

Example

Using a function callback as filter.

local tr = util.TraceLine( { start = LocalPlayer():EyePos(), endpos = LocalPlayer():EyePos() + EyeAngles():Forward() * 10000, filter = function( ent ) return ( ent:GetClass() == "prop_physics" ) end } ) print( tr.HitPos, tr.Entity )

Output: The trace will only hit prop_physics or world.

Example

Visualizes a trace.

local color_red = Color( 255, 0, 0 ) local color_blu = Color( 0, 0, 255 ) local mins, maxs = Vector( -24, -3, -2 ), Vector( 24, 3, 2 ) hook.Add( "PostDrawTranslucentRenderables", "trace_visualize", function() local eyePos = Entity( 1 ):EyePos() + Entity( 1 ):GetRight() * -5 local eyeDir = Entity( 1 ):GetAimVector() local tr = util.TraceLine( { start = eyePos, endpos = eyePos + eyeDir * 10000, filter = Entity( 1 ) } ) render.DrawLine( eyePos + LocalPlayer():GetRight() * -5, tr.HitPos, color_red, true ) -- Show that the traceline is a line, not a hull render.DrawWireframeBox( tr.HitPos, Angle( 0, 0, 0 ), mins, maxs, color_red, true ) eyePos = Entity( 1 ):EyePos() + Entity( 1 ):GetRight() * 5 local tr2 = util.TraceHull( { start = eyePos, endpos = eyePos + eyeDir * 10000, filter = Entity( 1 ), mins = mins, maxs = maxs } ) render.DrawLine( eyePos, tr2.HitPos, color_blu, true ) render.DrawWireframeBox( tr2.HitPos, Angle( 0, 0, 0 ), mins, maxs, color_blu, true ) end )

Output: