Limits and permissions
What the sandbox leaves out, what a plugin can reach, and what happens when one fails.
The sandbox
A plugin is Luau with the game's API added. Luau's own libraries are there: string, table, math, coroutine, utf8, bit32, buffer and vector. These globals are not:
| Not there | Instead |
|---|---|
os | utils:elapsedMs() to measure a duration. Instant.now():toEpochMilli() for the time now in Unix milliseconds, to compare with a field ending in At. |
io, dofile, loadfile | The routes under Files, below. |
package | require, which loads other files under your package's src/ and nothing else. |
load, loadstring | Nothing. No code compiles at run time. |
debug | log. An uncaught error logs its traceback. |
getfenv, setfenv, newproxy | Nothing. |
collectgarbage | Nothing. The client runs the collector. |
_G is read-only: _G.x = 1 raises. Keep your state in locals. Assigning to a bare global, such as player = 1, leaves the client's value alone but hides it from your own code.
Time
There is no time limit and no instruction limit. No callback, task step or startUp runs on a budget, and the client never cuts one off.
All of a client's plugins run on the game's thread, so while your code runs, the game and every other plugin wait. A callback that never returns freezes the game, and nothing stops it. Performance covers how to stay out of the way.
Memory
All of a client's plugins share one Luau state and one memory limit. The default is 512 MB. The player sets it under Settings, Advanced, Plugin memory: 128 MB, 256 MB, 512 MB, 1 GB, 2 GB or 4 GB, for the clients they launch after the change.
An allocation past the limit raises not enough memory in whichever plugin made it, which may not be the one holding the memory. So the client also looks at 95% of the limit. It runs a full collection, and if the state is still that full, it unloads the plugin holding the most until the client restarts.
Network
A published plugin can reach one place: the OSRS Wiki's API. That is https://oldschool.runescape.wiki/api.php and https://prices.runescape.wiki/api/v1/osrs/..., by GET with no body and no header but User-Agent and Accept. A redirect is followed only while it stays there. http and okHttpClient refuse every other request for it before anything is sent, and LineSocket refuses every host. A refused http:get does not raise: your callback gets nil and the message. The client's own services, such as hiscoreClient, still work for it. How your code is protected says what follows for secrets.
A request to the wiki carries your User-Agent. Any plugin's request to the wiki, published or local, must set one: printable ASCII, at most 256 characters, sent exactly as you wrote it. The client adds nothing to it and never fills one in. The wiki asks for one that says what the requests are for, with a way to reach you if you like. Without one, enqueue raises. http:get and http:post cannot set one, so use RequestBuilder.new():url(url):header("User-Agent", ...):build() with okHttpClient.
The client keeps to the wiki's API etiquette for every plugin. It sends one wiki request at a time across all of them, and adds maxlag=5 to an api.php request without one. When the wiki asks for a pause (a 429, or its servers lagging), every wiki request fails at once until the pause ends. Nothing is retried or cached for you: keep what you fetch, and use the prices API's bulk endpoints, such as /latest and /mapping, rather than one request per item.
The DPS calculator's link is not the wiki's API, so a published plugin cannot post its shortlink. Any plugin gets the link with wiki:dpsCalculatorLink(userAgent, function(link, why) ... end) instead. The client builds the request's body from the logged-in player's loadout and sends it under the userAgent you pass, with the same rules and turn-taking as any wiki request. Open the link with ui:openUrl.
A local package, one in your plugins folder, can reach any host. So a feature that works locally may not work once published. Its limits are 64 MiB for a response, 16 MiB for a request body, 32 requests in flight, 4 running at once and 5 minutes for a call.
A published plugin can still send the player to the wiki or the game's site. ui:openUrl(url), LinkBrowser.browse(url) and panel:hyperlink open an https link to oldschool.runescape.wiki, runescape.wiki or runescape.com, or a subdomain of one such as prices.runescape.wiki, at once and with no confirmation. Any other link raises, and so does LinkBrowser.open. A local package opens any http or https link.
Files
There is no io. A plugin reaches files three ways.
Your package's assets
Asset.text and Asset.bytes read a file under assets/ that your source names. Another plugin's assets are not found.
Your own data directory
Each plugin has a directory of its own. ClientPaths.CLIENT_DIR names it, and a File reads and writes whole files at once. Writes are atomic.
local file = File.new(ClientPaths.CLIENT_DIR, "routes/home.json")
file:writeText(Json.encode(route))
local saved = Json.parse(file:readText())A plugin cannot name a file outside it. An absolute path, a drive, .. or a link is refused at the first read or write. A path holds at most 8 parts of 128 characters each.
| Limit | Local package | Published plugin |
|---|---|---|
| The whole directory | 1 GiB | 64 MiB |
| One file | 256 MiB | 16 MiB |
| Files | 100,000 | 4,096 |
A file the player chooses
File dialogs are the safe route to any other file. The player chooses it, and your plugin never sees a path.
-- The player picks the file. You get its bytes and its name, never its path.
ui:fileOpen({ title = "Import routes", extensions = { "json" } }, function(bytes, name)
if bytes == nil then
return -- the player cancelled
end
routes = Json.parse(bytes)
log:info("imported {}", name)
end)
-- The player picks where it goes. An existing file is replaced only if they say so.
-- A local package only: a published plugin's ui:fileSave raises.
ui:fileSave({
title = "Export routes",
name = "routes.json",
extensions = { "json" },
bytes = Json.encode(routes),
}, function(written, why)
if not written and why then
log:warn("not saved: {}", why)
end
end)- Both are drawn over the game and neither blocks. Your callback runs on one of your plugin's ticks after the player answers.
fileOpenreturns at most 64 MiB, whatevermaxBytesasks for.- A published plugin cannot save files: its
ui:fileSaveraises.ui:fileOpenworks for every plugin. - One plugin can have eight dialogs open. The ninth raises.
Other limits
- Nesting. Panel and overlay scopes nest at most 32 levels. Past that, the call raises. A hook the client would fire that deep is skipped and logged.
- Other plugins.
pluginManager:getPlugins()lists every plugin, and any plugin can start, stop, enable or disable any other. A plugin reads and writes another's config, throughconfigManageror the proxypluginManager:getPluginConfigProxyreturns, and gets another plugin's own object fromgetPlugins(). A config item markedsecretis read only by its own plugin. - A local package, held by a published plugin. A published plugin gets a local package's object as a read-only view. Its fields, its methods,
#,pairs,ipairsandfor k, v in viewwork as they do on the object, and every table or function read through it is a view too. Assigning a field on it, or on any table reached through it, raises. While the published plugin's call into the package runs, the package is held to the published plugin's limits above: it reaches no host but the wiki's API, opens only those links and saves no file. So is everything that call leaves behind, whenever it runs later: timers, jobs, tasks and event subscriptions; overlays and infoboxes; key, mouse and Swing listeners; sidebar buttons, chatbox inputs and NPC highlighters; and a runnable that waits on a dialog and goes on after the player answers. A function the published plugin passes in runs as the published plugin, wherever the package calls it.next,rawgetand thetablelibrary see a view as empty, and a call through a view cannot yield. The published plugin reads the package's config but never writes it: the package reads its config later under its own limits, so a write would outlive the call. - If you write a local package. A published plugin can call any function on your plugin's object. Whatever that function registers while it runs (a timer, an overlay, a listener) is held to the published plugin's limits. What it stores is not. A value your function keeps and sends later, from a timer, listener or overlay you set up yourself, goes out with your package's access to the network: once your code has stored a value, Bento cannot tell that it came from the caller. Check what you send, and where, as you would for any caller.
- The clipboard. Any plugin can write to it. A published plugin can read it only while a click from the player is running in that plugin.
- Game settings. A plugin can recommend a setting. Only the player can change it.
- Package size. Package and publish has the upload limits.
Uncaught errors
An uncaught error is confined to the callback that raised it. The plugin carries on, and the next callback runs as normal. The two exceptions come at the very start of a plugin's life.
| Where it raised | What happens |
|---|---|
| The main chunk | The plugin does not load. |
startUp | The plugin is disabled, and the player sees why. |
An on<Event> hook | Logged. The event's other subscribers still run. |
renderOverlay | Logged. The frame goes on. |
| A task | That task stops, and getError() returns the error. Your other tasks go on. |
shutDown | Logged. The stop completes. |
| Any other callback | Logged. |
Each error is logged with its traceback. The same error from the same hook and traceback logs once, then again on every 1000th repeat, after a line that says so. The log remembers eight distinct errors per plugin.
So a bug in onGameTick can raise on every tick and show once in the log, while your plugin looks as if it is running. If a bot stops making progress, read the log first.
Stopping a plugin
- The player switches it off in the plugin list. Its events stop,
shutDownruns, and its tasks are cancelled. - The plugin itself, or another plugin, calls
pluginManager:stopPlugin(plugin). As with an action,truemeans queued: the stop happens at the next safe point, never inside the plugin's own callback, task or render. The plugin stays enabled, and stopped.pluginManager:setPluginEnabled(plugin, false)saves the choice and stops nothing. - A failed start. If
startUpraises, the client disables the plugin. - Memory. The plugin holding the most is unloaded when plugins reach their limit, as above.
- The marketplace. A published plugin that leaves the player's library, or whose paid time ends, is shut down and unloaded.
Nothing stops a callback that is already running. A stop takes effect when it returns, so a callback that never returns cannot be stopped at all.