Skip to content

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.

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.

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.

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)
end
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.

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.

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.
  • Server plugins are trusted. A plugin in Resources/Server runs 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, and from is 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.
  • secret config options never reach a game, and are stored in plain text in BeamJoyData/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 use https://.
  • Resources/Server/BeamJoyServer/api/README.md in 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.