Library trace

Provides functions for doing line/AABB traces and intersection tests.

Functions

computeAimVectorFromScreenPos( viewAngles, viewFOV, screenX, screenY, screenWidth, screenHeight ) Returns an aim vector based on the given view and screen parameters.
getPointContents( pos ) Returns the trace.CONTENTS_* flags that describe the contents of the given position.
intersectRayWithOBB( rayOrigin, rayDelta, boxOrigin, boxAngles, boxMins, boxMaxs ) Returns the intersection point for the given ray against the given box, in world space.
intersectRayWithPlane( rayOrigin, rayDir, planePos, planeNormal ) Returns the intersection point for the given ray on the given plane, in world space.
intersectRayWithSphere( rayOrigin, rayDelta, sphereOrigin, sphereRadius ) Returns the two intersection points for the given ray against the given sphere, in world space.
isBoxIntersectingSphere( boxMins, boxMaxs, sphereOrigin, sphereRadius ) Returns true if the given box and sphere are intersecting, false otherwise.
isOBBIntersectingOBB( box1Origin, box1Angles, box1Mins, box1Maxs, box2Origin, box2Angles, box2Mins, box2Maxs, tolerance ) Returns true if the given boxes are intersecting, false otherwise.
isPointInCone( point, coneOrigin, coneDir, coneSine, coneLength ) Returns true if the given point is contained within the given cone, false otherwise.
isRayIntersectingRay( ray1Start, ray1End, ray2Start, ray2End, tolerance ) Returns true and the intersection point if the given rays intersect, false otherwise.
isSphereIntersectingCone( sphereOrigin, sphereRadius, coneOrigin, coneDir, coneSine, coneCosine ) Returns true if the given sphere and cone are intersecting, false otherwise.
isSphereIntersectingSphere( sphere1Origin, sphere1Radius, sphere2Origin, sphere2Radius ) Returns true if the given spheres are intersecting, false otherwise.
traceEntity( ent, start, endPos, filter, mask, ignoreWorld, collisionGroup ) Does a trace using the given entity's (axis-aligned) physics object from the start position to the end position, stopping on the first surface hit.
traceHull( start, endPos, mins, maxs, filter, mask, ignoreWorld, collisionGroup ) Does a swept-AABB trace from the start position to the end position, stopping on the first surface hit.
traceLine( start, endPos, filter, mask, ignoreWorld, collisionGroup ) Does a line trace from the given start position to the given end position, stopping on the first surface hit.

Fields

