Lua scripting

Get started

1. Open the menu and go to Scripts.
2. Type a name into New script and press Create. GriefBot writes a short starter script, switches it on and opens it in your editor.
3. Change it and save. A script that is switched on reloads every time its file is saved, so you see each change in game straight away.
4. Anything you print, and the full error when a script stops, shows in Output under the scripts.

Every script is one .lua file in your cfg\scripts folder (Open folder on the Scripts tab takes you there), and its first line must be:

-- GriefBot script

This is the whole starter script. It adds two settings to its card in the menu and draws one line of text every frame:

-- GriefBot script
local show  = ui.toggle("Show", true)
local color = ui.color("Colour", "#5aa5ff")

events.on("paint", function()
    if not show:get() then return end
    local w = client.screen()
    render.text(w / 2, 48, "Hello from Lua", color:get(), 16, "c")
end)

Scripts use Lua 5.4. If you have never written Lua, the first chapters of Programming in Lua cover everything these pages use.

How a script runs

When a script is switched on, its file runs once from top to bottom. That is where it declares its settings and registers its callbacks with events.on. After that, GriefBot calls the callbacks:

• "paint" once every frame. Draw here; drawing anywhere else does nothing.
• A game event such as "player_death" when the game fires it, just before the next paint.
• "unload" once when the script is switched off, reloaded or the overlay unloads.

Settings can only be declared while the file runs the first time, not from inside a callback. Variables at the top of the file keep their values between callbacks, and are reset when the script reloads; use storage for anything that must survive that.

Everything a script does happens on the overlay's own frame, so a slow script costs frames. The card on the Scripts tab shows how many milliseconds each script takes a frame.

Settings

A script's settings appear in its card's cog on the Scripts tab, drawn like every other setting in the menu, and are saved for you. Each call returns a handle; read it with :get() whenever you need the current value, because the user can change it at any time.

A label is 1 to 47 characters with no ##, = or line break, and is unique within its script. A script has at most 32 settings. Values are remembered by label, so renaming a setting starts it from its default.

local size  = ui.slider_int("Text size", 10, 24, 14)
local side  = ui.combo("Side", { "Left", "Right" }, 1)
local key   = ui.key("Hold to hide", "mouse4")

events.on("paint", function()
    if key:get() then return end
    local w = client.screen()
    local x = side:get() == 2 and w - 200 or 40
    render.text(x, 300, "Side: " .. side:item(), "#ffffff", size:get())
end)

Drawing

Draw from "paint". Positions are screen pixels with 0, 0 at the top left; client.screen() gives the size. Shapes are drawn over the game and under the menu, in the order you draw them. Arguments shown after the colour can be left out.

Colours

A colour is either a hex string, "#ff8800" or with transparency "#ff8800cc", or the number render.color and ui.color return. Treat that number as a value to pass on, not one to do arithmetic with.

A script can draw up to 20,000 shapes a frame.

Players and the bomb

A player

The bomb

Game events

Register a function with events.on and it receives a table with the event's name and the fields below. A field that names a player holds that player's index (look them up with entities.get), or nil when the player cannot be found, such as a bot that just left.

events.on("player_death", function(e)
    local me = entities.local_player()
    if me and e.attacker == me.index and e.headshot then
        print("Headshot with the " .. e.weapon)
    end
end)

Numbers are numbers, flags such as headshot are booleans, and weapon is the game's own name for the weapon.

Client and keys

Keys

A key is a name or a Windows virtual-key code from 1 to 255. Names are a letter "a" to "z", a digit "0" to "9", "f1" to "f24", or one of: mouse1 to mouse5, shift, ctrl, alt, lshift, rshift, lctrl, rctrl, lalt, ralt, space, enter, tab, escape, backspace, capslock, insert, delete, home, end, pageup, pagedown, up, down, left, right.

Keys read as up while the menu is open or CS2 is not the window in front, so a script never sees what you type into the menu or another program.

Storage

Values a script wants to keep between reloads and restarts: a counter, a position, a last-seen time. They are saved for you a moment after they change.

A key is 1 to 48 characters with no = or line break. A script keeps up to 64 values, and a string can be up to 512 bytes. To keep a table, keep its parts under their own keys.

local kills = storage.get("kills", 0)

events.on("player_death", function(e)
    local me = entities.local_player()
    if me and e.attacker == me.index and e.userid ~= me.index then
        kills = kills + 1
        storage.set("kills", kills)
    end
end)

