Competitive & Ranked¶

Qualifying, ELO rankings, seasons, racing crews, team races, and the full competitive system.

Qualifying Session¶

Qualifying is an optional timed hot-lap session run before the main race. The fastest lap time each player sets determines their grid position — fastest qualifier starts P1.

How it works¶

Host creates a room and configures it normally (track, laps, vehicle settings).
Instead of clicking Start Race, the host clicks Start Qualifying.
The track loads. All players spawn on the grid with ghost ON (no contact).
A countdown timer appears in the HUD along with each player's current best lap time.
Players lap freely until the timer expires — or the host clicks End Qualifying.
A Qualifying Results table appears showing the grid order (P1 = fastest lap).
The host clicks Start Race — the race launches with qualifying grid positions automatically applied.

Qualifying HUD¶

Element	Description
QUALIFYING label	Shown in the corner while qualifying is active
Timer	Countdown to end of session (M:SS.mmm format)
YOUR BEST LAP	Your personal best lap set so far this session

Notes¶

Ghost is ON for the entire qualifying session — no contact between cars.
Qualifying best laps are not saved as track Personal Bests.
Race Points are not awarded during qualifying — only the main race awards RP.
Players who do not set a lap time start from the back of the grid.
The host selects qualifying duration from a dropdown next to Start Qualifying: 1 / 2 / 3 (default) / 5 / 10 minutes.
Only the host can end qualifying early — a non-host player cannot see the End Qualifying button.

Full step-by-step: Race Room → Qualifying Session

ELO / MMR Ranked System¶

A per-player ELO skill rating stored in the database. After every multi-player ranked race, ELO goes up or down based on how you finished relative to what was expected given your opponents' ratings.

How it works¶

All players start at 1000 ELO.
After a ranked race, each pair of finishers is evaluated: did you beat someone you were expected to beat? Did you lose to someone lower-rated?
ELO delta per pair: K × (actual − expected) where K = 32 (standard chess K-factor).
ELO only applies when 3 or more drivers finish.
Above 2000 ELO the K-factor halves — high-rated players' ratings stabilise.

Enabling Ranked Races (host)¶

Toggle Ranked (ELO) in Race Settings (Section 4) to mark a race as ranked.

Unranked races still award normal RP but do not change ELO.
Minimum 3 players must finish for ELO to apply.
Do NOT use Catch-Up, Ghost on Contact, or other systems that distort natural race results in ranked races.

Lobby Display¶

If showInLobby is enabled in server config, each player's current ELO is shown next to their name in the race room player list: [1234 ELO].

Tips¶

Stick to Specific vehicle or Personal vehicle modes — random cars in ranked feels unfair.
DNF counts as a loss in ranked.
No special race room appearance — it looks like a normal race to players.

Seasons¶

A parallel points counter (season_points) that runs alongside cumulative RP. At the end of a season, standings are archived and points reset to zero.

How it works¶

Every race awards racePoints × pointsMultiplier season points (default multiplier = 1.0).
Season points are shown on the leaderboard alongside cumulative RP.
A separate Season Board tab in the race browser shows the current season standings.
When a season ends, all current standings are archived, then season_points is reset to 0 for all players.

Admin Commands¶

Command	Effect
`/archive_season_standings`	Archive current standings and reset season_points for all players

Season Configuration¶

Admins configure the active season in config/config_server.lua: - currentName — displayed season label (e.g. "Season 3") - pointsMultiplier — season points = racePoints × this value - endDate — display string (e.g. "2026-06-01"), or nil for no end date - announceReset = true — posts a Discord webhook embed when the season ends

Racing Crews¶

Named groups of racers with a short tag and a colour. Crew points accumulate from member race results. Crew tags appear next to player names in the race lobby.

Creating a Crew¶

Open the Crews tab in the race browser NUI.
Click Create Crew, enter a name (max 30 chars) and a tag (max 4 chars, e.g. [RR]).
Choose a crew colour from the colour picker.
Click Create — you become the crew Owner.

Joining a Crew¶

An Owner or Officer can invite you by entering your player name in the Invite field.
Accept the invite from the notification prompt.

Crew Roles¶

Role	Permissions
Owner	Invite, kick, promote, disband
Officer	Invite, kick members
Member	Race under the crew tag

Leaving a Crew¶

Open the Crews tab → click Leave Crew. If you are the Owner, ownership transfers to the next Officer (or longest-serving Member) before you leave.

Crew Points¶

After each race, each member's finishing racePoints are added to the crew's total. Crew standings are shown in the Crews leaderboard.

Lobby Display¶

Your crew tag is shown next to your name in the race room player list and in your overhead label during a race.

Team Races¶

When the host marks a race as a Team Race, finishing positions contribute to crew totals rather than individual ELO/standings. Individual RP is still paid normally.

How to Enable (host)¶

In the Race Settings panel (already open for the host in the race room), scroll to Section 4.
Toggle Team Race ON.

Team Race requires all players to be in a crew. The Race Settings toggle is only available when both Crews and Team Race are enabled in server config.

Scoring¶

After all drivers finish: - Players are grouped by crew. - Each crew's score = sum of (1 / finishing_position) across its members. - The crew with the highest score wins the Team Race and earns a crew-points bonus. - Individual race points are still awarded as normal.

Tips¶

All players must be in a Crew — crewless players cannot participate.
Strategy matters: a crew's weakest driver finishing 3rd is worth more than one driver winning but another finishing last.
Fair Start → OFF is better here — teammates can assist each other by blocking opponents.
Does not combine well with ELO/Ranked (team scoring conflicts with individual MMR calculation).

Spectator Camera Modes¶

When spectating a race, you have four camera modes that cycle with Enter. Each mode gives a different perspective on the action.

