The plugin API
BeamJoy has an API for other BeamMP server plugins. It is for people writing Lua, not for server admins — nothing on this page is needed to run a server.
The complete reference ships with the mod, at
Resources/Server/BeamJoyServer/api/README.md, and is around 1,000 lines of method and event
signatures. This page is the orientation: what it can do, how it is shaped, and where to start.
What a plugin can do
Section titled “What a plugin can do”| Read | Races, leaderboards, maps, online players, running sessions, time and weather. |
| Hear | Events as they happen: a new best time, a lobby opening, the countdown and the green light with server times, every gate and lap, overtakes, resets, racers finishing or retiring, a finished race with every lap and sector, map changes, environment changes. |
| Take part | Refuse a join or a ready-up with a reason the player sees, set the grid order, take a racer back to not ready. |
| Run | Open lobbies of its own — scheduled events, league nights, an entry list — start or close them, and steward them: time penalties, disqualifications, reinstatements. |
| Build a discipline | Add race formats of its own to the start menu, choose who races each phase and in what order, start racers itself, rank by its own scores, judge a phase’s result, end, extend or skip a phase. |
| Draw | An activity overlay where the race HUD goes, in BeamJoy’s own look or laid out its way, and a line of text across the HUD. |
| Set | Time and weather, and a player’s GPS. |
| Add to the windows | Option sections in the race start menu and the race editor, labels on results, leaderboard entries and the race HUD, a tab in the config window, and pages of its own in the main window with buttons and fields. |
It is API version 1. A plugin can label, penalise and disqualify — but it can never change a lap time.
How it is shaped
Section titled “How it is shaped”Every folder in Resources/Server is a separate plugin with its own Lua state. Plugins cannot see
each other’s variables or call each other’s functions; they can only exchange events. BeamJoy’s
API is a set of those events carrying JSON:
| Direction | Event |
|---|---|
| your plugin → BeamJoy | BJAPI_Request |
| BeamJoy → every plugin | BJAPI_Response |
| BeamJoy → every plugin | BJAPI_<Event> |
| BeamJoy → every plugin | BJAPI_Hook — a question your plugin may answer |
You do not have to deal with any of that. BeamJoyAPI.lua is a helper that matches answers to
calls, waits for BeamJoy if your plugin starts first, and times out calls that get no answer.
Loading the helper
Section titled “Loading the helper”Load it from BeamJoy’s folder rather than copying it, so it always matches the installed BeamJoy version through updates. Each plugin that loads it gets its own copy in memory.
local here = debug.getinfo(1).source:gsub("^@", ""):gsub("\\", "/")local BJ = dofile(here:match("^(.*)/[^/]+/[^/]+$") .. "/BeamJoyServer/api/BeamJoyAPI.lua")
function onInit() BJ.init("MyPlugin")
BJ.onReady(function(info) print("BeamJoy " .. info.beamjoy.version .. " on " .. info.map.name) end)
BJ.on("LeaderboardChanged", function(data) print(data.change.name .. " set a time on " .. data.raceName) end)endThe helper’s surface
Section titled “The helper’s surface”| Call | What it does |
|---|---|
BJ.call(method, params, cb) |
cb(true, result) or cb(false, error). Calls made before BeamJoy is up wait for it; one with no answer fails with {code = "timeout"} after BJ.timeout seconds, 10 by default. |
BJ.on(event, fn) |
Every event of that name. |
BJ.onReady(fn) |
Once BeamJoy is up. Do your full sync here. |
BJ.hook(name, fn, opts) |
Answer one of BeamJoy’s questions. |
BJ.raceOptions(sections) |
Your options in the start menu and race editor. |
BJ.tyreOptions(list) |
The tyre sets racers can pick at a pit stop. |
BJ.configTab(tab, onChange) |
Your tab in the config window. |
BJ.page(page) |
A page in the main window, with updatePage and removePage. |
Everything that registers something re-registers itself whenever BeamJoy restarts, so a server restart does not leave your plugin’s UI missing.
A hook is a question BeamJoy asks before it goes on. It waits for every registered plugin to answer, up to a timeout — 2 seconds by default, 10 at most. A plugin that misses three in a row is dropped until it registers again, so a broken plugin cannot hold races up.
| Hook | Asked when | What an answer can do |
|---|---|---|
raceJoin |
A player joins a lobby, or an event already under way | Refuse, with a reason they see. An entry list, a licence, a class, a league ban. |
raceReady |
A racer readies up | Refuse, with a reason. The racer sees Checking… while plugins are asked. |
gridOrder |
A phase’s grid is about to be placed | Set the order, or take — only these racers run this phase. |
phaseResult |
A phase is over, before its result is final | Adjust times, disqualify, or place named racers first in your own order. |
Where several plugins answer, adjustments add up, every disqualification counts, and the first order given wins.
Events
Section titled “Events”The ones most plugins start from:
| Event | When |
|---|---|
Ready |
BeamJoy has loaded. |
LeaderboardChanged |
A time was set. |
RaceGridOpened, RaceCountdown, RaceGreenLight |
A session’s life, with server times. |
RacerGate, RacerLap |
Every gate and lap, with sectors, deltas and position. |
RacerFinished, RacerOut, RacerReset, RacerJumpStart |
What happens to a racer. |
RacePhaseFinished, RaceFinished |
Results, with every lap and sector. |
MapChanged, EnvironmentChanged, PlayerJoined, PlayerLeft, WhitelistChanged |
The server around it. |
Events sent while your plugin was not running are lost, which is why a full sync in onReady
is the pattern.
The shipped examples
Section titled “The shipped examples”Seven complete plugins ship in api/example/. Copy a folder into Resources/Server, next to
BeamJoyServer, and restart.
| Example | What it demonstrates |
|---|---|
| BJLeaderboardExport | Writes every map’s leaderboards to JSON and rewrites them when a time changes. The simplest one. |
| BJRaceControl | Hooks, race events and overlays: guests without a nickname cannot ready up, the fastest time starts in front, live timing that becomes the results. |
| BJClasses | Race classes end to end: a class in the editor and start menu, cars per class in a config tab, cars outside the class refused, class and points on results, and a League page with the standings. |
| BJHudLabels | Labels beside racers’ names on the HUD, plus a config tab choosing between BeamJoy’s HUD and the plugin’s own. |
| BJRallycross | A discipline built on phases: two heats, the second on a reversed grid, a final for the top six on points — and a joker lap enforced through phaseResult. |
| BJShootout | The plugin runs a phase itself: one lap each alone on track, the 107% rule, then the race on that grid. |
| BJRaceDirector | Races of its own: a lobby every half hour, a penalty per reset past the free ones, and the new leader told on their own HUD. |
Security, in short
Section titled “Security, in short”- Server plugins are trusted. A plugin in
Resources/Serverruns with the server’s full rights whether or not it uses this API — it can read every file, BeamJoy’s database included. Only install plugins you have read. The API does not sandbox anything, andfromis a name a plugin gives, not a checked one. - Nothing a plugin shows reaches a player’s game as code. Messages, overlays, options, labels, tabs and pages are plain text drawn by BeamJoy — HTML shows as typed and scripts never run.
- Players cannot use the API. A player’s game can fire the event, but BeamMP passes their ID where a plugin passes a JSON string; BeamJoy ignores those and logs who tried. Without the helper, check your handlers receive a string.
- What players send is validated. Option values are checked against your definitions; config
tabs need
EditPluginConfig; a page click only counts for a button on the page that player can see, and clicks faster than a person could make them are dropped. secretconfig options never reach a game, and are stored in plain text inBeamJoyData/db/pluginConfig.json— protect the server’s files.- Plugins see names, in-game IDs, groups and identity (
beammp,nickname,guest) and never IP addresses. A plugin that sends data to a website or Discord should say so, and usehttps://.
Resources/Server/BeamJoyServer/api/README.mdin your own install — the full reference.- Every feature, one row — what the API is exposing.
- Racing — the phase model a discipline plugin builds on.
- Groups and permissions —
EditPluginConfig, which gates a plugin’s tab.