All addons run in one shared sandbox: a global you set in one addon is readable in every other addon, functions can be called across mods, and hook events fired by one mod reach listeners in another. Only two things are per-addon: data (your private storage folder) and MOD_NAME (your folder name).

-- addons/hello/lua/autorun/hello.lua
log("hello loaded as " .. MOD_NAME)

-- A free-form HUD element, always on screen (mode = "pinned")
overlay.add("hello.clock", {
    mode = "pinned",
    paint = function(d)
        d:rect(d:w() - 150, 16, 130, 34, 0, 0, 0, 150)
        d:text(d:w() - 138, 24, os.date("%H:%M:%S"), 20, 255, 255, 255)
    end,
})

-- A button in the overlay menu (Shift+Tab)
overlay.add("hello.hi", {
    mode = "menu",
    button = { label = "Say hi", onClick = function() log("hi!") end },
})

Queues a PNG capture of the current video frame (overlay UI is not included). Fulfilled at the end of the frame 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. Pass all four of x, y, w, h to capture only that pixel region instead of the whole frame.

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)

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>/).

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.

Registers fn for event under a unique name. Adding again with the same event + name replaces the previous callback.

Unregisters the callback previously added under this event + name.

Fires an event, calling every registered callback with the given arguments. The engine uses this to dispatch events, but you can also define and fire your own custom events between mods.

The incoming video changed size — a different capture mode, a different console output setting, a stream restart. Fired before the first frame of the new size reaches OnFrameReceived, so anything you measured against the old frames can be thrown out in time. Note this is about the video, not the app window: resizing the window never moves a pixel of frame space, so there is deliberately no event for it.