MAT_ANTLION MAT_ANTLION
MAT_BLOODYFLESH MAT_BLOODYFLESH
MAT_CONCRETE MAT_CONCRETE
MAT_DIRT MAT_DIRT
MAT_EGGSHELL MAT_EGGSHELL
MAT_FLESH MAT_FLESH
MAT_GRATE MAT_GRATE
MAT_ALIENFLESH MAT_ALIENFLESH
MAT_CLIP MAT_CLIP
MAT_SNOW MAT_SNOW
MAT_PLASTIC MAT_PLASTIC
MAT_METAL MAT_METAL
MAT_SAND MAT_SAND
MAT_FOLIAGE MAT_FOLIAGE
MAT_COMPUTER MAT_COMPUTER
MAT_SLOSH MAT_SLOSH
MAT_TILE MAT_TILE
MAT_GRASS MAT_GRASS
MAT_VENT MAT_VENT
MAT_WOOD MAT_WOOD
MAT_DEFAULT MAT_DEFAULT
MAT_GLASS MAT_GLASS
MAT_WARPSHIELD MAT_WARPSHIELD
HITGROUP_RIGHTARM HITGROUP_RIGHTARM
HITGROUP_GEAR HITGROUP_GEAR
HITGROUP_GENERIC HITGROUP_GENERIC
HITGROUP_STOMACH HITGROUP_STOMACH
HITGROUP_RIGHTLEG HITGROUP_RIGHTLEG
HITGROUP_LEFTLEG HITGROUP_LEFTLEG
HITGROUP_HEAD HITGROUP_HEAD
HITGROUP_LEFTARM HITGROUP_LEFTARM
HITGROUP_CHEST HITGROUP_CHEST
MASK_OPAQUE_AND_NPCS MASK_OPAQUE_AND_NPCS
MASK_SOLID MASK_SOLID
MASK_PLAYERSOLID MASK_PLAYERSOLID
MASK_OPAQUE MASK_OPAQUE
MASK_SHOT_HULL MASK_SHOT_HULL
MASK_ALL MASK_ALL
MASK_VISIBLE MASK_VISIBLE
MASK_NPCWORLDSTATIC MASK_NPCWORLDSTATIC
MASK_DEADSOLID MASK_DEADSOLID
MASK_SPLITAREAPORTAL MASK_SPLITAREAPORTAL
MASK_CURRENT MASK_CURRENT
MASK_BLOCKLOS_AND_NPCS MASK_BLOCKLOS_AND_NPCS
MASK_NPCSOLID MASK_NPCSOLID
MASK_SOLID_BRUSHONLY MASK_SOLID_BRUSHONLY
MASK_VISIBLE_AND_NPCS MASK_VISIBLE_AND_NPCS
MASK_SHOT MASK_SHOT
MASK_NPCSOLID_BRUSHONLY MASK_NPCSOLID_BRUSHONLY
MASK_PLAYERSOLID_BRUSHONLY MASK_PLAYERSOLID_BRUSHONLY
MASK_SHOT_PORTAL MASK_SHOT_PORTAL
MASK_WATER MASK_WATER
MASK_BLOCKLOS MASK_BLOCKLOS
CONTENTS_CURRENT_270 CONTENTS_CURRENT_270
CONTENTS_DETAIL CONTENTS_DETAIL
CONTENTS_IGNORE_NODRAW_OPAQUE CONTENTS_IGNORE_NODRAW_OPAQUE
CONTENTS_BLOCKLOS CONTENTS_BLOCKLOS
CONTENTS_GRATE CONTENTS_GRATE
CONTENTS_CURRENT_0 CONTENTS_CURRENT_0
CONTENTS_AREAPORTAL CONTENTS_AREAPORTAL
CONTENTS_DEBRIS CONTENTS_DEBRIS
CONTENTS_MONSTERCLIP CONTENTS_MONSTERCLIP
CONTENTS_SLIME CONTENTS_SLIME
CONTENTS_WINDOW CONTENTS_WINDOW
CONTENTS_LADDER CONTENTS_LADDER
CONTENTS_CURRENT_180 CONTENTS_CURRENT_180
CONTENTS_TRANSLUCENT CONTENTS_TRANSLUCENT
CONTENTS_EMPTY CONTENTS_EMPTY
CONTENTS_TEAM2 CONTENTS_TEAM2
CONTENTS_CURRENT_UP CONTENTS_CURRENT_UP
CONTENTS_TESTFOGVOLUME CONTENTS_TESTFOGVOLUME
CONTENTS_TEAM1 CONTENTS_TEAM1
CONTENTS_AUX CONTENTS_AUX
CONTENTS_ORIGIN CONTENTS_ORIGIN
CONTENTS_TEAM3 CONTENTS_TEAM3
CONTENTS_WATER CONTENTS_WATER
CONTENTS_MOVEABLE CONTENTS_MOVEABLE
CONTENTS_PLAYERCLIP CONTENTS_PLAYERCLIP
CONTENTS_SOLID CONTENTS_SOLID
CONTENTS_CURRENT_DOWN CONTENTS_CURRENT_DOWN
CONTENTS_HITBOX CONTENTS_HITBOX
CONTENTS_MONSTER CONTENTS_MONSTER
CONTENTS_CURRENT_90 CONTENTS_CURRENT_90
CONTENTS_OPAQUE CONTENTS_OPAQUE
CONTENTS_TEAM4 CONTENTS_TEAM4
SURF_BUMPLIGHT SURF_BUMPLIGHT
SURF_HINT SURF_HINT
SURF_HITBOX SURF_HITBOX
SURF_LIGHT SURF_LIGHT
SURF_NOCHOP SURF_NOCHOP
SURF_NODECALS SURF_NODECALS
SURF_NODRAW SURF_NODRAW
SURF_NOLIGHT SURF_NOLIGHT
SURF_NOPORTAL SURF_NOPORTAL
SURF_NOSHADOWS SURF_NOSHADOWS
SURF_SKIP SURF_SKIP
SURF_SKY SURF_SKY
SURF_SKY2D SURF_SKY2D
SURF_TRANS SURF_TRANS
SURF_TRIGGER SURF_TRIGGER
SURF_WARP SURF_WARP
DISPSURF_BUILDABLE DISPSURF_BUILDABLE
DISPSURF_SURFACE DISPSURF_SURFACE
DISPSURF_SURFPROP1 DISPSURF_SURFPROP1
DISPSURF_SURFPROP2 DISPSURF_SURFPROP2
DISPSURF_WALKABLE DISPSURF_WALKABLE


