Team Fortress 2/Scripting/Script Functions/TraceLineEx

Description

bool TraceLineEx(table traceTable)

Does a raycast along a line specified by two vectors, returning the first entity or geometry hit along the way. Extended version of TraceLine and also serves as a script version of UTIL_TraceLine(). Results are written to the passed-in table.

Input

The only required information to make the trace is providing the start and end point. The rest are optional.

Name	Type	Description
start	vector	Point where to start the trace, in world coordinates.
end	vector	Point where to end the trace, in world coordinates. If the end is the same as the start, this will function as a point check, i.e. is the point inside any geometry.
mask	int	Optional contents bitmask to include or exclude common groups of geometry, such as fences, NPCs, playerclips, etc. Default mask is MASK_VISIBLE_AND_NPCS. See constants page for a list of contents and common mask types. By default this will trace against the bounding box of models only. Add CONTENTS_HITBOX to the mask to instead perform precise hitbox tests
ignore	entity	Optional entity to ignore when tracing. worldspawn cannot be ignored. Tip:To ignore or filter multiple entities, see the vscript_trace_filter library.

Output

Output written by the function to the table.

Name	Type	Description
pos	vector	Point in world coordinates where the trace ended. Equal to end position if nothing was hit.
fraction	float	Fraction from the start to end where the trace ended. E.g. 0.0 is start, 1.0 is end.
hit	bool	Whether the trace hit something.
enthit	entity	If hit, the entity that was hit. This is not written to the table if hit was false.
startsolid	bool	Whether the trace started inside geometry. This is not written to the table if it's false! Tip:Define startsolid to false in the input table so you don't have to check the key's existence.
allsolid	bool	If true, plane information is unavailable (i.e. started and ended inside geometry or didn't hit anything). This is not written to the table if it's false!
startpos	vector	Starting position of the trace in world coordinates. Probably the same thing as start.
endpos	vector	Ending position of the trace in world coordinates. Same as end if it didn't hit anything, otherwise this is the hit point.
plane_normal	vector	If hit, the normal (unit) vector of the surface.
plane_dist	float	If hit, distance of surface plane from origin. Forms a plane equation with plane_normal.
surface_name	string	If hit, name of the surface's texture that was hit. Not available for displacements or models.
surface_flags	int	If hit, bitmask of the surface flags. See FSurf constants.
surface_props	int	If hit, the surfaceprop of the surface. Note that is an index rather than a string. Todo: Describe how to interpret this .

Return

bool - False if the user didn't specify a valid start or end, true otherwise. You don't need to check this return usually.

Example

local player = GetListenServerHost()
local trace =
{
    start  = player.GetOrigin() // start from feet
    end    = player.GetOrigin() + Vector(0, 0, -64) // trace 64 units down from feet
    ignore = player // don't hit ourselves
}
TraceLineEx(trace)
// visualize the trace
DebugDrawLine(trace.startpos, trace.endpos, 255, 0, 0, false, 10.0)

if(trace.hit)
{
    printl("Trace hit!")
}
else
{
    printl("Trace missed!")
}

See the examples page for another example of how to trace triggers, which are usually not possible to trace.