Ray traces

Line cast via engine TraceShape (geometry) and optional smoke density LOS (SmokeVolume_GetSmokeDensityLOS).

Thread rule (hard): only from game-thread callbacks such as on_frame_stage_notify. Errors if called from on_draw. Cache the returned table and read it when drawing.

-- cache
local g_lastTrace = nil

function on_frame_stage_notify(stage)
    -- any stage is fine; many scripts use a non-draw stage or stage 12 before on_draw
    local me = aqua.get_local_player()
    if not me or not me.origin then return end
    local eye = { x = me.origin.x, y = me.origin.y, z = me.origin.z + 64 }
    local forward = { x = eye.x + 1000, y = eye.y, z = eye.z } -- example end
    g_lastTrace = aqua.trace_ray(eye, forward, {
        walls = true,
        players = true,
        smoke = true,      -- default false
        skip_local = true, -- default true (filter skips local pawn)
    })
end

function on_draw()
    local t = g_lastTrace
    if not t then return end
    if t.hit then
        local sx, sy, vis = aqua.draw.world_to_screen(t.endpos)
        if vis then
            aqua.draw.circle(sx, sy, 4, 1, 0.2, 0.2, 1)
        end
    end
end

Signatures

Call	Notes
aqua.trace_ray(from, to [, opts])	from/to as {x,y,z} or {1,2,3}
aqua.trace_ray(fx,fy,fz, tx,ty,tz [, opts])	Six numbers

opts (all optional)

Field	Default	Meaning
walls	true	Hit world / props (solid, window, debris, …)
players	true	Hit player pawns (hitbox / player contents)
smoke	false	Smoke density LOS along free segment
skip_local	true	Engine filter skips local pawn

At least one of walls / players / smoke must be true. Geometry traces need a live local pawn (in-match). Smoke-only does not.

Return table

Field	Type	Notes
hit	bool	hit_world or hit_player or hit_smoke
fraction	number	0..1 along the ray (geometry; 1 if only smoke / miss)
hit_world	bool	Non-player geometry hit (walls)
hit_player	bool	Matched a published player pawn (players)
hit_smoke	bool	Density ≥ 0.2 (same threshold as the built-in ESP and aim)
startpos / endpos / normal	{x,y,z}	Engine start, stop, surface normal
entity_index	int?	Controller list index when hit_player
hitgroup	int?	When hitbox data present
smoke_density	number?	Present when smoke=true

Smoke is evaluated along from → endpos when geometry ran (stops at first wall/player), or from → to for smoke-only.