Common knowledge

The kinds of values the API uses, and the habits that keep scripts from breaking.

Types at a glance

Colours

A colour is packed as a << 24 | b << 16 | g << 8 | r. You never need to do that by hand: use color(), color.alpha, color.lerp, color.hsv and color.unpack. Program settings (through config) store colours differently: as a table {r, g, b, a} of numbers from 0 to 1.

local c = color(255, 128, 0)
local r, g, b, a = color.unpack(c)
local as_setting = { r / 255, g / 255, b / 255, a / 255 }

Units and angles

• World positions are game units. Players are about 72 units tall standing; 1 metre is about 39.37 units.
• z is up. pos of a player is their feet.
• Angles are degrees. Yaw goes from -180 to 180; pitch from -89 (looking up) to 89 (looking down).
• Speeds are units per second. Running with a knife is 250.
• Screen positions are pixels from the top-left corner. Use draw.screen(), never a fixed resolution.
• Time is seconds as a decimal number.

nil is normal

Many values can be missing. Check before you use them, or your script stops with attempt to index a nil value.

local me = entity.local_player()
if not me or not me.bones then return end
local head = me.bones.head

Variables and scope

• Use local for everything. Globals are slower and easy to mistype.
• Locals at the top of the file keep their value between frames, for as long as the script runs.
• A reload (Save, file change, turning it off and on) starts the file over: every variable is reset. To keep something, use ui.* settings, db or files.
• Callbacks (on_frame, on_kill…) must be globals, so the program can find them. Write them as function on_frame(), not local function on_frame().
• Each script has its own world: two scripts cannot read each other's variables.

Key codes

Use these with input.key_down, input.key_pressed and as ui.keybind defaults.

Mouse

Control

Navigation

Letters and digits

Function

Sides