Functions

trace.computeAimVectorFromScreenPos( viewAngles, viewFOV, screenX, screenY, screenWidth, screenHeight )
Returns an aim vector based on the given view and screen parameters. This can be used to project from screen space into a direction in world space.

Environment:

Shared

Parameters:

  • (Angle) viewAngles: The view angles in world space.
  • (number) viewFOV: The field of view in degrees.
  • (number) screenX: The x position on the screen to project from.
  • (number) screenY: The y position on the screen to project from.
  • (number) screenWidth: The width of the screen.
  • (number) screenHeight: The height of the screen.
trace.getPointContents( pos )
Returns the trace.CONTENTS_* flags that describe the contents of the given position.

Environment:

Shared

Parameters:

  • pos: The position to get the contents flags for.
trace.intersectRayWithOBB( rayOrigin, rayDelta, boxOrigin, boxAngles, boxMins, boxMaxs )
Returns the intersection point for the given ray against the given box, in world space. If no intersection occurs, nil will be returned.

Environment:

Shared

Parameters:

  • (Vector) rayOrigin: The origin of the ray.
  • (Vector) rayDelta: A vector whose direction determines the ray's direction, and whose length determines how far the ray travels.
  • (Vector) boxOrigin: The origin of the box.
  • (Angle) boxAngles: The angles of the box.
  • (Vector) boxMins: The minimum extents of the box.
  • (Vector) boxMaxs: The maximum extents of the box.

Return values:

  1. (Vector | nil) The position of the intersection point, or nil if no intersection occurs.
  2. (Vector | nil) The hit normal of the intersection, or nil if no intersection occurs.
  3. (number | nil) The fraction along the ray at which the intersection occurred (between 0 and 1), or nil if no intersection occurs.
trace.intersectRayWithPlane( rayOrigin, rayDir, planePos, planeNormal )
Returns the intersection point for the given ray on the given plane, in world space. If no intersection occurs, nil will be returned.

Environment:

Shared

Parameters:

  • (Vector) rayOrigin: The origin of the ray.
  • (Vector) rayDir: The normalised direction of the ray.
  • (Vector) planePos: A position on the plane.
  • (Vector) planeNormal: The plane's normal.
trace.intersectRayWithSphere( rayOrigin, rayDelta, sphereOrigin, sphereRadius )
Returns the two intersection points for the given ray against the given sphere, in world space. Note that the first fraction is always behind the second, and may be negative if the intersection point is behind the origin. If no intersection occurs, nil will be returned.

Environment:

Shared

Parameters:

  • (Vector) rayOrigin: The origin of the ray.
  • (Vector) rayDelta: A vector whose direction determines the ray's direction, and whose length determines how far the ray travels.
  • (Vector) sphereOrigin: The origin of the sphere.
  • (number) sphereRadius: The radius of the sphere.

Return values:

  1. (number | nil) The fraction along the ray at which the first intersection point occurred, or nil if no intersection was found.
  2. (number | nil) The fraction along the ray at which the second intersection point occurred, or nil if no intersection was found.
trace.isBoxIntersectingSphere( boxMins, boxMaxs, sphereOrigin, sphereRadius )
Returns true if the given box and sphere are intersecting, false otherwise.

Environment:

Shared

Parameters:

  • (Vector) boxMins: The minimum extents of the box.
  • (Vector) boxMaxs: The maximum extents of the box.
  • (Vector) sphereOrigin: The origin of the sphere.
  • (number) sphereRadius: The radius of the sphere.
trace.isOBBIntersectingOBB( box1Origin, box1Angles, box1Mins, box1Maxs, box2Origin, box2Angles, box2Mins, box2Maxs, tolerance )
Returns true if the given boxes are intersecting, false otherwise.

Environment:

Shared

Parameters:

  • (Vector) box1Origin: The origin of the first box.
  • (Angle) box1Angles: The angles of the first box.
  • (Vector) box1Mins: The minimum extents of the first box.
  • (Vector) box1Maxs: The maximum extents of the first box.
  • (Vector) box2Origin: The origin of the second box.
  • (Angle) box2Angles: The angles of the second box.
  • (Vector) box2Mins: The minimum extents of the second box.
  • (Vector) box2Maxs: The maximum extents of the second box.
  • (number?) tolerance: The tolerance to accept when calculating the intersection. Set to 0 for a precise test.