Fired on key-down while the overlay is closed (when it's open, keys drive the UI instead).

hook.Add("KeyPress", "screenshotter", function(key)
    if key == "P" then screenshot("screenshots/" .. os.time() .. ".png") end
end)

Fired once per element, every frame, just before it is drawn — for every element, native ones included. Mutate the passed element table to restyle, rename, hide (el.hidden = true), or re-mode anything on the overlay.

hook.Add("OverlayElement", "myskin", function(el)
    if el.id == "options" then el.button.label = "Settings" end
    if el.id == "close_overlay" then el.hidden = true end
end)

Fired for every captured video frame, before it is displayed. Mutate the frame's pixels in place (through the Frame object) to alter what's shown — no return value needed. Handlers run in turn; if one returns a non-nil value, the remaining handlers are skipped for that frame.

hook.Add("OnFrameReceived", "dim-top", function(frame)
    local pitch = frame:pitch()
    for row = 0, 40 do                 -- NV12: Y plane is the first rows
        for col = 0, frame:width() - 1 do
            frame:setByte(row * pitch + col, 16)   -- Y=16 -> black band
        end
    end
end)

Frame width in pixels. Takes no parameters.

Frame height in pixels. Takes no parameters.

Bytes per row of the first (luma) plane. Index a pixel's row with row * pitch() + col. Takes no parameters.

The pixel format name, e.g. "SDL_PIXELFORMAT_NV12". Takes no parameters.

Total pixel-buffer size in bytes — the valid range for byte indices. Takes no parameters.

Reads one byte of the pixel buffer.

Read a rectangle in one call. Returns w*h bytes, row-major — index it with string.byte. Anything outside the frame comes back as 0 rather than being refused.

-- one row of the luma plane, sampled every 6th pixel
local row = frame:region(x0, y, 600, 1)
for i = 1, 600, 6 do
    local luma = row:byte(i)
end

Writes one byte of the pixel buffer — this is how you change what's displayed.

Open a web page. Returns true if it was handed off successfully.

browser.open("https://bulbapedia.bulbagarden.net/wiki/Pikachu_(Pok%C3%A9mon)")

Register this mod against a game (or several) and get back the object you hang your callbacks and settings on. Pass a handle string, one definition table, or an array of them — an array means the same mod serves several games (e.g. FireRed and LeafGreen).

local g = game.register({
    { handle="pkmn_firered",   name="Pokemon FireRed",   image="addons/"..MOD_NAME.."/fr.png" },
    { handle="pkmn_leafgreen", name="Pokemon LeafGreen", image="addons/"..MOD_NAME.."/lg.png" },
})

Overridable: called once per frame, but only while one of your games is selected. Dormant mods cost nothing.

Overridable: called with each captured Frame while your game is selected — the gated version of OnFrameReceived. Use it to read or alter pixels only when your game is actually on.

Overridable: your game was just selected / deselected. Switching between two games that both belong to your mod does not fire these — you stay active.

Overridable: for work too heavy to finish inside one frame. Offered every frame, but a call that hasn't returned yet keeps running instead of a new one starting — see Threading for what that costs you and how to yield.

Declare a setting. You only say what it's called, how it should be shown, and what kind of input it is — the engine owns everything else: it stores the value, remembers it between runs, validates it, and builds the settings menu. There is nothing to draw and nothing to save.

g:addSetting("show_stats", "Show Pokemon stats", "bool", nil, true)
g:addSetting("route_info", "Show route information", "choice",
             { "on", "off", "overlay only" }, "on")

if g:get("show_stats") then ... end

Current value of one of your settings — a boolean for "bool", otherwise a string. nil if you never declared that key.

Change a setting yourself. Saved immediately; invalid values for a choice are ignored.

Handle of the selected game, or nil if none is. Takes no parameters.

Whether that particular game is the selected one — handy when your mod serves several and needs to tell them apart.

Select a game as if its cartridge had been clicked. Fires the relevant OnDeactivate/OnActivate. The choice is remembered and restored next launch.

Every registered game in registration order, as { handle, name, image }. Takes no parameters.

The handles of the games a given mod registered, e.g. game.gamesOfMod("pkmn_stats") → {"pkmn_firered", "pkmn_leafgreen"}. Used by the engine's upload form to fill itself in from the mod rather than asking you to retype what the mod already declared — handles rather than display names, because the site matches on internal names that look like handles.

Whether a capture device is currently open and streaming. Takes no parameters.

The device's name, e.g. "UGREEN-25854" — the card's USB name, not the console or game. nil if no device is open. Takes no parameters.

The user-declared label for whatever HDMI device is plugged into this card, e.g. "Nintendo Switch". The card cannot detect this — the user types it in Options → Connected device, and it's remembered per card name. nil until they set it. Useful for source-specific mods: if camera.source() == "Nintendo Switch" then …. Takes no parameters.

Width in pixels of the live frame format (0 if none). Takes no parameters.

Height in pixels of the live frame format (0 if none). Takes no parameters.

Pixel format name of the live frame, e.g. "SDL_PIXELFORMAT_NV12". Matches frame:format(). nil if none. Takes no parameters.

Frame rate of the live format in frames per second (0 if unknown). Takes no parameters.

The frame colorspace as SDL's numeric SDL_Colorspace enum value (0 if none). Niche — most mods won't need it. Takes no parameters.

Every format/resolution/framerate the device advertises, as an array of tables. A fresh copy each call — safe to modify. Takes no parameters.

if camera.isOpen() then
    log(camera.name() .. ": " .. camera.width() .. "x" .. camera.height()
        .. " " .. camera.format() .. " @ " .. camera.fps() .. " fps")
    log("advertises " .. #camera.formats() .. " formats")
end

Whether somebody is signed in right now. Everything else here is nil when this is false. Takes no parameters.

Their display name, for showing — e.g. greeting them in a HUD. Not an identity: it is user-chosen, changeable, and not unique. nil when signed out or unset. Takes no parameters.

The account id, and the only identity there is — not the email address, since one account can have several logins and the address is merely one of them. Key any per-user state a mod stores on this. nil when signed out. Takes no parameters.

-- remember something per signed-in user
local id = account.id()
if id then data.write("prefs_" .. id .. ".txt", "...") end

Registers an element under a unique string id and returns the element table (the same spec, now with .id set). Adding with an existing id replaces it.

Removes the element registered under id. Does nothing if no such element exists.

Returns the registered element table for id. Mutating the returned table changes the element live.

Toggles the overlay open/closed (same as Shift+Tab). Takes no parameters.

Opens the overlay. Takes no parameters.

Closes the overlay (and clears any text-field focus). Takes no parameters.

Whether the overlay is currently open. Takes no parameters. Returns a boolean.

Sets a user override for an element's visibility mode. Ignored for elements whose lockMode is true.

Returns the user override mode for an element.

Gives keyboard focus to a textbox widget. Useful right after creating an element so the user can type immediately.

Width of the window in pixels — use it to centre or right-align things. Takes no parameters.

Height of the window in pixels. Takes no parameters.

Pointer X in screen pixels, or -1 until the mouse has moved once. Lets an element work out where inside itself the cursor is — which row of a list it is over, say — rather than only that it is somewhere inside. Still reported while the pointer is auto-hidden. Takes no parameters.

Pointer Y in screen pixels, or -1 until the mouse has moved once. Takes no parameters.

Controls when the element is visible:

When true, the element's mode is forced and overlay.setUserMode is ignored for it. When false, the user may override the mode.

Reset to false each frame, then read after the OverlayElement hook — set it there to hide the element for that frame.

Mouse behaviour of the element's rectangle. false (default): the element consumes mouse events over its bounds — it receives the callbacks below, and elements beneath it get nothing. true: the element (including its widgets) ignores the mouse entirely and events fall through to the next element under the cursor. Elements are tested topmost-first (last drawn = on top), so the highest non-passThrough element under the cursor is always the one that receives events.

Maintained by the engine: true while this element is the current mouse-hover target, false otherwise. Read-only in spirit — useful inside paint to restyle on hover without writing callbacks.

Overridable callback (GMod-panel style; nil = no-op): called once when the mouse moves onto this element.

Overridable callback: called once when the mouse leaves this element (or another element takes the hover).

Overridable callback: a mouse button was pressed on this element (and no child widget took the click — widgets inside a panel get first crack, left button only).

Overridable callback: the button was released. Sent to the element that received the OnMouseDown (capture semantics — a drag that ends outside the element still notifies it).

local pnl = overlay.add("mymod.box", {
    mode = "pinned", x = 40, y = 40, w = 180, h = 90,
    children = { { type = "label", x = 10, y = 10, text = "drag me" } },
})
function pnl.OnMouseDown(self, x, y, button) log("down at " .. x .. "," .. y) end
function pnl.OnMouseUp(self, x, y, button)   log("released")                  end
function pnl.OnHoverEnter(self) self.style.border = {120,200,255,255} end
function pnl.OnHoverExit(self)  self.style.border = {200,200,215,255} end

Makes the element an auto-laid-out button in the centered overlay menu column. Button elements are ordinary elements underneath: they inherit passThrough, hovered, and the OnHoverEnter / OnHoverExit / OnMouseDown / OnMouseUp callbacks, and the engine writes the computed x, y, w, h back onto the element each frame so you can read where the button ended up.

Makes the element a free-form drawing. Called every frame it's visible with a DrawContext d. Paint elements have no built-in input handling.

Makes the element a panel: a styled box at x, y, w, h containing native Widgets (positioned relative to the panel). Requires x, y, w, h; accepts a style.

Static text. One line at a point by default; give it w and h and it wraps at word boundaries inside that box instead, clipping when it runs out of height. Size h for the longest text the label can be given — at font f each line costs f + 3, and the last one fits while it starts at or before h - f. Undersize it and the tail vanishes with nothing to show for it; the engine logs label doesn't fit its w/h to the developer console when that happens.

A clickable button with a hover highlight.

An editable text field. Click it (or call overlay.focus) to focus; the engine handles typing, the blinking caret, and editing keys natively. Read/write its current contents via the text field.

A dropdown. Shows the selected option; clicking opens a list of options (drawn on top of everything), and picking one collapses it.

A draggable value bar. Click or drag the track to set the value.

Current screen width in pixels.

Current screen height in pixels.

Fills a rectangle.

Draws a 1px rectangle outline.

Draws a line between two points.

Draws text with the built-in font.

Draw a PNG or JPEG, scaled into that rectangle. Returns false if it can't be loaded, so you can fall back to drawing a label. Images are cached after the first draw, and a failed path is remembered too rather than retried every frame.

Draws a PNG or JPEG scaled into the given rectangle. Returns true if it drew, false if the image couldn't be loaded — check the result and fall back to text rather than assuming it worked. Images are loaded once and cached, so calling this every frame is cheap (the first call does the disk read).

if not d:image("addons/" .. MOD_NAME .. "/logo.png", 20, 20, 64, 64) then
    d:text(20, 20, "MyMod", 16, 230, 230, 240)   -- fallback
end

Writes contents to name (overwriting), creating sub-folders as needed.

Reads a file back.

Appends contents to the end of name (creating it if needed).

Whether a file exists in your data folder.

Deletes a file.

Lists your saved files. Takes no parameters. Returns a Lua array (table) of string relative paths of all files in your data folder, recursively.

The absolute path of your data folder (informational). Takes no parameters. Returns a string.

Start a background thread running a script from your own addon folder. Only while your mod is loading — a worker is long-lived, and load time is when the engine still knows whose folder to read from. Returns nil (and logs) if the file isn't there.

local w = worker.spawn("workers/reader.lua")

Hand over one job. False means it is still busy — and that is the whole scheduling model: ask every frame, and a frame where the answer is no is a frame you simply skip. Nothing queues, so a slow pass can never build a backlog of work about frames that have already gone.

Everything the worker has finished since you last asked, as an array. Never blocks and returns an empty table when there is nothing — call it every frame. Each entry is whatever that job's onJob returned.

Give the worker a value once, as a global on its side. For the things that never change and are too big to send every frame — a font atlas, a lookup table. It is a snapshot: changing your copy afterwards changes nothing over there until you share it again.

w:share("FONT", PKMN.font)      -- a few hundred KB, sent once
w:post({ rows = sampled })      -- a few KB, sent every frame

Whether a pass is running. You rarely need it — post already answers the same question by refusing.

False if the script failed to load or defines no onJob. A worker that throws inside a job stays alive: one bad frame shouldn't stop the mod being processed for the rest of the session.

In the worker script, not in your mod: the one function the engine calls, once per posted job. What you return comes back through collect. A worker script that doesn't define it is refused at spawn.

The worker gets a smaller sandbox than a mod: string, table, math, utf8 and the base library, plus log(msg) and now() (milliseconds, for timing a pass). No os, no data, and none of the engine APIs — no overlay, no hook, no game. They all reach shared state, and reaching is the thing this design exists to avoid.

-- workers/reader.lua
function onJob(job)
    local out = {}
    for _, w in ipairs(job.windows) do out[#out+1] = classify(w, FONT) end
    return { seq = job.seq, windows = out }
end

nil, booleans, numbers, strings and tables of those, nested. Everything else — functions, userdata, metatables, a Frame — is dropped, and the engine logs how many values it left behind rather than failing quietly. Cycles are not followed.

This is a copy, in both directions. The two Lua states share no memory at all, which is what makes it safe to run one while the other is drawing; it is also why there are no globals to reach for over there. Package what the worker needs into the job, and expect the answer back the same way.

Inside LateUnreliableThink: yields if this frame's share of time is spent, and resumes here on the next one. Call it wherever stopping is safe. Without a slice call the pass runs to completion in one frame and you have gained nothing.

Why a coroutine rather than a thread: there is one Lua state shared by every mod (that is what makes cross-mod globals work), and a second OS thread touching it would corrupt it. So the slicing is cooperative, and the budget is 2 ms of a ~16 ms frame. "Unreliable" is the promise: passes never overlap and never queue, but nothing says how often one runs or how long it takes.

function g:LateUnreliableThink()
    for i = 1, 100000 do
        crunch(i)
        if i % 500 == 0 then game.slice() end
    end
end

print, pairs, ipairs, next, type, tostring, tonumber, select, error, assert, pcall, xpcall, setmetatable, getmetatable, rawget, rawset, rawequal, rawlen, and the string, table, math, coroutine, utf8 libraries.

A time-only subset: os.time, os.date, os.clock, os.difftime. (No execute, remove, rename, getenv, exit.)

Removed entirely. These are the usual ways to escape a sandbox — file I/O goes through data, and there is no runtime code loading.

These exist, but not for mods. They change the user's device, window, volume or sign-in state, and auth additionally holds the session tokens — in a sandbox shared by every mod, one of these reachable would be all of them reachable. The read-only slices mods do get are camera (what the card reports) and account (who is signed in).