Globals

Everything on this page is available in every script without any import. These are the building blocks every script starts with: scheduling work, reacting to game events, and reading per-frame state.

Overview

Timers

Schedule one-shot or repeating callbacks with setTimeout and setInterval.

console

Log, warn, error, and assert output to the script console.

Events

addEventListener for ticks, input, and engine events.

script

Metadata about the running script - name, version, author.

Timers

Standard browser-style timer API. IDs returned by setTimeout and setInterval are independent - pass the right ID to the right clear function.

setTimeout

setTimeout(callback: () => void, ms: number): number

Calls callback once after ms milliseconds. Returns a timer ID.

setTimeout(() => {
    console.log("3 seconds have passed");
}, 3000);

setInterval

setInterval(callback: () => void, ms: number): number

Calls callback repeatedly every ms milliseconds. Returns a timer ID.

const id = setInterval(() => {
    console.log("tick");
}, 1000);

clearTimeout / clearInterval

clearTimeout(id: number): void
clearInterval(id: number): void

Cancels a pending timer by its ID. Safe to call with an invalid or already-fired ID.

const id = setInterval(() => {
    console.log("tick");
}, 500);

// Stop after 5 seconds
setTimeout(() => clearInterval(id), 5000);

Cancel intervals you no longer need. They keep firing even if the entities or objects they reference have become invalid, and an interval that runs heavy work every few milliseconds costs the same as doing it in tick.

Timers do not survive a reload: every timer belonging to a script is dropped when it unloads, so a forgotten setInterval cannot pile up across hot reloads. Clearing them in onUnload is still good hygiene, not damage control.

console

console.log(...args: any[]): void      // general output
console.warn(...args: any[]): void     // warning
console.error(...args: any[]): void    // error
console.assert(cond: any, ...args: any[]): void  // logs if cond is falsy

console.log("Player HP:", player.m_iHealth);
console.warn("Entity not found for index", idx);
console.error("Critical failure:", err);

// Multiple values are space-joined
console.log("pos:", pos.x, pos.y, pos.z);

Objects print as objects

Values are formatted by an inspector, not by toString(), so structures are readable without wrapping everything in JSON.stringify:

console.log({ name: "bot", pos: { x: 1, y: 2 }, tags: ["a", "b"] });
// { name: 'bot', pos: { x: 1, y: 2 }, tags: [ 'a', 'b' ] }

console.log(new Map([["k", 1]]));      // Map(1) { 'k' => 1 }
console.log(new Uint8Array([1, 2, 3])); // Uint8Array(3) [ 1, 2, 3 ]
console.log(vec);                       // Vector(1, 2, 3)

Nesting is cut off after two levels ([Object]), long arrays and strings are truncated with a note, and cycles print as [Circular] instead of hanging.

Getters are shown as [Getter] and never invoked. Reading a property off an entity is a memory read, and logging must not have side effects - so console.log(player) will not silently read every field of the entity.

Extras

console.dir(value, { depth: 4 });   // deeper inspection
console.inspect(value, depth);      // the formatted string, no output
console.table(rows);                // aligned grid
console.group("label"); console.groupEnd();
console.time("t"); console.timeEnd("t");
console.count("hits"); console.countReset("hits");
console.trace("got here");

Printf-style placeholders work too: %s %d %i %f %o %O %j %%.

console.log("%s took %d ms", name, elapsed);

Events

Events use the standard addEventListener API. Everything a browser gives you works here - once, signal, preventDefault, custom EventTargets - see Web APIs.

addEventListener

addEventListener(type: string, listener: (event: Event) => void, options?: {
    once?: boolean;
    capture?: boolean;
    passive?: boolean;
    signal?: AbortSignal;
}): void

removeEventListener(type: string, listener: (event: Event) => void): void

addEventListener("tick", () => {
    // called every tick
});

addEventListener("keydown", (e: KeyboardEvent) => {
    if (e.code === "Insert") toggle();
}, { once: true });

The cleanest way to unregister a whole script’s worth of listeners is one AbortController:

const controller = new AbortController();
const { signal } = controller;

addEventListener("tick", onTick, { signal });
addEventListener("render", onRender, { signal });
addEventListener("keydown", onKey, { signal });

export function onUnload() {
    controller.abort();   // removes all three
}

A listener that throws does not take the script down: the error is reported through the error event and the remaining listeners still run.

on / once / off (legacy)

on(event: string, callback: (...args: any[]) => void): number
once(event: string, callback: (...args: any[]) => void): number
off(id: number): boolean

The original API, still fully supported. Handlers receive positional arguments instead of an event object, and on returns a numeric ID for off. Old event names ("OnKeyDown", "OnMouseMove", …) keep working and resolve to the same events as the modern names.

const id = on("OnKeyDown", (vk) => console.log(vk));
off(id);

// emit your own event - reaches both listener styles
emit("my-event", 1, 2);

