Queues a PNG capture. The default — no overlay, no region — saves the raw capture frame, pixel for pixel at the frame's own resolution, straight off the card and after mods' OnFrame mutations: what the reader sees is what lands in the file, whatever size the window is or how the picture is scaled into it. Fulfilled on a background thread, so it never stalls rendering. A relative path is resolved against the app's screenshots/ folder; omit it for an auto-named file.

The other two shapes photograph the rendered window instead: overlay = true (options-table form, screenshot(path, { overlay = true })) captures after the overlay draws, panels and HUD included — the built-in screenshot addon binds this to O, with P on the raw frame. A region (all four of x, y, w, h, in window pixels) also reads from the window, because that is the space its coordinates live in. Window-based shots are scaled by the display fit; only the default form is fixture-grade.

hook.Add("KeyPress", "mymod", function(key)
    if key == "F12" then
        screenshot("screenshots/grab_" .. os.time() .. ".png")   -- whole frame
    elseif key == "F11" then
        screenshot("screenshots/hud.png", 20, 20, 260, 90)       -- just a region
    end
end)

Plays a small WAV once — UI feedback, not a music system. The sound is mixed over the passthrough audio on its own stream and follows the app's output volume, so a muted instance stays silent. path is resolved against the app's data root exactly like image paths ("addons/<mod>/click.wav"); absolute paths and .. are refused. Returns false if the file could not be loaded or played. Keep files short — the whole file is queued at once.

-- a shutter click alongside a screenshot (see the screenshot addon)
screenshot(name)
if sound and sound.play then                -- guard for older engines
    sound.play("addons/" .. MOD_NAME .. "/shutter.wav")
end

Start or stop keeping a copy of the console's sound as it passes through to the speakers — for a mod that wants to record it. Nothing is buffered until a mod asks, and switching it off drops whatever was held, so a recorder that is turned off costs nothing. sound.capturing() answers whether it is on.

Everything captured since the last call, plus the format it is in. The bytes are raw interleaved PCM exactly as the passthrough has them — no conversion, so writing them straight into a WAV or an AVI's audio stream is lossless. Returns an empty string when nothing has arrived. Takes no parameters.

-- collected in Think, where calling into Lua is safe
sound.capture(true)
function g:Think()
    local pcm, ch, rate, bits, isFloat = sound.take()
    if #pcm > 0 then keep(pcm, perf.nowMs()) end
end

Writes a line to the console/log stream, prefixed with [mod]. Handy for debugging.

The addon's folder name. Also the name of your private data folder (data/<MOD_NAME>/).

What your mod.txt says this copy's version is, as "major.minor.patch" — "0.0.0" when there is no manifest. Handy for a "did the update land?" line in your own logging.

Which copy of your mod is running: ".ccmod" for the package, "file" for a loose folder. A mod can exist twice on one machine and the versions decide which one wins, so after an update "did my edit take, or the download?" is otherwise only answerable from the startup log. The engine shows this beside the version in the mod's settings header; you get the same string if you want it yourself.

Install a skin: one table of sections that every native widget falls back to. This is the whole redesign surface — a mod that styles nothing follows the installed skin, a mod that styled something keeps exactly what it asked for, and with no skin everything is the engine's built-in look. Resolution order is always widget style → theme section → built-in default.

Pass nil to take a skin back off. You rarely need to: unloading the mod that called this clears its skin automatically, so removing a skin mod restores the stock look with nothing to undo.

overlay.setTheme({
    overlay = { scrim = {14,20,27,204} },
    panel   = { bg = {35,38,46,242}, border = {61,68,80,255} },
    button  = { bg = {61,68,80,255}, bgHover = {26,159,255,255},
                bgActive = {26,159,255,255}, fg = {220,222,223,255} },
    menu    = { dir = "row", anchor = "bottom", w = 170, h = 40, gap = 8,
                -- the fill is transparent so the art's corners survive
                bg = {0,0,0,0}, bgHover = {0,0,0,0},
                bgImage      = "addons/" .. MOD_NAME .. "/skin/toolbar.png",
                bgImageHover = "addons/" .. MOD_NAME .. "/skin/toolbar_hover.png" },
})

The installed skin, or nil. For reading colours out of a skin see overlay.themeColor below — it handles the "no skin" case for you.

One colour out of the installed skin, falling back to the four values you pass. Returns them as four numbers, so it drops straight into d:text / d:rect. This is how something that draws its own pixels — a paint function — follows a skin instead of being the one part of the screen that ignores it. overlay.themeNum(section, key, def) and overlay.themeStr(section, key, def) are the same idea for numbers and strings.

function el.paint(d)
    d:rect(0, 0, 200, 40, overlay.themeColor("panel", "bg", 40, 42, 54, 235))
end

On a button widget: what the button means, leaving what it looks like to the skin. "active" for a toggle that is on or the selected one of a set, "danger" for the ones that delete, "neutral" (the default) for the rest. The theme is consulted per role — bgActive, bgDanger — at DRAW time, which is what lets a skin loaded later restyle a button built earlier. A style.bg of your own still wins over both.

{ type = "button", text = "Sound: ON", role = "active", style = { font = 14 } }

Whether the overlay menu is up, right now. Unlike MOD_NAME and friends this one changes as the user opens and closes it, and the engine keeps it current the moment the state changes — read it from anywhere: a Think, a paint, a "KeyPress" handler, a helper three files away. overlay.isOpen() is the same fact as a function call.

It is what a mod filters keybinds on, since the engine no longer decides that for you: a key that would be a nuisance while the menus are up returns early, and a key that is about what is on screen (a screenshot) does not.

hook.Add("KeyPress", "mymod", function(key)
    if OVERLAY_OPEN then return end        -- not while the user is in the menus
    if key == "R" then reset() end
end)

-- and anywhere else, not just in a callback that was handed it:
hook.Add("Think", "mymod_idle", function()
    if not OVERLAY_OPEN then pollTheGame() end
end)

An optional file at the root of your addon (addons/<name>/mod.txt), read by the engine before any Lua runs. It exists to answer one question: when the same mod is present twice — as a folder you are editing and as a .ccmod you downloaded — which copy loads? The higher version wins, and a tie goes to the package — equal versions mean the folder has not been bumped since that release was cut, so the two are claiming to be the same thing and the published one is the copy that was actually built.

# addons/mymod/mod.txt
version = 1.2.3

Two more keys, both advisory. dependencies lists mods this one needs beside it, optionally with a minimum version; incompatible lists mods it cannot live with. Names are folder names, matched without regard to case, comma separated.

# addons/mymod/mod.txt
version      = 1.2.3
dependencies = pkmn_stats >= 0.3.0, notes
incompatible = steam_skin

Current frame-to-screen latency in milliseconds (a smoothed average) — from when the OS timestamps a received frame to when it's presented. This is the software path only; it does not include the capture card + USB latency. Handy for testing your mod's rendering cost. Takes no parameters.

Frames presented in the last second. Takes no parameters.

Milliseconds since the app started — the same clock the frame loop runs on. Use it for anything that has to fit inside a frame; os.clock measures CPU time and is too coarse. Takes no parameters.