The sandbox

Scripts can draw and read the game. They cannot touch your files, start programs, reach the network, or change what the game or the rest of GriefBot does. That is what makes it safe to run a script somebody else wrote.

What Lua gives you

• string, table, math, utf8 and coroutine, complete except string.dump.
• The basic functions: print, pairs, ipairs, type, tostring, tonumber, select, pcall, error, setmetatable and the rest, without dofile, loadfile and require. load takes text only.
• os.time(), os.date(format, time) and os.clock() (seconds since the script started). No other part of os, and no io or debug.
• collectgarbage with "count", "collect" or "step".
• print(...) writes to the Output panel, the values separated by two spaces.

Limits

A script that goes past a limit is stopped and says which one. pcall cannot catch running out of time: an endless loop is stopped even inside it.

When a script fails

A script that hits an error stops. Its card turns red and shows the line and the message, such as Line 12: attempt to index a nil value, and the Output panel has the full message with the chain of calls that led to it. The other scripts keep running.

Fix the file and save it: a script that is switched on starts again by itself. Reload in the card's cog runs it again without a change.

The most common error is reading a field of something that is nil, for example entities.local_player().health outside a match. Check first:

local me = entities.local_player()
if not me then return end

Sharing scripts

The Library on the Config tab has a Scripts section with scripts other members published. Get downloads one into your scripts folder, switched off, under a name that does not replace anything you have. Read it first if you like, then switch it on from the Scripts tab.

To publish your own, open its card's cog and choose Publish. You name it and describe it, and the file is published as it is saved. Your account name is shown with it. A published script must start with -- GriefBot script and be at most 256 KB.

Signed-in members can also browse the scripts on the website, in the library.

Examples

Each one is a complete script: paste it into a new file and save.

Speed

-- GriefBot script
local size = ui.slider_int("Size", 12, 32, 18)

events.on("paint", function()
    local me = entities.local_player()
    if not me or not me.alive then return end
    local v = me.velocity
    local speed = math.floor(math.sqrt(v.x * v.x + v.y * v.y))
    local w, h = client.screen()
    render.text(w / 2, h - 160, speed .. " u/s", speed > 250 and "#7ee08a" or "#ffffff", size:get(), "c")
end)

Bomb timer

-- GriefBot script
events.on("paint", function()
    local b = entities.bomb()
    if not b or not b.ticking then return end
    local text = string.format("%s  %.1f s", b.site, b.time_left)
    if b.defusing then
        text = text .. string.format("  -  defused in %.1f s", b.defuse_left)
    end
    local w = client.screen()
    render.text(w / 2, 90, text, b.time_left < 10 and "#ff6b71" or "#ffffff", 20, "c")
end)

Hit log

-- GriefBot script
local hold   = ui.slider("Show for", 1, 10, 4, "%.0f s")
local groups = { "head", "chest", "stomach", "left arm", "right arm", "left leg", "right leg" }
local lines  = {}

events.on("player_hurt", function(e)
    local me = entities.local_player()
    if not me or e.attacker ~= me.index then return end
    local victim = entities.get(e.userid)
    table.insert(lines, {
        text = string.format("Hit %s in the %s for %d (%d left)",
            victim and victim.name or "someone", groups[e.hitgroup] or "body", e.dmg_health, e.health),
        at = client.time(),
    })
end)

events.on("paint", function()
    local now = client.time()
    for i = #lines, 1, -1 do
        if now - lines[i].at > hold:get() then table.remove(lines, i) end
    end
    local y = 200
    for _, line in ipairs(lines) do
        render.text(24, y, line.text, "#e0e6f0", 14)
        y = y + 18
    end
end)

Health bars

-- GriefBot script
local color = ui.color("Bar", "#7ee08a")

events.on("paint", function()
    for _, p in ipairs(entities.players()) do
        if p.enemy and p.alive and not p.dormant then
            local tx, ty = render.world_to_screen(p.head.x, p.head.y, p.head.z + 10)
            local bx, by = render.world_to_screen(p.origin)
            if tx and bx then
                local h = by - ty
                local x = tx - h * 0.3 - 6
                local filled = h * p.health / 100
                render.rect_filled(x, ty, 3, h, "#00000099")
                render.rect_filled(x, ty + h - filled, 3, filled, color:get())
            end
        end
    end
end)