Trace

import Trace from "@native/trace";

The Trace module casts rays and sweeps shapes through the game world using the same collision data the engine uses - static geometry, dynamic entities, and tagged collision layers.

All trace functions are synchronous and return immediately. Create a TraceFilter once and reuse it across frames - this avoids per-call allocation and lets you build up an ignore list over time.

Overview

Filters

Create reusable trace filters from presets or custom configs.

Raycasts

Single and multi-hit rays, box / sphere / capsule sweeps.

Spatial queries

Visibility, solid checks, overlap spheres, closest point.

Results

TraceResult, OverlapResult, ClosestPointResult shapes.

Filters

Every trace function accepts an optional filter that controls what the trace collides with. Filters can be passed in three forms - pick whichever fits your situation:

Form	Example
Preset string	`"bullet"`
`TraceFilter` object	`Trace.filter("bullet")`
Inline config object	`{ type: "bullet", backFaces: true }`
Omitted	Defaults to `"bullet"`

Trace.filter

Trace.filter(preset?: string): TraceFilter
Trace.filter(options: FilterOptions): TraceFilter

Creates a reusable TraceFilter. Pass a preset string for common scenarios, or a configuration object for fine-grained control.

string

default:"bullet"

One of the built-in filter presets (see table below).

Preset strings

Preset	Description
`"bullet"`	Standard bullet collision (default)
`"visibility"`	Line-of-sight checks
`"everything"`	Collide with all surfaces
`"grenade"`	Grenade collision rules
`"player_movement"`	Player movement sweep
`"occlusion"`	Occlusion culling traces

const filter = Trace.filter("bullet");
const visFilter = Trace.filter("visibility");

// No argument - defaults to "bullet"
const defaultFilter = Trace.filter();

const filter = Trace.filter({
    type: "bullet",
    static: true,
    dynamic: true,
    resolveNormals: true,
    resolveMaterials: true,
    resolveEntity: true,
    backFaces: false,
    includeTags: ["pass_bullets", "window", "sky", "ladder", "player"],
    excludeTags: ["player_clip", "npc_clip", "grenade_clip"],
});

Configuration object fields

Option	Type	Default	Description
`type`	`string`	`"bullet"`	Base preset to start from
`static`	`boolean`	`true`	Trace against static world geometry
`dynamic`	`boolean`	`true`	Trace against dynamic entities
`resolveNormals`	`boolean`	`true`	Compute surface normals on hit
`resolveMaterials`	`boolean`	`true`	Resolve surface material info on hit
`resolveEntity`	`boolean`	`true`	Populate entity info on hit
`backFaces`	`boolean`	`false`	Collide with back-facing surfaces
`includeTags`	`string[]`	-	Collision tags to include
`excludeTags`	`string[]`	-	Collision tags to exclude

Disable resolveNormals, resolveMaterials, and resolveEntity if you only care about whether something was hit - the trace runs faster when it doesn’t need to fill in extra data.

TraceFilter methods

Once you have a filter, you can tell it to skip specific entities.

filter.ignore

Adds an entity to the filter’s ignore list. Accepts a raw entity index or any object with an .index property (e.g. an Entity).

filter.ignore(entityIndex: number): void
filter.ignore(entity: { index: number }): void

const filter = Trace.filter("bullet");
const local = Entities.getLocalPlayer();

// Ignore by entity object
filter.ignore(local);

// Ignore by raw index
filter.ignore(42);

filter.clearIgnore

Clears the ignore list so the filter collides with all entities again.

filter.clearIgnore(): void

filter.clearIgnore();

Raycasts

Trace.ray

Trace.ray(start: Vector, end: Vector, filter?): TraceResult

Casts a single ray from start to end. The workhorse of the trace API - use this for hit detection, aim checks, and penetration tests.

Vector

required

Ray origin, typically the player’s eye position.

Vector

required

Ray endpoint - the target position.

string | TraceFilter | FilterOptions

Collision filter. Defaults to "bullet" if omitted.

Default filter
Preset string
Reusable filter
Inline config

const result = Trace.ray(eye, target);

const result = Trace.ray(eye, target, "bullet");

const filter = Trace.filter("bullet");
filter.ignore(local);
const result = Trace.ray(eye, target, filter);

const result = Trace.ray(eye, target, { type: "bullet", backFaces: true });

Trace.box

Trace.box(start: Vector, end: Vector, mins: Vector, maxs: Vector, filter?): TraceResult

Sweeps an axis-aligned box from start to end. mins and maxs define the box extents relative to the sweep origin.

Vector

required

Sweep origin.

Vector

required

Sweep destination.

Vector

required

Minimum corner of the box (negative offsets).

Vector

required

Maximum corner of the box (positive offsets).

string | TraceFilter | FilterOptions

Collision filter. Defaults to "bullet".

const mins = new Vector(-16, -16, 0);
const maxs = new Vector(16, 16, 72);

