util
util - Utilities#
Host helpers plus the injected prelude library (targeting, aim, lead, threat helpers).
util.log#
util.log(msg)
Write a line to the debug log ([Lua] prefix).
| Parameter | Type | Default | Description |
|---|---|---|---|
msg | string | (required) | Message. |
util.distance#
util.distance(a, b) → number
3D distance between two {x,y,z} points.
| Parameter | Type | Default | Description |
|---|---|---|---|
a | table | (required) | Point {x,y,z}. |
b | table | (required) | Point {x,y,z}. |
util.screen_distance#
util.screen_distance(x1, y1, x2, y2) → number
2D pixel distance between two screen points.
| Parameter | Type | Default | Description |
|---|---|---|---|
x1 | number | (required) | |
y1 | number | (required) | |
x2 | number | (required) | |
y2 | number | (required) |
util.total_hp#
util.total_hp(e) → number
injected helper (prelude)
health + armor + shields + overhealth.
| Parameter | Type | Default | Description |
|---|---|---|---|
e | entity | (required) | Entity table. |
util.normalize_bone#
util.normalize_bone(b) → string
injected helper (prelude)
Normalize a bone picker / legacy head bool / index to 'head'|'neck'|'chest'|'pelvis'|'feet' (common synonyms accepted).
| Parameter | Type | Default | Description |
|---|---|---|---|
b | string | number | boolean |
util.bone_world#
util.bone_world(e, bone) → { x, y, z } | nil
injected helper (prelude)
World aim point for a bone - live skeleton when available, else feet/head height fractions.
| Parameter | Type | Default | Description |
|---|---|---|---|
e | entity | (required) | Entity table. |
bone | string | (required) | Bone name. |
util.bone_screen#
util.bone_screen(e, bone) → sx, sy
injected helper (prelude)
Screen coords for a bone (host screen cache for head/feet, W2S otherwise; falls back to a head/feet blend).
| Parameter | Type | Default | Description |
|---|---|---|---|
e | entity | (required) | Entity table. |
bone | string | (required) | Bone name. |
util.screen_dist#
util.screen_dist(e, [bone_or_head]) → dist, sx, sy
injected helper (prelude)
Pixel distance from the crosshair to the entity's bone. Defaults to head (legacy bool form also accepted).
| Parameter | Type | Default | Description |
|---|---|---|---|
e | entity | (required) | Entity table. |
bone_or_head | string | boolean | true (head) |
util.best_enemy#
util.best_enemy(opts) → entity | nil, dist
injected helper (prelude)
Closest-to-crosshair enemy inside FOV. opts: fov, range, vis (default true), on_screen (default true), bone (or legacy head bool).
| Parameter | Type | Default | Description |
|---|---|---|---|
opts | table | (required) | Options. |
util.sticky_enemy#
util.sticky_enemy(state, opts) → entity | nil, dist
injected helper (prelude)
best_enemy with hysteresis: keeps the previous target while it stays valid inside fov*hysteresis (default 1.4) so aim never flip-flops. state is a table the script keeps across ticks (uses e.id).
| Parameter | Type | Default | Description |
|---|---|---|---|
state | table | (required) | Per-script tracking table. |
opts | table | (required) | best_enemy opts + hysteresis. |
util.aim_at#
util.aim_at(sx, sy, [smooth], [max_step])
injected helper (prelude)
Smoothed, clamped mouse.move toward a screen point. smooth >= 1 divides the delta; max_step (default 40 px/tick) caps violent snaps.
| Parameter | Type | Default | Description |
|---|---|---|---|
sx | number | (required) | Target screen X. |
sy | number | (required) | Target screen Y. |
smooth | number | 1 | Divisor smoothing. |
max_step | number | 40 | Max pixels per tick. |
util.aim_at_bone#
util.aim_at_bone(e, bone, [smooth]) → boolean
injected helper (prelude)
Move toward a bone's screen position (util.aim_at on util.bone_screen).
| Parameter | Type | Default | Description |
|---|---|---|---|
e | entity | (required) | Entity table. |
bone | string | (required) | Bone name. |
smooth | number | 1 | Divisor smoothing. |
util.lead_world#
util.lead_world(e, bone, proj_speed, [cast_time]) → { x, y, z } | nil
injected helper (prelude)
Iterative projectile lead to a world aim point. proj_speed <= 0 = hitscan (no lead); cast_time (s) adds the windup. Falls back to the raw bone when velocity/camera are unavailable.
| Parameter | Type | Default | Description |
|---|---|---|---|
e | entity | (required) | Entity table. |
bone | string | (required) | Bone name. |
proj_speed | number | (required) | Projectile speed (m/s); 0 for hitscan. |
cast_time | number | 0 | Windup seconds added to flight time. |
util.lead_screen#
util.lead_screen(e, bone, proj_speed, [cast_time]) → sx, sy | nil
injected helper (prelude)
lead_world projected to screen; nil when the predicted point is off-screen or behind the camera.
| Parameter | Type | Default | Description |
|---|---|---|---|
e | entity | (required) | Entity table. |
bone | string | (required) | Bone name. |
proj_speed | number | (required) | Projectile speed (m/s); 0 for hitscan. |
cast_time | number | 0 | Windup seconds. |
util.cooldown#
util.cooldown(t, ms) → boolean
injected helper (prelude)
True once per ms window; stamps t.last. Use a script-local table for state.
| Parameter | Type | Default | Description |
|---|---|---|---|
t | table | (required) | State table. |
ms | number | (required) | Window in milliseconds. |
util.held#
util.held(name) → boolean
injected helper (prelude)
Canonical held-check for keybind values: mouse buttons ('Mouse1'..'Mouse5', 'left'/'right'/'middle') or a keyboard key. 'None'/nil = never held.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | (required) | Keybind value. |
util.me#
util.me() → entity | nil
injected helper (prelude)
Alive local player or nil - the single gate every script starts with.
util.ability_ready#
util.ability_ready(me, slot) → boolean
injected helper (prelude)
Ability slot readiness ('skill1' = Shift, 'skill2' = E). Unknown cooldown counts as ready.
| Parameter | Type | Default | Description |
|---|---|---|---|
me | entity | (required) | Local player entity. |
slot | string | (required) | 'skill1' |
util.hp_pct#
util.hp_pct(me) → number
injected helper (prelude)
Local HP as 0-100 percent (unknown vitals read as full).
| Parameter | Type | Default | Description |
|---|---|---|---|
me | entity | (required) | Local player entity. |
util.ult_threat_on_me#
util.ult_threat_on_me([range], [facing_deg]) → boolean, threat | nil
injected helper (prelude)
First ult threat aimed at the local player.
| Parameter | Type | Default | Description |
|---|---|---|---|
range | number | 12 | Max enemy distance (m). |
facing_deg | number | 70 | Facing cone width in degrees. |
util.ult_threat_on_mate#
util.ult_threat_on_mate([range], [facing_deg], [save_range]) → boolean, threat | nil, mate | nil
injected helper (prelude)
First ult threat aimed at a saveable teammate (alive, visible, on screen).
| Parameter | Type | Default | Description |
|---|---|---|---|
range | number | 25 | Max enemy-to-mate distance (m). |
facing_deg | number | 70 | Facing cone width in degrees. |
save_range | number | 15 | Max you-to-mate distance (m). |
Last updated 2026-10-03