util.TraceLine

table util.TraceLine( table traceConfig )

Description

Performs an infinitely thin, invisible ray trace (or "trace") in a line based on the input and returns a 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 unless hitclientonly is set to true.

See ents.FindAlongRay if you wish for the trace to not stop on first intersection.
See util.TraceHull for a "box" type trace.

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.

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 with Trace structure traceConfig

A table of data that configures the trace. See Trace structure for available options.

Returns

1 table with TraceResult structure

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: