Team Fortress 2/Scripting/Script Functions/TraceHull

Description

bool TraceHull(table traceTable)

Does a box (AABB) sweep along a path defined by two vectors, returning the first entity or geometry hit along the way. Serves as a script version of UTIL_TraceHull. Results are written to the passed-in table. The input variables are kept in the table after the trace.

Input

The only required information to make the trace is providing the start, end points and the min/max extents. The rest are optional.

Name	Type	Description
start	vector	Position where to start the trace, in world coordinates.
end	vector	Position where to end the trace, in world coordinates. If the end is the same as the start, this will function as a clearance check, i.e. is the box touching any geometry.
hullmin	vector	The minimum extent of the box, relative to the start position.
hullmax	vector	The maximum extent of the box, relative to the start position.
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. CONTENTS_HITBOX is not supported.
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,end, hullmin or hullmax, 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, -128) // sweep downwards
    hullmin = player.GetBoundingMins() // same box size as player
    hullmax = player.GetBoundingMaxs()
    ignore  = player // don't hit ourselves
}
TraceHull(trace)
// visualize the trace, blue box is where it started, red box is where it ended
DebugDrawBox(trace.startpos, trace.hullmin, trace.hullmax, 0, 0, 255, 15, 10)
DebugDrawBox(trace.endpos, trace.hullmin, trace.hullmax, 255, 0, 0, 15, 10)

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