In-Race Systems¶

raycin_races HUD Nitro Pitstops NEW: Quick Rematch

HUD, Nitro, Pitstops, and everything that happens once the race starts.

Pre-Race Briefing¶

When a race is launched, every player sees a 6-second briefing card before the start sequence begins (briefing → countdown → GO).

The card shows track info, mode, lap count, active Race Options and a minimap preview. It auto-dismisses — no input required. The countdown / F1 lights then take over.

If F1 Lights-Out is enabled, the briefing is also force-dismissed by the lights-out sequence so the 5-light strip has a clean centre-screen view.

See Race Creation → Race Start Sequences for the three start modes (Classic, F1 Lights-Out, Staggered) and the jump-start penalty.

In-Race HUD¶

The right-side HUD panel shows during an active race. Nitro bar and AHEAD / BEHIND opponent chips both live inside the HUD panel for a single tidy heads-up area (they used to be scattered around the minimap).

Element	Description
Position	Your current race position (large number at top)
Lap	Current lap / total laps
Checkpoint	Next checkpoint number
Current Lap	Running time of your current lap
Completed lap time	Briefly shown after crossing the lap line — your just-finished lap time plus a +/− delta vs your previous lap (not vs PB)
Time	Total elapsed race time
Speed	Current speed in MPH or KPH (server config)
NOS bar	Remaining nitro charge — only shown when Race Settings Nitro is active
Vehicle	Your current vehicle name
Pit Stops	Completed / required stops — only shown when Race Settings Pitstop is active
▲ AHEAD	Name, vehicle, and gap to the player directly ahead
▼ BEHIND	Name, vehicle, and gap to the player directly behind
🚩 BLUE FLAG	Pulsing blue banner when a lapping driver approaches (see below)
Weather Grip	Grip percentage indicator during degraded-traction weather
PB	Personal Best time for this track with a live +/− delta in green (ahead) or red (behind). Only shown if you have a recorded PB.
⏱ Timed Race Timer	Countdown chip in the top-right corner showing `MM:SS` remaining. Pulses red in the final 30 seconds. Only shown when Race Settings Timed Race is active.
⏱ TIME EXPIRED	Replaces the Timed Race Timer chip when the clock hits zero. Shown for ~8 seconds then fades. Signals the final lap — everyone finishes their current lap and results are shown.

Momentary Overlays¶

These appear briefly on screen during specific events and disappear automatically.

Overlay	When it appears
Position change flash	Whenever your race position changes — ▲ P2 (green, gained) or ▼ P4 (red, lost) — shown in the bottom-left corner
LAP X / FINAL LAP	At the start of each new lap (top of HUD panel)
PERSONAL BEST	When you set a new fastest lap for this track (centre screen, gold)
⚡ FASTEST LAP	When you set the fastest lap of the entire race, shown only to you (gold flash) — requires Race Settings → Fastest Lap tracker to be enabled
FINISHED P1	When you cross the finish line — shows your final position (gold for P1, silver for P2, bronze for P3)
DNF timer	Right-side countdown when you are at risk of being DNF'd; turns red and pulses when ≤ 30 seconds remain
🔀 TRANSFORMING TO [Vehicle]	Banner when a Vehicle Transform event fires, showing the incoming vehicle model name. If a countdown delay is configured a `5→4→3→2→1` counter fires first, then the swap happens. See Vehicle Transform below.
⚠ SWAP WARNING	Banner shown approximately 1 lap before the next vehicle swap in Synchronised Roll mode (with No Repeats ON). Names the incoming vehicle so you're not surprised mid-lap.
🟡 JUMP START — 5s penalty	Banner shown at race start when the host enabled F1 Lights-Out and you pressed throttle before the lights extinguished. Your vehicle freezes + goes invisible for 5 seconds while others race away. Followed by ✅ Penalty served — GO! when released.

Blue Flag¶

When a driver who is ahead of you in race position and on a higher lap comes within 100 metres of your position, a pulsing 🚩 BLUE FLAG banner appears showing their name.

