Team Fortress 2/Scripting/Script Functions/TraceLineEx
Contents
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 |
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.