Write a plugin
A plugin is a folder with src/main.luau in it. There is no manifest, no build step and no SDK to install.
What a plugin is
src/main.luau builds a plugin object with Plugin.new{...}, defines the hooks it wants as methods on that object, and returns it. function plugin:onGameTick(event) is called once per tick, and a hook you do not define is never called.
The game itself is a set of globals: player, scene, bank, log and the rest. Other files under src/ load with require, by their path under src/ without the .luau: require("overlays/hud") is src/overlays/hud.luau. require("src/overlays/hud") and require("overlays/hud.luau") find nothing.
There is deliberately no manifest. The entry is always src/main.luau, the id is the folder name locally and assigned by the server on the marketplace, and the name a player sees is the descriptor's name. A stray plugin.toml is rejected rather than ignored.
Plugins run inside the game client's process, alongside the built-in ones. Reads are direct, and a side panel is drawn in the sidebar docked beside the game canvas.
Set up a folder
Plugins load from ~/.bentobox/plugins. Make a folder there and put the entry file in it:
~/.bentobox/plugins/food-watch/
src/main.luau the plugin
types/author_globals.d.luau editor types (optional, recommended)
assets/icon.png side-panel icon (optional)Restart the client to pick it up. After a change, right-click the plugin in the sidebar's plugin list and choose Reload plugin.
log output goes to ~/.bentobox/logs/bento-host.log. Use log:info or log:warn while developing: the published client does not write debug or trace lines.
A file under assets/ ships only if your source names it with a literal path: Asset.text or Asset.bytes for data, and ImageUtil.loadImageResource(nil, "icon.png") for an image such as the panel icon. An upload carrying an asset that nothing names is refused.
A sound is an asset too: audioPlayer:playBytes(Asset.bytes("assets/ding.wav"), 0). The upload accepts .wav, .ogg (Vorbis), .mp3 and .flac, up to 30 seconds, 48 kHz and stereo, and ships every one as WAV. The client plays only WAV, so keep a .wav in the folder to hear it before you upload.
A complete plugin
This is src/main.luau in full: a tick hook that watches the food you carry, and a side panel that shows it.
--!strict
-- A complete Bento plugin: src/main.luau, the only file a package needs.
-- It builds the plugin object with `Plugin.new`, defines the hooks it wants
-- as methods on it, and returns it.
local plugin = Plugin.new({
-- The side panel's tab is named after this.
name = "Food Watch",
description = "Warns when food runs low.",
})
local LOW_FOOD = 3
-- Once per game tick, 600ms. Hooks that carry an event take it as their one
-- argument; the game itself is in globals such as `player` and `log`.
function plugin:onGameTick(_event: GameTick)
if not player:isLoggedIn() then
return
end
local food = player:inventory():foodAmount()
if food < LOW_FOOD then
log:info("food is low: " .. tostring(food))
end
end
-- Defining `sidePanel` is what gives the plugin a panel, drawn in the sidebar
-- docked beside the game canvas. It is immediate mode: called every frame, and
-- a button returns true on the frame it was clicked.
function plugin:sidePanel(panel: Panel)
panel:heading("Food Watch")
if not player:isLoggedIn() then
panel:label("Not logged in")
return
end
local inventory = player:inventory()
panel:label("Food: " .. tostring(inventory:foodAmount()))
panel:label("Free slots: " .. tostring(inventory:emptySlots()))
if panel:button("Eat now") then
-- A name pattern matches the whole name, ignoring case; `|` separates
-- alternatives. `true` means the click is queued, not that it landed.
inventory:interactName("Shark|Manta ray|Lobster", "Eat")
end
end
return pluginEvery call in it is on the reference: Inventory for the item reads, Panel for the side panel.
Editor types
There is nothing to require for the API, so completion and typechecking come from a declaration file instead. Point luau-lsp at the one the marketplace builder validates against:
- Download
author_globals.d.luauinto your plugin'stypes/folder. - Add
.vscode/settings.json:
{
"luau-lsp.types.definitionFiles": [
"types/author_globals.d.luau"
],
"files.associations": {
"*.luau": "luau"
}
}Start each file with --!strict. The builder typechecks uploads against the same declaration, so a clean editor is a clean upload. The CLI leaves types/ out of an upload and the builder ignores it in an archive you make yourself: it brings its own copy.
Hooks
A hook is a method on the plugin object. Hooks that carry an event take it as their one argument; the drawing hooks receive a surface that is valid only for that pass. These tables come from the same declaration as the API reference.
Lifecycle
| Hook | Argument | Description |
|---|---|---|
startUp | None | The plugin was enabled, or the client started with it enabled. No event reaches it before this returns; the object is registered on the eve… |
shutDown | None | The plugin was disabled. The object is unregistered from the event bus first, so no event reaches it after. |
resetConfiguration | None | The settings page's Reset put the plugin's config group back to its defaults. |
provideConfig | None | Return configManager:getConfig(SomeConfigGroup) to make that group the plugin's own. Called once, at load; without it the first group the… |
recommendedSettings | None | The game settings this plugin recommends values for (any row of All Settings that holds one: a toggle, a dropdown, ...), as a list of `Reco… |
Drawing
| Hook | Argument | Description |
|---|---|---|
sidePanel | Panel | Draw the plugin's side panel. Declaring this is what gives the plugin a panel at all. Immediate mode: called every frame. |
renderWindows | Window | Open and drive separate viewport windows. The window handle is valid only for this pass. |
renderOverlay | Draw, DrawLayer | Draw over the game. Called once per layer every frame, three calls in all, so a hook that ignores layer draws three times. The draw surfa… |
Events
An event hook is on and the name of its event, and receives that event. eventBus:subscribe reaches the same events.
Globals
Lowercase globals are the live game: the local player, the scene, the bank, world hopping, the Grand Exchange and logging. They are refreshed for every callback, and reading one outside a callback raises.
Capitalised globals are constants and constructors: Skill.ATTACK, VarbitID, WorldPoint, Json. They never change, so they are safe to keep in a local.