This signals that a lapping driver is approaching — yield when safe so they can pass without losing time. The banner disappears automatically as soon as they move beyond 100 m.

Note: The blue flag only appears on your screen (the backmarker's). The lapping driver sees no indicator.

Sector Split Flashes¶

If the track creator has marked sector split checkpoints (up to 3 per track), a brief overlay flashes each time you cross one showing the sector number (S1, S2, S3) and your time for that sector.

Gap Units¶

Gap to other players shown as time (+1.4s) or distance (87m), configured in server settings.

Position Table (Left Side)¶

A live leaderboard showing all players ordered by race position, with their lap and checkpoint.

Hot Lap Badge¶

When Hot Lap Mode is enabled in Race Settings, a small ⏱ HOT LAP badge appears in the HUD. The race clock shows --:-- until you cross Checkpoint 1, at which point it starts counting.

Nitro (NOS)¶

When the host enables Nitro in the Race Settings:

Hold the nitro button to activate boost while the NOS bar has charge.
The NOS bar in the HUD shows remaining charge — it refills automatically while driving.
Other players see exhaust flame effects when you activate NOS.

Nitro Button¶

Input device	Button
Keyboard	Left Shift (default — host can change this in Race Settings)
Controller	L3 (Left Stick click) — press and hold the left analogue stick down

Controller note: Left Shift has no equivalent vehicle button on a gamepad. The resource automatically detects controller input and switches to L3 (Left Stick) instead. You do not need to configure anything.

Nitro Settings (Race Settings)¶

Setting	Effect
Boost Power	Speed multiplier when NOS is active
Drain Rate	How quickly the bar empties per second
Regen Rate	How quickly the bar refills per second
Regen Delay	Seconds of cooldown before regen starts
Torque Multiplier	Additional torque applied during boost
Refill on Lap	Bar refills to 100% at each new lap start

Pitstops¶

When the host enables Mandatory Pitstop in the Race Settings, all players must complete one or more timed pit stops. The Pit Stops counter in the HUD shows done / required.

Pitstop Modes¶

Lap Mode (default)¶

The pitstop triggers automatically when the driver completes the configured trigger lap (e.g. lap 3 on a 5-lap race).
The vehicle is frozen in place for the configured freeze duration (seconds), with a ghost effect applied.
The countdown is shown on screen. After the timer expires the driver is released.
One stop per race — once triggered it won't fire again.

Checkpoint Mode¶

The pitstop triggers each time the driver passes through a specific pitstop checkpoint.
The vehicle freezes for the configured duration, ghosts, then releases.
The HUD counter increments each time a stop is completed. Multiple stops per race can be required.

Zone Mode¶

A pit zone (x/y/z + radius) is configured in Race Settings. The driver must enter the zone and remain at ≤ 5 mph for the full freeze duration — a progress bar fills as they dwell.
If the driver speeds up or leaves the zone the progress bar resets and they must dwell again.
Supports per-lap requirements and DQ on Miss (auto-disqualify if per-lap requirement is missed at lap end).

Setting the pit zone coordinates — three methods:

Method A — Save with the track in raycin_creator (recommended)

Open raycin_creator → load or create your track.
Drive to the intended pit location in-world.
Open Race Detail submenu → click 📍 Set Pit Zone (Zone Pitstop mode).
Coordinates are captured from your current position and saved into the track JSON as ptz.
Optionally set the Pit Zone Radius (5–50 m) in the list that appears after setting.
Save/publish normally.

When the host opens this track in raycin_races the Zone fields in Race Settings auto-fill from the saved coordinates. A log line confirms: [PitZone] auto-filled from track: x=... y=... z=... r=...

Method B — Manual coordinate entry in Race Settings

Look up the world coordinates from a map tool or in-game /coords command.
In the race room → Race Settings → Pitstop section → enable Pitstop → set mode to Zone.
Three number inputs labelled X / Y / Z appear.
Enter the coordinates and click Apply.
The status row updates to "✓ Zone set (manual)".

Method C — In-world capture at race time

Travel to the pit location in-world (requires being near the track).
In Race Settings → Pitstop → Zone mode, click "📍 Set zone to my position".
Status updates to "✓ Zone set (in-world)".

Priority: if the track has saved ptz data it auto-fills when the room opens (source = "track"). In-world capture and manual entry override it (source = "live" or "manual") and won't be overwritten by the auto-fill.

Ghost During Stop¶

All three modes ghost the player's vehicle (semi-transparent, no collision) for the duration of the freeze. Prevents other players from being blocked by a stationary car.

Weather-Adjusted Duration¶

If the host changes the weather mid-race, the freeze duration is automatically recalculated from the original configured value:

Weather	Freeze duration multiplier
CLEAR, OVERCAST, CLOUDS, FOGGY, SMOG, NEUTRAL	× 1.0 (no change)
RAIN	× 1.5
THUNDER	× 1.5
BLIZZARD, SNOW, SNOWLIGHT, XMAS	× 1.5

Fuel and Tyre Restore¶

If Fuel System (Race Settings) or Tyre Wear is active, completing a pitstop (any mode) fully refuels the vehicle and restores tyre grip to 100%.

Fuel System¶

When the host enables Fuel System in Race Settings:

Each vehicle has a fuel bar visible in the HUD.
Fuel drains at the configured rate while racing.
A low-fuel notification fires at 20%.
When fuel reaches 0 the engine cuts out — the vehicle slows to a halt.
Fuel is restored to 100% by completing a pitstop (any mode).

Settings: Drain Rate (bar units per second), Start Level (0–100%).

Tyre Wear¶

When the host enables Tyre Wear in Race Settings:

Tyre grip (fTractionCurveMax) degrades by a fixed amount each lap.
A warning notification fires when grip falls below 30%.
Grip is fully restored by completing a pitstop.

Settings: Wear per lap, Minimum grip (floor before undriveable).

Vehicle Transform HUD¶

When the host enables Vehicle Transform in Race Settings, the race periodically swaps everyone into a new vehicle at the configured trigger points (lap boundary, time, checkpoint, etc.). Two on-screen notifications fire for each swap.

Swap notifications¶

1. Announce banner — fires when the trigger condition is met:

🔀 Vehicle Transform!  →  Zentorno

Appears centre-screen. Names the incoming vehicle so you know what you're about to be driving.

2. Countdown — if the host configured a Countdown Delay (seconds), a countdown fires after the announce banner before the actual vehicle swap:

  5  →  4  →  3  →  2  →  1  →  [SWAP]

Each digit replaces the last in the same banner position. The swap happens at 0 — you do not have to do anything; the vehicle change is automatic.

Example: Host sets Vehicle Transform → trigger = Every Lap → Countdown Delay = 5 s. At the lap line: "🔀 Vehicle Transform! → Adder" appears. A 5-second countdown fires. At 0 everyone transforms into an Adder simultaneously.

No-countdown variant: if Countdown Delay is set to 0, the announce banner still appears briefly but the swap happens immediately — no countdown.

Tip: If you're near the lap/checkpoint trigger at speed, the announce banner is your warning to straighten up and brace for the transition animation. The vehicle swap is slightly faster than a spawn — expect a brief visual flash.

Slipstream / Drafting Boost¶

When enabled in Race Settings, staying directly behind another vehicle at race speed charges a one-use speed boost.

Visual indicators¶

State	What you see
Drafting	Three green chevrons (›››) appear on screen, pulsing to indicate you are in the draft cone and charging the boost.
Boost ready → fires	A gold "BOOST!" flash appears as the boost triggers automatically.
Draft broken	Chevrons disappear immediately when you leave the draft zone.

The boost fires automatically once fully charged — you do not press a button. The chevrons are only visible to the drafting player, not to the vehicle being drafted.

Settings: Boost power, Minimum speed (m/s), Required draft time (seconds), Boost duration (seconds).

Weather Grip Effects¶

When the Race Settings Weather Event fires (or if rain/thunder was set at race creation):

Weather	Traction	Braking
Clear / Extra Sunny	100%	100%
Rain	75%	85%
Thunder	65%	80%
Blizzard	60%	75%
Snow Light	70%	82%

A Weather Grip percentage indicator appears in the HUD during degraded weather conditions.

Post-Race Rewind / Replay Ghost¶

(Disabled by default — performance impact on large fields)

When enabled by the server admin, every player's position, heading, and speed is recorded every 100 ms during a race into a circular buffer. After the race, the last N seconds can be replayed with ghost vehicles at each player's recorded positions. Recording infrastructure is in place; full playback UI is in development.

Config: Config.ReplayGhost.enabled = true in config/config_client.lua.

Race Points (RP) & Leaderboard¶

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.

Stats Site¶

A web-based stats site shows all-time best times per track, track details, and the global leaderboard. Ask your server admin for the URL.

Fastest Lap Tracking¶

When Fastest Lap is ON in Race Settings, the fastest lap time across all players is tracked in real time. Whenever a new fastest lap is recorded the whole field is notified with the player name and time. A bonus RP amount is awarded if configured by the server admin.

If you set the race's fastest lap, a ⚡ FASTEST LAP gold banner appears on your screen confirming the achievement.

Post-Race Scoreboard¶

The scoreboard appears automatically when you finish or DNF. It shows position, vehicle, total time, best lap, and points for every driver.

Lap Breakdown¶

After finishing a race, your row in the scoreboard has a small ▾ toggle button next to your name. Clicking it expands a row beneath your result showing your individual lap times:

L1  1:23.456   L2  1:22.987   L3  1:24.102

Lap breakdown is shown only for your own row — other players' per-lap times are not tracked client-side so no toggle appears on other rows.
The toggle only appears if you completed more than one lap (it is hidden in P2P / sprint races).
Click ▾ again to collapse the row.

Quick Rematch — ↺ REMATCH Button¶

When the scoreboard appears at the end of a race, the host only sees a ↺ REMATCH button at the bottom. Clicking it re-runs the same race instantly, skipping the lobby entirely. Other players just see the scoreboard.

What it does¶

One click → the server re-fires the race-start sequence on the same room, with everyone still in their seats. Players don't have to: - Return to the race lobby menu - Re-accept an invite - Re-pick a vehicle - Re-tick any race settings - Stand on the start grid manually

The grid loads, the countdown fires, the race begins again — typically in 3–5 seconds from button click to grid teleport.

What carries over (everything, unchanged)¶

Setting	Carries over?
Track	✓ Same one
Laps	✓ Same count
Vehicles Mode (Default / Specific / Personal / Random / Track Class)	✓ Same
Vehicle Classes / Vehicle Preset / Custom Vehicle List	✓ Same pool
Synchronised Roll, No Repeats, Per-Checkpoint Re-roll	✓ Same
Weather, Time of Day, Traffic, DNF Timer	✓ Same
Special modes — DLP, Hot Lap, Fair Start, Fuel, Tire Wear, Ghost-on-Contact, Explode on Impact, etc.	✓ Same
Roster (every player who finished, DNF'd, or was spectating)	✓ Re-grids together
Track Star Rating already given	✓ Not re-prompted

What gets re-rolled (intentionally)¶

What	Why
Sync rotation sequence (Synchronised Roll ON)	The server re-picks which vehicle each lap/checkpoint gets — same pool, fresh randomised order. So if your Custom List was 12 cars, lap 1 might have been the Adder last race and might be the Zentorno this race.
Random vehicle assignments (Sync OFF)	Each player re-rolls their starting vehicle from the same class pool.
Starting grid positions	Reshuffled (unless Fair Start / handicap-based starting order is enabled, in which case position depends on the previous race's result).
Lap timers, best laps, scoreboard	Wiped clean — it's a fresh race, not a continuation.
Career points (if enabled)	Each race is scored separately, so the rematch awards a new set of points based on its own finish positions.

What it can NOT do¶

Limitation	What to do instead
Add new players who joined the server during the race	Return to lobby → reopen the race room so they can join the normal way
Change track	Return to lobby → pick a new track
Change ANY race setting (laps, weather, VP options, etc.)	Return to lobby → adjust settings → start a new race
Drop a specific player from the roster	They must leave themselves (or you kick them in lobby) before rematch
Bring back a player who quit during the race	They must rejoin via the race browser before the rematch grid loads

Who can click it¶

Only the race host (the original room owner) sees the button.
If the host leaves before clicking, the button vanishes — host transfer doesn't carry it over. Anyone wanting another race must reopen the race room from the lobby.

Worked example — "Rapid-fire stunt session"¶

Scenario: 4 players, stunt-45 track, 6 laps, Custom Vehicle List of 6 bikes, Sync ON + No Repeats ON. Race ends. Everyone wants another go but with the SAME setup — just to see if anyone can beat their best lap.

Old workflow (without Rematch): 1. Host clicks "Back to Lobby" on scoreboard → lobby opens 2. All 4 players returned to lobby 3. Host re-opens the race room (same track) → 4 invites fire 4. 3 other players have to accept the invite again 5. Host re-applies all VP settings (or trusts they're still cached — depends on server) 6. Host clicks Start 7. ~30–60 seconds wasted between races, easy for someone to wander off

New workflow (with Rematch): 1. Scoreboard fades in → host sees ↺ REMATCH button 2. Host clicks it 3. ~3 seconds later — grid loads, countdown fires, race 2 starts. Same 4 players, same bikes pool, fresh rotation order. Best laps to beat are still in your head from a minute ago.

Why this matters: rematch keeps a session's momentum. Five quick rematches in a row = 5 short races with the same friends instead of 5 trips back to the lobby with people drifting off between them.

Common pitfalls¶

"I clicked Rematch but nothing happened." → You're not the host (or you were and lost host before clicking). Only the room owner can trigger it.
"Same race re-ran but the vehicles are different from last time." → Intentional. Sync rotation is re-rolled from the same pool each race so consecutive rematches don't feel identical.
"I want to tweak the laps before the next race." → Rematch can't change settings. Return to the lobby for any change.
"My friend joined the server mid-race — Rematch didn't include them." → Rematch only re-grids players who were in the room at the time. New arrivals need to wait for you to return to lobby.
"The Rematch button disappeared from my scoreboard." → Scoreboard auto-hides ~20 seconds after the race ends. The button goes with it. If you waited too long, return to lobby for the next race.

Recently Played Indicator¶

The race browser marks tracks that have been raced during the current session with a green ✓ PLAYED badge in the top-left corner of the card, helping hosts avoid repeating the same track.

Track Record Holder¶

Each track card in the race browser shows the current record holder's name and time (e.g. ⏱ 1:23.456 Alan) so you can see who holds the fastest lap before selecting a track.

Spectator Mode¶

When you DNF, are eliminated, or use quit_race during a race, you enter Spectator Mode — you stay in the world and can watch the remaining drivers without being teleported away.

Camera Modes¶

Cycle through camera modes using the spectator key bindings:

Mode	Description
Follow Cam	Attached behind the spectated vehicle, smooth trailing camera
Cinematic Cam	Rotating orbit camera — slowly circles the spectated vehicle for a broadcast-style view
Free Cam	Full manual camera control — WASD/left stick to move, mouse/right stick to look
Helicopter Cam	Fixed overhead looking straight down at the spectated vehicle

Switching Between Players¶

Next player → / Previous player ← — cycle through all remaining active drivers

Exiting Spectator¶

Use the quit_race key binding to leave spectator mode completely and return to freemode.
The race results screen appears automatically when the last driver finishes — you will see the full scoreboard even from spectator mode.