Performance

Plugins run on the game's thread, so the time your code takes is the game's time.

The one rule

Never loop over the client in Luau when a query can narrow in the client.

Every call on a handle crosses from Luau into the client and back. A loop over the client pays for that on every row, for every call in its body. A query reads once, narrows the rows in the client, and crosses at its last call.

-- Wrong: every NPC crosses into Luau, and each row calls back for more.
local best, bestDistance = nil, math.huge
for _, npc in client:getNpcs() do
    if npc:getName() == "Goblin" then
        local distance = npc:getWorldLocation():distanceTo(here)
        if distance <= 10 and distance < bestDistance then
            best, bestDistance = npc, distance
        end
    end
end

-- Right: the client narrows the scene. One NPC crosses, at the end.
local best = scene:npcs():named("Goblin"):within(10):nearest()

scene:npcs(), scene:players(), scene:objects() and scene:groundItems() all work this way. See NPCQuery for the filters. A last call such as count, nearest or collect uses the query up, and a second one raises. Start a new query instead of keeping an old one.

No filter takes a Luau function, because it would call back into your plugin once per candidate. For a test no filter covers, narrow first and go through the table collect returns.

-- Narrow as far as the query goes, then filter the table it returns.
local weak = {}
for _, npc in scene:npcs():within(8):combatLevelBelow(50):collect() do
    if isWorthFighting(npc) then
        table.insert(weak, npc)
    end
end

A getter reads the game live, so keep what you use twice in a local.

No hook budget

No hook has a time budget. The client waits for a slow hook rather than stopping it, skipping it or disabling the plugin, and the game and every other plugin wait with it. A hook that takes too long shows as a visible hitch.

To measure a hook, use utils:elapsedMs(). It counts milliseconds, with fractions, from an arbitrary start. There is no os.clock.

function plugin:onGameTick(_event: GameTick)
    local started = utils:elapsedMs()
    run()
    log:debug("tick took {} ms", utils:elapsedMs() - started)
end

Run less often

A hook's cost is its time multiplied by how often it runs. onGameTick runs every 600 ms. onClientTick runs every 20 ms while logged in. sidePanel and renderOverlay run every frame.

So do your reading on the tick, keep plain values in locals, and draw from those.

local goblins = 0

-- Read the scene once per game tick.
function plugin:onGameTick(_event: GameTick)
    goblins = scene:npcs():named("Goblin"):within(10):count()
end

-- Every UI frame: show what the tick found.
function plugin:sidePanel(panel: Panel)
    panel:label("Goblins near: " .. tostring(goblins))
end

Define only the hooks you use. A hook you do not define is never called, and a plugin with no renderOverlay is not visited for overlays at all.

Widgets

ui:widgets() is the interface registry as a query. Its filters run in the client over the rows it holds, and only the last call returns Widget handles.

-- Wrong: every widget in the registry becomes a handle, then each one calls back.
for _, widget in ui:widgets():collect() do
    if widget:getText() == "Deposit" then
        button = widget
    end
end

-- Right: the client narrows the rows it holds. One widget crosses.
local button = ui:widgets():visible():textContaining("Deposit"):first()

-- Better, when you know its id: read that one widget.
local known = client:getWidget(PACKED_ID)

It replaced an earlier form that decoded the whole registry into Luau tables: tens of thousands of rows, each with nested tables and copied strings. One plugin ran it from a tick hook and ran so long that the client of the time disabled it within seconds. Today's client would not disable it, and the game would stall instead.

ui:widgets() still reads the registry each time you call it, so run it on a tick and not on a frame.

Overlays

Draw is per frame. renderOverlay runs once per layer per frame, and there are three layers: DrawLayer.ABOVE_SCENE, DrawLayer.ABOVE_WIDGETS and DrawLayer.ALWAYS_ON_TOP. A hook that ignores layer draws everything three times.

-- Wrong: redraws every tile on every frame, and on all three layers.
function plugin:renderOverlay(draw: Draw, _layer: DrawLayer)
    for _, tile in tiles do
        draw:tilePoly(tile, EDGE, FILL)
    end
end

For tiles, use draw:record and draw:replay. Recording reads terrain heights once and bakes the draws into a buffer. Replaying copies the buffer into the frame, and what you replay still follows the camera.

local tiles: { WorldPoint } = {}
local recorded: PrimBuffer? = nil

function plugin:onGameTick(_event: GameTick)
    tiles = {}
    for _, npc in scene:npcs():named("Goblin"):within(10):collect() do
        table.insert(tiles, npc:getWorldLocation())
    end
    recorded = nil -- the tiles changed, so record again on the next frame
end

function plugin:renderOverlay(draw: Draw, layer: DrawLayer)
    if layer ~= DrawLayer.ABOVE_SCENE then
        return
    end
    local buffer = recorded or draw:record(function(d)
        d:fillTiles(tiles, EDGE, FILL)
    end)
    recorded = buffer
    draw:replay(buffer)
end
  • Record again when the tiles change, or when the scene base moves (client:getBaseX(), client:getBaseY()).
  • Keep the buffer. The draw your hook receives is valid only for that pass.
  • A recording drops text, and draw:hudBlock does nothing inside one. Draw those live, on one layer.
  • Pass many tiles to one fillTiles call. It is one crossing, however many tiles it holds.

Long lists

sidePanel runs every UI frame while the panel shows, and everything in it runs again each time. For a long list, panel:scrollRows draws only the rows in view. Your function gets the panel and the first and last visible row, counted from 1.

-- Wrong: a label for every row, on every frame, seen or not.
panel:scrollArea(function(list)
    for _, row in rows do
        list:label(row)
    end
end)

-- Right: only the rows in view. Each row must be rowHeight points tall.
panel:scrollRows(18, #rows, function(list, first, last)
    for i = first, last do
        list:label(rows[i])
    end
end)

Event filters

A hook that returns on its first line still enters Luau for every event. eventBus:subscribe takes a filter the client tests before that: { actor = "local" } for events on actors, { varbit = { ids }, varp = { ids } } for VarbitChanged, { eventName = names } for ScriptCallbackEvent, and { scriptId = ids } for ScriptPreFired and ScriptPostFired.

function plugin:startUp()
    -- Tested in the client as the event is raised. An animation on anyone else
    -- never enters your plugin.
    eventBus:subscribe(AnimationChanged, onMyAnimation, 0, { actor = "local" })
end

An on<Event> hook takes the same filters from the plugin's eventFilters table, keyed by the hook's name: plugin.eventFilters = { onScriptPostFired = { scriptId = { 750 } } }. It is read once, when the plugin loads, so set it before main.luau returns.

A ScriptPreFired or ScriptPostFired subscription with no scriptId takes every script the client runs, as { scriptId = "all" } does. Name the scripts you want when you can: your handler is then not called for any other, and while every subscriber names its scripts, a script nobody named is not raised at all. Subscribe once rather than every tick: each script subscription made, dropped or changed lets every script through to the client's check until the filter is rebuilt.