const result = Trace.box(start, end, mins, maxs, "player_movement");
if (result.hit) {
    console.log("Blocked at", result.position);
}

Trace.sphere

Trace.sphere(start: Vector, end: Vector, radius: number, filter?): TraceResult

Sweeps a sphere from start to end.

Vector

required

Sweep origin.

Vector

required

Sweep destination.

number

required

Sphere radius in game units.

string | TraceFilter | FilterOptions

Collision filter. Defaults to "bullet".

const result = Trace.sphere(start, end, 8.0, "grenade");

Trace.capsule

Trace.capsule(start: Vector, end: Vector, radius: number, halfHeight: number, filter?): TraceResult

Sweeps a capsule (cylinder with hemispherical caps) from start to end. Useful for simulating player-sized collision hulls.

Vector

required

Sweep origin.

Vector

required

Sweep destination.

number

required

Capsule radius.

number

required

Half the height of the cylindrical section.

string | TraceFilter | FilterOptions

Collision filter. Defaults to "bullet".

const result = Trace.capsule(start, end, 16.0, 36.0, "player_movement");

Trace.rayAll

Trace.rayAll(start: Vector, end: Vector, filter?, maxHits?: number): TraceResult[]

Casts a ray and returns all hits along the path, not just the first. Useful for penetration simulation - you get every surface the ray passes through.

Vector

required

Ray origin.

Vector

required

Ray endpoint.

string | TraceFilter | FilterOptions

Collision filter. Defaults to "bullet".

number

default:"32"

Maximum number of hits to return. Clamped to 1..128.

const hits = Trace.rayAll(eye, target, "bullet", 8);

for (const hit of hits) {
    console.log(`Hit at fraction ${hit.fraction.toFixed(3)}`);
    if (hit.surface) {
        console.log(`  Material: ${hit.surface.name}`);
    }
}

Spatial queries

Fast utility functions that answer spatial questions without giving you a full TraceResult.

Trace.isVisible

Trace.isVisible(from: Vector, to: Vector): boolean

The fastest way to check line of sight. Returns true if nothing blocks the path between from and to. Skips normal, material, and entity resolution entirely - just a yes/no answer.

Vector

required

Start position (e.g. eye position).

Vector

required

Target position (e.g. enemy head).

import Entities from "@native/entities";

const local = Entities.getLocalPlayer();
const enemy = Entities.getPlayers({ skipLocal: true })[0];

const localPos = local.m_pGameSceneNode.m_vecAbsOrigin;
const enemyPos = enemy.m_pGameSceneNode.m_vecAbsOrigin;

if (Trace.isVisible(localPos, enemyPos)) {
    console.log("Target is visible");
}

Use isVisible over Trace.ray when you only need a boolean - it’s significantly faster because it doesn’t resolve any hit data.

Trace.isSolid

Trace.isSolid(point: Vector): boolean

Returns true if the given point is inside solid geometry. Useful for checking whether a calculated position is valid or stuck in a wall.

Vector

required

World position to test.

if (Trace.isSolid(position)) {
    console.log("Point is inside a wall");
}

Trace.overlapSphere

Trace.overlapSphere(origin: Vector, radius: number, filter?): OverlapResult[]

Returns all colliders overlapping a sphere centered at origin.

Vector

required

Center of the sphere.

number

required

Sphere radius in game units.

string | TraceFilter | FilterOptions

Collision filter. Defaults to "bullet".

import Entities from "@native/entities";

const local = Entities.getLocalPlayer();
const localPos = local.m_pGameSceneNode.m_vecAbsOrigin;

const nearby = Trace.overlapSphere(localPos, 256.0);

for (const overlap of nearby) {
    if (overlap.entity) {
        console.log(`${overlap.entity.className} - depth: ${overlap.depth}`);
    }
}

Trace.closestPoint

Trace.closestPoint(origin: Vector, maxDistance: number, filter?): ClosestPointResult

Finds the closest point on any surface within maxDistance of origin.

Vector

required

Search center.

number

required

Maximum search radius in game units.

string | TraceFilter | FilterOptions

Collision filter. Defaults to "bullet".

import Entities from "@native/entities";

const local = Entities.getLocalPlayer();
const localPos = local.m_pGameSceneNode.m_vecAbsOrigin;

const closest = Trace.closestPoint(localPos, 128.0);
if (closest.hit) {
    console.log(`Nearest wall at distance ${closest.distance.toFixed(1)}`);
}

Results

TraceResult

Returned by Trace.ray, Trace.box, Trace.sphere, Trace.capsule, and each element of Trace.rayAll.