Prefer addEventListener in new scripts: typed event objects, signal cleanup, and the same names you already know from the web.

Built-in events

Modern name	Legacy name	Event class
`tick`	`tick`	`Event`
`render`	`render`	`Event`
`unload`	-	`Event`
`keydown` / `keyup`	`OnKeyDown` / `OnKeyUp`	`KeyboardEvent`
`mousemove`	`OnMouseMove`	`MouseEvent`
`mousedown` / `mouseup`	`OnMouseClick`	`MouseEvent`
`wheel`	`OnMouseScroll`	`WheelEvent`
`error`	-	`ErrorEvent`

Input events carry the fields you would expect in a browser:

addEventListener("keydown", (e: KeyboardEvent) => {
    e.key;        // "w" - layout aware
    e.code;       // "KeyW" - physical key
    e.keyCode;    // 87 - Windows virtual key code
    e.shiftKey;   // modifiers
    e.getModifierState("Control");
});

addEventListener("mousemove", (e: MouseEvent) => {
    e.x; e.y;                       // absolute cursor position
    e.movementX; e.movementY;       // delta since the last event
    e.buttons;                      // bitmask: 1 left, 2 right, 4 middle
});

addEventListener("wheel", (e: WheelEvent) => {
    e.deltaY;   // positive when scrolling down, like the web
});

The legacy sections below describe the positional arguments the on() API passes for the same events.

`"render"`

Fires every frame when the overlay is being drawn. All Render module calls must happen inside this callback - drawing outside of it will cause flickering or missing visuals because the frame may have already been submitted.

import Render from "@native/render";

on("render", () => {
    const { x: w, y: h } = Render.getScreenSize();
    Render.text({ x: w / 2, y: 10 }, "Hello!", Color.white(), 18);
});

Never call Render.* methods from "tick", setInterval, or other non-render callbacks. The overlay only accepts draw commands during the "render" event; anywhere else the call does nothing and logs render.text() outside of a 'render' listener does nothing once.

`"tick"`

Fires on the script loop, which targets 128 Hz independently of the server tickrate and of your framerate. The primary place for logic - entity reads, state machines, calculations. Do not draw here - use "render" for that.

import Entities from "@native/entities";

on("tick", () => {
    const local = Entities.getLocalPlayer();
    if (!local) return;

    console.log(`HP: ${local.m_iHealth}, pos: ${local.m_pGameSceneNode.m_vecAbsOrigin}`);
});

`"OnMouseMove"`

on("OnMouseMove", (absX: number, absY: number, deltaX: number, deltaY: number) => void)

Param	Type
`absX`	`number`	Absolute cursor X position in screen pixels
`absY`	`number`	Absolute cursor Y position in screen pixels
`deltaX`	`number`	Change in X since the last event
`deltaY`	`number`	Change in Y since the last event

let cursorPos = { x: 0, y: 0 };

on("OnMouseMove", (absX, absY) => {
    cursorPos = { x: absX, y: absY };
});

`"OnMouseClick"`

on("OnMouseClick", (button: number, isDown: boolean) => void)

Param	Type
`button`	`number`	`0` = left, `1` = right, `2` = middle, `3` = X1, `4` = X2
`isDown`	`boolean`	`true` on press, `false` on release

on("OnMouseClick", (button, isDown) => {
    if (button === 0 && isDown) {
        console.log("Left mouse button pressed");
    }
});

`"OnMouseScroll"`

on("OnMouseScroll", (direction: number) => void)

Param	Type
`direction`	`number`	`1` = scroll up, `-1` = scroll down

on("OnMouseScroll", (dir) => {
    console.log(dir > 0 ? "Scrolled up" : "Scrolled down");
});

`"OnKeyDown"` / `"OnKeyUp"`

on("OnKeyDown", (vkCode: number) => void)
on("OnKeyUp",   (vkCode: number) => void)

Param	Type
`vkCode`	`number`	Windows Virtual Key code

const VK_INSERT = 0x2D;

on("OnKeyDown", (vk) => {
    if (vk === VK_INSERT) {
        console.log("Insert pressed");
    }
});

Virtual Key codes are listed in the Microsoft documentation. Common ones: 0x01 LMB · 0x02 RMB · 0x04 MMB · 0x10 Shift · 0x11 Ctrl · 0x12 Alt · 0x2D Insert · 0x2E Delete.

onUnload

Script cleanup is handled by exporting a function named onUnload. It is called once when the script is about to be unloaded or reloaded.

export function onUnload() {
    console.log("script unloaded");
}

const intervalId = setInterval(() => { /* ... */ }, 100);

export function onUnload() {
    clearInterval(intervalId);
    console.log("Cleaned up.");
}

const tickId = on("tick", () => { /* ... */ });
const keyId  = on("OnKeyDown", () => { /* ... */ });