trace.isPointInCone( point, coneOrigin, coneDir, coneSine, coneLength )
Returns true if the given point is contained within the given cone, false otherwise.

Environment:

Shared

Parameters:

  • (Vector) point: The point to test.
  • (Vector) coneOrigin: The origin of the cone.
  • (Vector) coneDir: The direction the cone is pointing towards.
  • (number) coneSine: The sine (calculated with math.sin) of the cone's angle.
  • (number) coneLength: The height of the cone.
trace.isRayIntersectingRay( ray1Start, ray1End, ray2Start, ray2End, tolerance )
Returns true and the intersection point if the given rays intersect, false otherwise.

Environment:

Shared

Parameters:

  • (Vector) ray1Start: The start point of the first ray.
  • (Vector) ray1End: The end point of the first ray.
  • (Vector) ray2Start: The start point of the second ray.
  • (Vector) ray2End: The end point of the second ray.
  • (number?) tolerance: A tolerance value to use to determine if the rays intersect. If the rays come within this many units of each other along each axis, they will be considered to intersect. The default value is 0.0001 units.

Return values:

  1. (boolean) True if the given rays intersect, false otherwise.
  2. (number) If the rays intersect, the distance from the start of the first ray to the intersection point.
  3. (number) If the rays intersect, the distance from the start of the second ray to the intersection point.
trace.isSphereIntersectingCone( sphereOrigin, sphereRadius, coneOrigin, coneDir, coneSine, coneCosine )
Returns true if the given sphere and cone are intersecting, false otherwise.

Environment:

Shared

Parameters:

  • (Vector) sphereOrigin: The origin of the sphere.
  • (number) sphereRadius: The radius of the sphere.
  • (Vector) coneOrigin: The origin of the cone.
  • (Vector) coneDir: The direction the cone is pointing towards.
  • (number) coneSine: The sine (calculated with math.sin) of the cone's angle.
  • (number) coneCosine: The consine (calculated with math.cos) of the cone's angle.
trace.isSphereIntersectingSphere( sphere1Origin, sphere1Radius, sphere2Origin, sphere2Radius )
Returns true if the given spheres are intersecting, false otherwise.

Environment:

Shared

Parameters:

  • (Vector) sphere1Origin: The origin of the first sphere.
  • (number) sphere1Radius: The radius of the first sphere.
  • (Vector) sphere2Origin: The origin of the second sphere.
  • (number) sphere2Radius: The radius of the second sphere.
trace.traceEntity( ent, start, endPos, filter, mask, ignoreWorld, collisionGroup )
Does a trace using the given entity's (axis-aligned) physics object from the start position to the end position, stopping on the first surface hit.

Environment:

Shared

Parameters:

  • ent: The entity to use
  • start: Start position
  • endPos: End position
  • filter: Entity/array of entities/function taking entity argument to filter
  • mask: Trace mask
  • ignoreWorld: Whether to ignore the world
  • collisionGroup: The collision group(s) to hit (see ents.COLLISION_GROUP_*)

Return value:

    (TraceResult) A table containing the trace results.
trace.traceHull( start, endPos, mins, maxs, filter, mask, ignoreWorld, collisionGroup )
Does a swept-AABB trace from the start position to the end position, stopping on the first surface hit.

Environment:

Shared

Parameters:

  • start: Start position
  • endPos: End position
  • mins: Lower box corner of the hull
  • maxs: Upper box corner of the hull
  • filter: Entity/array of entities/function taking entity argument to filter
  • mask: Trace mask
  • ignoreWorld: Whether to ignore the world
  • collisionGroup: The collision group(s) to hit (see ents.COLLISION_GROUP_*)

Return value:

    (TraceResult) A table containing the trace results.
trace.traceLine( start, endPos, filter, mask, ignoreWorld, collisionGroup )
Does a line trace from the given start position to the given end position, stopping on the first surface hit.

Environment:

Shared

Parameters:

  • start: Start position
  • endPos: End position
  • filter: Entity/array of entities/function taking entity argument to filter
  • mask: Trace mask
  • ignoreWorld: Whether to ignore the world
  • collisionGroup: The collision group(s) to hit (see ents.COLLISION_GROUP_*)

Return value:

    (TraceResult) A table containing the trace results.

Valid XHTML 1.0!