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 plugin

Every 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:

  1. Download author_globals.d.luau into your plugin's types/ folder.
  2. 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

HookArgumentDescription
startUpNoneThe plugin was enabled, or the client started with it enabled. No event reaches it before this returns; the object is registered on the eve…
shutDownNoneThe plugin was disabled. The object is unregistered from the event bus first, so no event reaches it after.
resetConfigurationNoneThe settings page's Reset put the plugin's config group back to its defaults.
provideConfigNoneReturn configManager:getConfig(SomeConfigGroup) to make that group the plugin's own. Called once, at load; without it the first group the…
recommendedSettingsNoneThe 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

HookArgumentDescription
sidePanelPanelDraw the plugin's side panel. Declaring this is what gives the plugin a panel at all. Immediate mode: called every frame.
renderWindowsWindowOpen and drive separate viewport windows. The window handle is valid only for this pass.
renderOverlayDraw, DrawLayerDraw 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.

HookEventDescription
onActorDeathActorDeath
onAmbientSoundEffectCreatedAmbientSoundEffectCreated
onAnimationChangedAnimationChanged
onAreaSoundEffectPlayedAreaSoundEffectPlayed
onBeforeMenuRenderBeforeMenuRender
onBeforeRenderBeforeRender
onChatMessageChatMessage
onClanChannelChangedClanChannelChanged
onClanMemberJoinedClanMemberJoined
onClanMemberLeftClanMemberLeft
onClientTickClientTickOnce per client cycle while logged in. It does not run on the login screen; onPostClientTick does.
onCommandExecutedCommandExecuted
onDecorativeObjectDespawnedDecorativeObjectDespawned
onDecorativeObjectSpawnedDecorativeObjectSpawned
onFakeXpDropFakeXpDrop
onFocusChangedFocusChanged
onFriendsChatChangedFriendsChatChanged
onFriendsChatMemberJoinedFriendsChatMemberJoined
onFriendsChatMemberLeftFriendsChatMemberLeft
onFriendsChatSyncFriendsChatSync
onGameObjectDespawnedGameObjectDespawned
onGameObjectSpawnedGameObjectSpawned
onGameStateChangedGameStateChanged
onGameTickGameTick
onGrandExchangeOfferChangedGrandExchangeOfferChanged
onGrandExchangeSearchedGrandExchangeSearched
onGraphicChangedGraphicChanged
onGraphicsObjectCreatedGraphicsObjectCreated
onGroundObjectDespawnedGroundObjectDespawned
onGroundObjectSpawnedGroundObjectSpawned
onHitsplatAppliedHitsplatApplied
onInteractingChangedInteractingChanged
onItemContainerChangedItemContainerChanged
onItemDespawnedItemDespawned
onItemQuantityChangedItemQuantityChanged
onItemSpawnedItemSpawned
onMenuEntryAddedMenuEntryAdded
onMenuOpenedMenuOpened
onMenuOptionClickedMenuOptionClicked
onMenuShouldLeftClickMenuShouldLeftClick
onNameableNameChangedNameableNameChanged
onNpcChangedNpcChanged
onNpcDespawnedNpcDespawned
onNpcSpawnedNpcSpawned
onOverheadTextChangedOverheadTextChanged
onPlayerChangedPlayerChanged
onPlayerDespawnedPlayerDespawned
onPlayerSpawnedPlayerSpawned
onPostClientTickPostClientTickOnce per client cycle in every game state, the login screen included.
onPostHealthBarConfigPostHealthBarConfig
onPostMenuSortPostMenuSort
onPreMapLoadPreMapLoad
onProjectileMovedProjectileMoved
onRemovedFriendRemovedFriend
onResizeableChangedResizeableChanged
onScriptCallbackEventScriptCallbackEvent
onScriptPostFiredScriptPostFiredThe ScriptPostFired event. A subscription takes every script the client runs, thousands a second. To hear only some, name them: `eventFil…
onScriptPreFiredScriptPreFiredThe ScriptPreFired event. A subscription takes every script the client runs, thousands a second. To hear only some, name them: `eventFilt…
onSoundEffectPlayedSoundEffectPlayed
onStatChangedStatChanged
onVarClientIntChangedVarClientIntChanged
onVarClientStrChangedVarClientStrChanged
onVarbitChangedVarbitChanged
onWallObjectDespawnedWallObjectDespawned
onWallObjectSpawnedWallObjectSpawned
onWidgetClosedWidgetClosed
onWidgetDragWidgetDrag
onWidgetLoadedWidgetLoaded
onWorldChangedWorldChanged
onWorldListLoadWorldListLoad
onWorldViewLoadedWorldViewLoaded
onWorldViewUnloadedWorldViewUnloaded
onAccountHashChangedAccountHashChanged
onCanvasSizeChangedCanvasSizeChanged
onUsernameChangedUsernameChanged
onWorldEntityDespawnedWorldEntityDespawned
onWorldEntitySpawnedWorldEntitySpawned
onConfigChangedConfigChanged
onExternalPluginsChangedExternalPluginsChanged
onOverlayMenuClickedOverlayMenuClicked
onPlayerLootReceivedPlayerLootReceived
onPluginChangedPluginChanged
onProfileChangedProfileChanged
onRuneScapeProfileChangedRuneScapeProfileChanged
onServerNpcLootServerNpcLoot
onWorldsFetchWorldsFetch

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.