export function onUnload() {
    off(tickId);
    off(keyId);
}

onUnload must be a named export at the module level. It will not fire if declared as a local variable or inside a nested function.

There is also an unload event, fired just before onUnload is called. Use whichever fits - the event works with AbortController cleanup, the export does not need a listener:

addEventListener("unload", () => {
    console.log("going away");
});

Execution budget

Script code runs on one shared worker thread, so a listener that never returns would freeze every script at once. Two thresholds guard against that:

Situation	Threshold	What happens
One event, timer or callback	250 ms	Warning in the log, nothing is interrupted
One event, timer or callback	2 s	JS is unwound, the script is stopped and marked as errored
Top-level code at load	2 s / 15 s	Same, with a larger budget for setup work

Only JavaScript time counts. A slow native call - reading a big file, scanning a whole module, an FFI call into blocking code - pauses the clock, so you are never punished for the host being slow:

import Memory from "@native/memory";

addEventListener("tick", () => {
    // The scan itself may take a second; the budget does not tick during it.
    const addr = Memory.scan("client.dll", "48 8B 05 ? ? ? ? 48 85 C0");
});

A script blocked inside a native call still holds the worker thread - there is no way to interrupt native code. Never call into something that can block forever through @native/ffi.

The 250 ms warning means you dropped a frame. If you see it every few seconds, move the work into a setInterval at a lower rate, or cache the result - see the throttling recipe below.

script

The script object exposes metadata about the currently running script. All fields are readonly.

declare var script: {
    name: string;
    version: string;
    author: string;
};

Field	Type	Description
`name`	`string`	Script display name
`version`	`string`	Version string
`author`	`string`	Author name

console.log(`${script.name} v${script.version} by ${script.author}`);

Recipes

Feature toggle with a keybind

let enabled = false;
const VK_INSERT = 0x2D;

on("OnKeyDown", (vk) => {
    if (vk === VK_INSERT) {
        enabled = !enabled;
        console.log("Feature:", enabled ? "ON" : "OFF");
    }
});

on("render", () => {
    if (!enabled) return;
    // ... draw your visuals here
});

Throttle expensive work with setInterval

import Entities from "@native/entities";
import Render   from "@native/render";

let cachedEnemies = [];

// Heavy work in a timer - not every frame
setInterval(() => {
    cachedEnemies = Entities.find("C_CSPlayerPawn")
        .filter(p => p.m_iHealth > 0)
        .toArray();
}, 100);

// Drawing in the render callback
on("render", () => {
    for (const enemy of cachedEnemies) {
        const { success, screen } = Math.worldToScreen(enemy.m_pGameSceneNode.m_vecAbsOrigin);
        if (success) Render.circleFilled(screen, 4, Color.red());
    }
});

Frame-time independent animation

import Game   from "@native/game";
import Render from "@native/render";

let alpha = 0;
let direction = 1;

on("render", () => {
    alpha += direction * 120 * Game.frameTime;

    if (alpha >= 255) { alpha = 255; direction = -1; }
    if (alpha <= 0)   { alpha = 0;   direction =  1; }

    const { x: w, y: h } = Render.getScreenSize();
    Render.text(
        { x: w / 2, y: h / 2 },
        "Hello World",
        new Color(255, 255, 255, alpha)
    );
});

Overview

Modules

Types

Overview

Timers

console

Events

script

Timers

setTimeout

setInterval

clearTimeout / clearInterval

console

Objects print as objects

Extras

Events

addEventListener

on / once / off (legacy)

Built-in events

`"render"`

`"tick"`

`"OnMouseMove"`

`"OnMouseClick"`

`"OnMouseScroll"`

`"OnKeyDown"` / `"OnKeyUp"`

onUnload

Execution budget

script

Recipes

Feature toggle with a keybind

Throttle expensive work with setInterval

Frame-time independent animation

​Overview

Timers

console

Events

script

​Timers

​setTimeout

​setInterval

​clearTimeout / clearInterval

​console

​Objects print as objects

​Extras

​Events

​addEventListener

​on / once / off (legacy)

​Built-in events

​"render"

​"tick"

​"OnMouseMove"

​"OnMouseClick"

​"OnMouseScroll"

​"OnKeyDown" / "OnKeyUp"

​onUnload

​Execution budget

​script

​Recipes

​Feature toggle with a keybind

​Throttle expensive work with setInterval

​Frame-time independent animation

Overview

Timers

setTimeout

setInterval

clearTimeout / clearInterval

console

Objects print as objects

Extras

Events

addEventListener

on / once / off (legacy)

Built-in events

`"render"`

`"tick"`

`"OnMouseMove"`

`"OnMouseClick"`

`"OnMouseScroll"`

`"OnKeyDown"` / `"OnKeyUp"`

onUnload

Execution budget

script

Recipes

Feature toggle with a keybind

Throttle expensive work with setInterval

Frame-time independent animation