The race editor
The race editor is where a route becomes a race. It runs inside the game, on the map you are standing on: you drive to a corner, click Add gate at my position, and that is a checkpoint. Nothing is edited on disk and nothing is uploaded — the server saves the race when you press save.
Where it lives. The Races tab of the Configuration window. The quickest way in is the main window’s Activities → Races list, where the Edit button opens it for you.
Who may use it. Anyone with the EditRaces permission, which belongs to mod and above by default. A server can narrow that further — see who may edit what at the end of this page.
A race is five things
Section titled “A race is five things”Everything below is one of these. If you only ever learn the first two you can still build a working race.
Gates the checkpoints, in order at least 2 requiredStart positions the grid slots, in order at least 1 requiredPits an optional pit lane and boxes circuits onlyProps optional barriers, cones, paint up to 1000Race defaults the rules the race starts with all have defaultsThe shortest possible race is two gates and one start position. That saves, runs, and records times. Everything else is refinement.
The flow
Section titled “The flow”Races tab → New race → Waypoints: drive, Add, repeat ↓ Start Positions: park on the grid, Add ↓ Race Info: name it, circuit or point to point ↓ (optional) Pits · Props · Race Defaults ↓ SaveThe race list
Section titled “The race list”The Races tab opens on the races this map already has, one row each, showing the mode, the gate count, the distance, the prop count if it has any, and by whoever built it. Clicking a row opens it. The delete button on a row only appears on races you are allowed to manage.
Two buttons sit above the list:
| Button | What it does |
|---|---|
| New race | Opens an empty editor. Nothing exists until you save. |
| Import map races | Reads the races the map itself ships with — its time trials and quick races — and offers them for import. See importing a map’s own races. |
If the list is empty it says so: “No races on this map yet.” Races belong to the map they were built on, so a different map means a different list.
The six sections
Section titled “The six sections”Across the top of the editor are six sections. They are not a wizard — you can work in any order — but the order they are in is the order that works.
| Section | What you do in it |
|---|---|
| Race Info | Name it, and set the things that change what a route is: circuit or point to point, one-way gates, branching, sectors. |
| Waypoints | Place, size, order and reverse the gates. The count is shown in the tab. |
| Start Positions | Place and order the grid slots. The count is shown in the tab, and it is the lobby’s maximum size. |
| Pits | Lay out a pit lane and a box per grid slot. Only appears once the race is Loopable. |
| Props | Barriers, cones, curbs, walls and painted lines. The count is shown in the tab. |
| Race Defaults | Every rule the race carries when someone starts it. |
The tools every section shares
Section titled “The tools every section shares”Placement works the same way everywhere, so these four appear in Waypoints, Start Positions, Pits and Props alike:
- Translate / Rotate / Scale — the gizmo. Gates and pit lines also resize by dragging the gizmo’s side and top handles directly.
- Snap to ground — click it to cycle: off (red), terrain (green), raycast (blue). Terrain follows the landscape; raycast lands on whatever is actually under the point, roads and bridges included.
- Set to my vehicle’s position — moves the selected thing to where you are standing.
- Teleport my vehicle here — the reverse: moves you to the selected thing, which is how you check a gate is where you think it is.
Reset to last saved state undoes your changes to the selected gate or slot, not the whole race.
Race Info
Section titled “Race Info”| Control | What it does |
|---|---|
| Name | 3 to 40 characters, and unique on this map. The save is refused otherwise. |
| Mode | Grid (a lobby, a countdown, a field) or Passive (no lobby at all). |
| Loopable | Makes the route a circuit: the last gate is also the start/finish, and the race runs laps. Off means point to point, driven once. Pits need this on. |
| Passive | Lets players run the race alone in freeroam — driving through its start gate starts the clock. One lap, timed on the race’s own Passive board. |
| Distance | Measured, not entered. It updates as you place gates. |
| One-way gates | On: a gate only counts crossed the forward way. Off (the default): it counts either way, so a missed gate can be backed through once. |
| Branching paths | Lets a gate have more than one valid next gate, so a route can genuinely fork. Sectors are disabled while this is on, and so is limiting visible gates. |
| Manual sector boundaries | Choose the sector splits yourself by flagging gates, instead of an even split by distance. |
| Sectors | How many sectors a lap is split into for split times. Clamped to between 1 and 12, and never more than the gate count. |
Waypoints
Section titled “Waypoints”Add gate at my position places a gate where you are — in a car or on foot, facing the way you are facing. The empty state says it plainly: “No gates yet. Drive or walk to a checkpoint location and click Add.”
Each gate row expands to its own detail:
| Field | What it does |
|---|---|
| Width / Height | How big the gate is. Wide enough to be crossed at speed without being so wide it catches a parallel road. |
| Sector boundary | A sector ends at this gate. The final gate always ends the last sector regardless. |
| Positioning | Set to my vehicle’s position, or reset this gate to its last saved state. |
The first and last gates are labelled for you: (Start), (Finish), or (Start/Finish) on a circuit, where they are the same gate.
Reverse flips the whole route: the gate order reverses and each gate turns to face the other way. The editor is explicit about the catch — “Start positions aren’t moved, so check they still make sense for the new direction.” A reversed circuit usually needs its grid rebuilt.
On a branching route
Section titled “On a branching route”Turning Branching paths on adds three fields to every gate:
| Field | What it does |
|---|---|
| Step | Read-only: this gate’s place in the route, one after the furthest gate it is reachable from. Gates sharing a step are alternates, and only one of them is crossed per run. |
| Valid finish | Crossing this gate can end the race. A loopable race’s finish is always its own step-1 gate instead, whatever this says. |
| Reachable from | Which gate or gates this one may be crossed after. Add Start to make it reachable straight off the grid. |
Branching is the one choice on this page that closes doors: no sectors, no limiting visible gates, and no pit lane.
Start Positions
Section titled “Start Positions”Add start position at my position places a grid slot. Park where the car should sit, facing down the track, and click. Again the empty state tells you: “No start positions yet. Drive or walk to a grid slot and click Add.”
Three things to know, each of which catches someone:
- The list order is the grid order. Slot 1 is pole. The list reorders by dragging.
- The number of slots is the maximum field size. A race with one start position can never be joined by anyone else — BeamJoy forces it solo and turns Multiplayer off on save.
- Each slot owns a pit box. Reordering or deleting a slot takes its box with it.
The Pits section only appears once the race is Loopable, because a pit lane on a point-to-point route has nothing to rejoin.
A pit lane is four things: an entry line, an exit line, the two gates it sits between, and a box per grid slot. Until all four are right the pits stay off, and the section says which one is missing — in this order:
| It says | What to do |
|---|---|
| A pit lane is for circuits: turn Loopable on in Info first. | Turn Loopable on in Race Info. |
| Pits don’t work on a branching route yet. | Turn Branching paths off, or build the race without pits. |
| Place PIT IN and PIT OUT to use the pits. | Place both lines. |
| Pick the gates the pit lane joins after and rejoins before (they can’t be the same). | Set Joins after and Rejoins before. |
| Add start positions first: each one gets a pit box. | Build the grid first. |
| Pits stay off until every start slot has a box. | Place the boxes it lists. |
When all of it is done the section says Pits ready: the start menu and each phase can use them.
The lane
Section titled “The lane”| Control | What it does |
|---|---|
| PIT IN / PIT OUT | The two lines, placed at your car or the free camera facing the way you are driving, or placed with the mouse. |
| Joins after | The last gate before PIT IN: the pit lane only counts right after it. Set from where PIT IN is, and set again when you move the line. |
| Rejoins before | The first gate after PIT OUT. The gates in between are credited to whoever goes through the lane, so nobody loses a lap for pitting. |
| PIT IN width / PIT OUT width | How wide each line is. |
| Speed limit (km/h) | The lane’s limiter, on from PIT IN to PIT OUT. Entering faster costs the server’s pit entry penalty. |
| Delete pit lane | Removes the lane, both lines and every box. It asks first. |
Placing
Section titled “Placing”Either place a line or a box at your car — or the free camera — facing the way you are driving, or place it with the mouse: a ghost follows the mouse over the world, the wheel turns it, a click places it. While placing:
| Key | What it does |
|---|---|
| Click | Place it |
| Wheel | Turn it |
| Ctrl + Wheel | Turn it 1° at a time |
| Ctrl + Click | Place it and go on to the next slot without a box |
| Right-click | Stop |
Fixed rotation keeps a line or box at its own heading whichever way you look, instead of facing the camera. It is the same switch the props use.
Ctrl+click is the one to learn: it walks you down the grid placing a box per slot without going back to the window between each.
Props are the barriers, cones, tyre stacks, curbs, walls and painted lines that turn a route into a track. Add props opens the props drawer beside the editor; pick a prop, then click the ground to place one, or drag to lay a line of them.
The drawer has five tabs:
| Tab | What is in it |
|---|---|
| Curated | The hand-tuned set: the props that stand up the right way and are sized sensibly. Start here. |
| All game meshes | Everything the game has. These are not tuned by hand — BeamJoy stands each one up from its size, so some face the wrong way and need turning after placing. |
| Prefabs | Props made of several meshes, placed, moved and deleted as one: gazebos, billboards on their stands. |
| Curbs & walls | Drawn along the ground in one piece: drag to lay one, then bend it by its middle handle. Always solid. |
| Paint | Painted lines laid on the ground, bent the same way. Cars drive over them, never into them. |
Favourites, Recent and All sit down the drawer’s own rail, and the search takes a / from
anywhere. Props can also be listed from the game’s other maps, which is where most tyre stacks
and arch gantries come from.
Dragging lays a line rather than a prop, and a line stays one object you can keep adjusting:
- Props on the line, or Fixed gap instead — one prop every so many metres, so a longer line gets more of them. Guardrails want the gap; a cone chicane wants the count.
- + Node and clicking the line’s path both add a bend point; Remove node and Delete take one out; Straighten takes them all out.
- Follow the ground sits each prop on the ground beneath it, so the line rides humps and dips.
- Alternate with gives every other prop a different mesh — red and white barriers in turn.
- End caps put a closing mesh on either end, facing out of the line.
- Split into props turns the line into single props, each where it was.
Working with what you have placed
Section titled “Working with what you have placed”| Control | What it does |
|---|---|
| Click / Ctrl+click / Shift+click | Select one (a grouped prop selects its group) / add or remove from the selection / select one of a group alone. |
| Group / Ungroup | Makes a selection move, turn, copy and delete as one. |
| Solid / Drive-through | Whether cars hit the prop or pass through it. Paint is never solid. |
| Collision while editing | Off by default so you can drive through your own track while building it. Turn it on to feel it as players will; any edit turns it back off. |
| Eyedropper | Arms that prop again, exactly as it is — scale, collision and line settings included. |
| Copy / Paste | Copies the selection, or everything, and pastes it where it was copied. Props copied on another map are refused. |
| Swap mesh | Gives a placed prop a different mesh without moving it. |
The budget is 1000 props per race, shown as a bar in the drawer with the striped part being what you are about to place. A line that would go over is cut short rather than refused.
Race Defaults
Section titled “Race Defaults”This section is every rule the race carries when someone starts it. What each one does is Racing’s subject, not this page’s — here is where to find them.
| Accordion | What it holds |
|---|---|
| (top of the section) | Multiplayer, Grid placement, Respawn strategy, Auto-spectate on finish, Laps, Timing starts, Out lap, DNF on stall and its timeout, Rejoin time, the reset penalty and the reset speed limit. |
| Vehicle Restrictions | Free, Single Config or Pool; the captured vehicle; the allowed-vehicle preset; randomise assignment; allow tuning. |
| Ghosting | Ghost on grid, Disable collisions, Ghost backmarkers, Hide other racers, the start sequence and the jump start penalty. |
| Pits | Start from grid or pits, ghosting in the lane, required stops and the penalty for missing one, refuelling and fill rate, start fuel, repairs, tyre changes, towing, and returning to the pits between phases. |
| Anticheat | Disable node grabber, Disable Free Cam, Disable gravity changes. All three are on by default, and turning any of them off forfeits the leaderboard. |
| Display | Gate markers, gate nametags, limiting visible gates to the next 1–5, and waypoint beams. |
| Advanced timers | Countdown, and — only while Multiplayer is on — the grid ready timeout and the grid timeout. |
| Race phases | Turns this race into an event of up to 20 phases. Edit phases builds the list; One race takes it back to a single race. |
| Plugins | Only appears when a server plugin has added race options of its own. |
Everything here is a default: the host can still change most of it in the start menu when they actually run the race. Setting them here means they do not have to.
Saving
Section titled “Saving”| Button | What it does |
|---|---|
| Save | Writes the race. Greyed out until something has changed, and while you are not allowed to save this one. |
| Save as new race | Asks for a name and saves a copy, your unsaved changes included. The original is untouched. |
| Delete | Removes the race. It asks first, and it cannot be undone. |
| Back to list | Leaves the editor, asking first if there is anything unsaved. |
Saving an existing race deletes its recorded times. This is deliberate: gates can move under a saved race, and a time set on a different layout is not comparable to one set on this one. The confirmation tells you how many times you are about to lose when there are any.
A save is refused outright if:
- the name is under 3 or over 40 characters, or another race on this map already has it;
- there are fewer than 2 gates, or no start position at all;
- a gate or a start position has no position or no direction.
And quietly corrected if: the sector count is above 12 or above the gate count; Multiplayer is on with only one grid slot; a vehicle restriction names a vehicle or preset that no longer exists.
Share codes
Section titled “Share codes”A race can travel to another server as text. Copy Share Code puts a BJRACE1: code on your
clipboard; Import from Code replaces whatever is in the editor with the race in a pasted code,
which is then validated exactly like any other save.
The code carries the route itself — gates, grid, pits, props and defaults. It does not carry the map, so a code only makes sense on the map it was built for, and it does not carry recorded times. Some game builds lack the compression the codes are built on; on those the two buttons are hidden rather than shown broken.
Importing a map’s own races
Section titled “Importing a map’s own races”Most official maps ship with their own time trials and quick races. Import map races finds them and lets you pick, with three ways to take them:
| Mode | What it does |
|---|---|
| Everything | Adds the ticked races as new BeamJoy races, with their barriers and cones as props. You can adjust them in the editor afterwards. |
| Gates and grid only | Adds the ticked races with no props: just their gates and grid slots. |
| Props only | Adds the map’s barriers and cones to races you already have with the same name. Their gates, slots, options and times stay as they are, and props they already have are not added twice. |
Each row tells you what it is first — circuit and lap count or point to point, branching, gate and slot counts, prop count — and why it would be skipped: name already used, can’t be read, no props. Imported races keep their original author, not whoever clicked Import.
Who may edit what
Section titled “Who may edit what”| Setting | Where | What it does |
|---|---|---|
| EditRaces | Groups and permissions | Opens the Races tab at all. mod and above by default. |
| Restrict editing to authors | Config → General → Race Editor | Only staff and a race’s own creator may edit or delete it. Off by default. |
| Only show editable races | Config → General → Race Editor | Hides races you cannot manage from the list, rather than showing them greyed. |
While the restriction is on, the Save button on someone else’s race is disabled before you start rather than after, and its tooltip says why: “Only the author of this race (or staff) can save changes to it.” A race you are still creating has no author to conflict with, so it is always yours to save.
What to know before you rely on it
Section titled “What to know before you rely on it”- Races are per map. They are stored against the map they were built on, and a map switch shows a different list. Nothing is lost; it is just not on this map.
- Saving wipes that race’s leaderboard, every time, not only when the gates moved.
- Props are the expensive part. A thousand of them is the cap for a reason — every player on the server loads every prop in a race they join.
- Branching rules out sectors and pits. Decide which you want before you build the route, not after.
- A reversed route keeps its grid. Reverse is a two-step job: flip the gates, then rebuild the start positions to face the new first corner.
- One start position means a solo race, whatever the Multiplayer toggle looked like when you saved.
- Racing — what every rule in Race Defaults actually does.
- Your first race night — running what you just built.
- Every feature, one row — the rest of BeamJoy.
- Groups and permissions — deciding who may build races at all.