Property	Type	Description
`hit`	`boolean`	Whether the trace hit anything
`fraction`	`number`	`0..1` - how far along the path the hit occurred
`position`	`Vector`	Impact point in world space
`normal`	`Vector`	Surface normal at the impact point
`startSolid`	`boolean`	`true` if the trace started inside solid geometry
`allSolid`	`boolean`	`true` if the entire trace was inside solid
`hitSky`	`boolean`	Hit the skybox
`hitWindow`	`boolean`	Hit a window surface
`hitLadder`	`boolean`	Hit a ladder surface
`hitPassBullets`	`boolean`	Hit a pass-bullets surface
`entity`	`object \| null`	Entity info (see below)
`surface`	`object \| null`	Surface material info (see below)

entity - populated when resolveEntity is true and the trace hit a dynamic entity:

Property	Type
`className`	`string`	Entity class name, e.g. `"C_CSPlayerPawn"`
`handle`	`number`	Entity handle
`origin`	`Vector`	Entity origin

surface - populated when resolveMaterials is true:

Property	Type
`name`	`string`	Material name
`penetration`	`number`	Penetration factor (higher = easier to shoot through)
`damage`	`number`	Damage modifier for this surface

const result = Trace.ray(eye, target);

if (result.hit) {
    console.log(`Hit at ${result.position}, fraction: ${result.fraction}`);

    if (result.entity) {
        console.log(`Entity: ${result.entity.className}`);
    }
    if (result.surface) {
        console.log(`Material: ${result.surface.name}`);
        console.log(`Penetration: ${result.surface.penetration}`);
    }
}

OverlapResult

Returned by each element of Trace.overlapSphere.

Property	Type	Description
`position`	`Vector`	Contact point
`normal`	`Vector`	Contact normal
`depth`	`number`	Penetration depth
`entity`	`{ className: string } \| null`	Entity class if the overlap is with an entity

ClosestPointResult

Returned by Trace.closestPoint.

Property	Type	Description
`hit`	`boolean`	Whether a surface was found within range
`position`	`Vector`	Closest point on the surface
`normal`	`Vector`	Surface normal at that point
`distance`	`number`	Distance from origin to the closest point

Collision tags

Tags control which collision layers are included or excluded in a filter’s includeTags / excludeTags arrays.

Tag	Description
`"pass_bullets"`	Surfaces that bullets pass through
`"player_clip"`	Player clip brushes - block players, not bullets
`"npc_clip"`	NPC clip brushes
`"grenade_clip"`	Grenade clip brushes
`"ladder"`	Ladder surfaces
`"window"`	Breakable windows
`"sky"`	Skybox surfaces
`"player"`	Player collision hulls

Recipes

Fast visibility check

Trace.isVisible is the fastest way to check line of sight - it skips normal / material / entity resolution and just returns a boolean.

const local = Entities.getLocalPlayer();
if (!local) return;

const myEyes = local.m_pGameSceneNode.m_vecAbsOrigin;

for (const enemy of Entities.getPlayers({ skipLocal: true })) {
    if (enemy.m_iHealth <= 0) continue;

    const head = enemy.m_pGameSceneNode.m_vecAbsOrigin;
    if (Trace.isVisible(myEyes, head)) {
        console.log(`${enemy.controller?.m_iszPlayerName} is visible`);
    }
}

Ground trace

import Entities from "@native/entities";

const local = Entities.getLocalPlayer();
if (!local) return;

const feet = local.m_pGameSceneNode.m_vecAbsOrigin;
const below = new Vector(feet.x, feet.y, feet.z - 64);

const ground = Trace.ray(feet, below, "player_movement");
if (ground.hit) {
    console.log(`Ground at Z=${ground.position.z.toFixed(1)}`);
    console.log(`Normal: ${ground.normal}`);
}

Overview

Modules

Types

Overview

Filters

Raycasts

Spatial queries

Results

Filters

Trace.filter

TraceFilter methods

Raycasts

Trace.ray

Trace.box

Trace.sphere

Trace.capsule

Trace.rayAll

Spatial queries

Trace.isVisible

Trace.isSolid

Trace.overlapSphere

Trace.closestPoint

Results

TraceResult

OverlapResult

ClosestPointResult

Collision tags

Recipes

Fast visibility check

Ground trace

​Overview

Filters

Raycasts

Spatial queries

Results

​Filters

​Trace.filter

​TraceFilter methods

​Raycasts

​Trace.ray

​Trace.box

​Trace.sphere

​Trace.capsule

​Trace.rayAll

​Spatial queries

​Trace.isVisible

​Trace.isSolid

​Trace.overlapSphere

​Trace.closestPoint

​Results

​TraceResult

​OverlapResult

​ClosestPointResult

​Collision tags

​Recipes

​Fast visibility check

​Ground trace

Overview

Filters

Trace.filter

TraceFilter methods

Raycasts

Trace.ray

Trace.box

Trace.sphere

Trace.capsule

Trace.rayAll

Spatial queries

Trace.isVisible

Trace.isSolid

Trace.overlapSphere

Trace.closestPoint

Results

TraceResult

OverlapResult

ClosestPointResult

Collision tags

Recipes

Fast visibility check

Ground trace