Camera Modes¶

Mode	Description
Follow Cam	Standard follow camera — attached behind the spectated vehicle
Cinematic (Director)	Smooth scripted orbit camera with mouse drag / scroll controls
Free Cam	Detached free-roam camera — move independently of the spectated driver
Helicopter	Overhead bird's-eye view, 40 m above the spectated vehicle, looking straight down

How to Cycle¶

Enter spectator mode (DNF, finish early, or join as a late spectator).
Press Enter to step through: Follow Cam → Cinematic → Free Cam → Helicopter → Follow Cam → …
A brief toast message confirms the active camera mode each time.

Changing Spectated Driver¶

Input	Action
← Arrow	Previous driver
→ Arrow	Next driver

Cinematic (Director) Mode Controls¶

Input	Action
Mouse drag	Orbit around target
Scroll wheel	Zoom in / out
R	Reset to default follow angle
Ctrl+D	Exit Director Mode

Helicopter Mode¶

The helicopter camera locks 40 metres directly above the spectated vehicle and points straight down, giving a map-like overhead view. It updates every frame — the view stays centred on the vehicle as it moves.

Pre-Race Tuning Window¶

After all players have loaded onto the grid (but before the countdown starts), a configurable timed window opens for last-minute vehicle tuning. A compact NUI panel lets players adjust engine, brakes, suspension, gearbox, and tyres directly on the grid.

How to Enable (host)¶

In the Race Settings panel (already open for the host in the race room), scroll to Section 4.
Toggle Tuning Window ON and choose a duration (15 / 30 / 60 seconds).

Player Experience¶

All players load onto grid as normal.
Instead of the countdown starting immediately, the Pre-Race Tuning panel appears.
A large countdown timer shows how many seconds remain.
Players apply any mod changes they want — changes apply to the spawned vehicle immediately.
When the timer expires the panel closes and the normal countdown begins.

Tips¶

Useful when Personal vehicle mode is used — players can tweak their build for the specific track.
Also useful if a track was just announced and players want to check their setup before committing.
Players who are ready early can simply wait — the window cannot be skipped by the host.

Track Voting¶

After a race ends, three random tracks from the same category are presented to all players. Players vote for the next track. The most-voted track is auto-selected.

Flow¶

Race ends → server picks 3 random tracks (same category, or random if configured).
A Track Vote overlay appears for all players showing 3 track cards (thumbnail, name, category).
Players click a card to cast their vote. Live vote totals update in real time.
After the vote duration:
The winner is announced.
If host override is enabled, the host sees Accept and Pick Different buttons.
On Accept (or no host action), the winning track is loaded into the room automatically.

Note: Track Voting is disabled by default. Ask your server admin to enable it in Config.TrackVoting.

Driver Rivalries¶

The Rivalries system analyses shared race history to identify your closest competitors — players you race against most often — and calculates a head-to-head win/loss record for each.

How to View¶

Open the Stats tab in the race browser NUI.
A Your Rivals section shows up to 3 rivals: name, shared race count, W/L record.
Data is fetched via the /cr-api/rivals/{license} endpoint.

Qualification¶

A player only appears as a rival once you have raced them at least 5 times (server-configurable minimum). Short one-off sessions are filtered out.

Race Director (Host)¶

During an active race the host can open Race Director controls to manage the race in real time — issue flags, penalise specific drivers, or adjust conditions without ending the race.

Full reference: Race Room → Race Director Tools — flags (🟡🟢🔴), Sin Bin, DQ, Drive-Through Penalty, Reset to Checkpoint, Ghost Toggle, Speed Limiter, Weather/Time Change, Mandatory Pit.

Post-Race Podium¶

After every multi-player race a 🏆 podium animation slides up from the bottom of the screen showing the top 3 finishers with gold / silver / bronze medals, names, and finish times. It stays visible until Lua dismisses it (typically when the race room reopens). The 5-star track rating prompt appears a few seconds after the scoreboard.

Race Points (RP) — How They Work¶

Race Points are awarded at the end of each race based on finishing position and accumulate across all races on the server.

Checking Your RP¶

Click RP BOARD in the Race Menu (right-side tab) — top-10 leaderboard.
F10 → Player Hub → My Race Points — your personal total.
F10 → Player Hub → Top 10 Leaderboard — global ranking.

Fastest Lap Bonus¶

When Fastest Lap tracking is ON in Race Settings and a new fastest lap is recorded during a race, the whole field is notified. A bonus RP amount is awarded to the player who set the fastest lap (if configured by the server admin in Config.RacePoints.fastestLapBonus).

Track Star Ratings¶

After finishing a race, a 1–5 star prompt appears briefly. Ratings appear in the race browser next to the track name as a ★ average.

Ratings are stored per player per track — you can have one active rating per track at a time.
Rating the same track again replaces your previous rating.
Ratings survive server restarts.
Tracks with no ratings show no star.

Public Stats API¶

A set of read-only HTTP endpoints that allow external websites, dashboards, or Discord bots to query live race data.

Disabled by default — requires Config.PublicAPI.enabled = true in server config.

Endpoints¶

Endpoint	Returns
`GET /cr-api/leaderboard?page=1`	Top players ranked by RP, includes ELO and season points
`GET /cr-api/season`	Current season name, standings and end date
`GET /cr-api/crews`	Crew leaderboard ranked by crew points
`GET /cr-api/drift`	Top drift scores from all sessions
`GET /cr-api/rivals/{license}`	Head-to-head rivalry data for a specific player

Authentication¶

If requireKey = true, all requests must include the header:

X-CR-Key: your_secret_key_here

Requests without the key receive a 401 Unauthorized response.