Skip to content

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.

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 required
Start positions the grid slots, in order at least 1 required
Pits an optional pit lane and boxes circuits only
Props optional barriers, cones, paint up to 1000
Race defaults the rules the race starts with all have defaults

The shortest possible race is two gates and one start position. That saves, runs, and records times. Everything else is refinement.

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
↓
Save

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.

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.

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.

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.

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.

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.

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:

  1. The list order is the grid order. Slot 1 is pole. The list reorders by dragging.
  2. 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.
  3. 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.

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.

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

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.

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.

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.

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.

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.

  • 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.