Tracks & races

Track types

Each track also has a vehicle kind: CAR, MOTORCYCLE, BOAT, or AIRCRAFT (checkpoint visuals and props differ by kind).

Who can create tracks

By default you need racing rep ≥ Config.TrackCreateMinRep (default 100), unless you are:

• A racing admin (ACE / framework admin / Config.AdminIdentifiers)
• On Config.TrackCreatorWhitelist
• Listed in gs_racing_creators (admin-managed)

See Economy & permissions.

Track creator

Open GS Racing → create track. In-world controls (indices in config; labels follow the player's binds):

Limits:

Config.MinCheckpoints = 3
Config.MinTrackLength = 200.0 -- meters

Props come from Config.PlaceableObjects (can be filtered by vehicle kind).

Verification

Admins can mark tracks verified. If Config.RequireVerifiedTrackToHost = true, only verified tracks (or the creator's own drafts) can be hosted. Full Stewards UI: Stewards (admin).

Hosting a race

From Host in the tablet, pick a track and set:

• Mode (sprint / laps / drift) — taken from the track type
• Laps (circuit / drift)
• Vehicle class filter (or open)
• Entry fee / host contribution (bank)
• Timing — open now, or schedule a start

Phasing (ghosting) uses server defaults from config for each lobby; see Phasing.

Defaults and caps:

Config.DefaultEntryFee = 500
Config.DefaultHostContribution = 0
Config.MaxEntryFee = 100000
Config.MaxHostContribution = 500000
Config.MinParticipantsToStart = 1
Config.PrizeDistribution = 'TOP3'
Config.Top3Shares = { 0.55, 0.30, 0.15 }

Prize pot = entry fees collected + host contribution. Distribution styles: EVEN, NORMAL, TOP, TOP3.

Joining

1. Drive near the race start circle (drawn when a lobby is open)
2. Read the floating race info card (or classic 3D text if the card is disabled)
3. Press the join key (Config.JoinKeybind, default E) when close enough
4. Be in an eligible vehicle for the race class/kind
5. Entry fee is charged from bank (refunded on cancel / disconnect when enabled)

Config.JoinProximity = 60.0          -- see markers + world card
Config.JoinInteractDistance = 15.0   -- must be this close to press join
Config.JoinCircleRadius = 8.0
Config.LobbyLeaveDistance = 50.0     -- wander too far → leave lobby
Config.LobbyLeaveGraceMs = 4000
Config.JoinWorldCard = true          -- floating DUI card at start (false = classic DrawText3D)

World join card

When Config.JoinWorldCard is true (default), players see a clean in-world DUI panel above the start circle instead of GTA draw text. It shows track name, type/laps, vehicle, prize pool, countdown, participants (and max grid when set), plus join/start key prompts.

• On — DUI card (recommended)
• Off — classic DrawText3D labels (same join/start binds)

Owners only toggle the boolean; sizing and draw distance are handled internally. Keybinds still use JoinKeybind / HostStartKeybind and only work within JoinInteractDistance.

Hosts can start from the circle with Config.HostStartKeybind (default G) once min participants are met.

Race flow

1. Countdown — Config.CountdownDuration (default 30s)
2. Freeze — vehicles freeze when remaining ≤ Config.FreezeAtRemaining
3. GO — timers start; phasing/ghosting begins if enabled (see below)
4. Race — checkpoints + GPS blip; HUD updates
5. Finish — first finisher starts DNF grace (Config.DnfGraceMs); hard timeout Config.RaceTimeoutMs

Config.CountdownDuration = 30
Config.FreezeAtRemaining = 10
Config.DnfGraceMs = 120000
Config.RaceTimeoutMs = 45 * 60 * 1000
Config.SoloCheckpointIdleMs = 60000  -- solo idle DNF between checkpoints
Config.CheckpointWorldLabels = true  -- floating DUI distance cards on upcoming CPs

Checkpoint world labels

When Config.CheckpointWorldLabels is true (default), the next few checkpoints show floating DUI cards with live distance and a stem line to the gate (next CP highlighted; finish in green). Labels sit high when far and drop/shrink as you approach; distant cards fade in. Native checkpoint tubes stay, but directional chevron / checkered-flag icons are suppressed. Countdown at the start line also uses the DUI instead of draw-text + flag. Set false to restore classic arrows, flags, and 3D text.

Phasing (ghosting)

Phasing turns racers into ghosts so they pass through each other at the start instead of stacking collisions on the grid.

How it works

1. Countdown ends → GO
2. If Config.PhasingEnabled is true, each racer becomes a ghost (SetLocalPlayerAsGhost)
3. Ped + vehicle alpha drops (~180) so ghosts look translucent
4. After the phasing window, ghosting turns off and players get the Ghosting disabled notify
5. Finish / cancel / cleanup always clears ghost state

Phasing does not run during countdown — only after GO.

Duration

Each race stores phasing_seconds (default from Config.PhasingDuration). Auto events use the same default.

--- Master switch. false = never ghost, even if a race row has a duration.
Config.PhasingEnabled = true

--- Default seconds from GO. Written onto new races as phasing_seconds.
--- 0 = entire race.
Config.PhasingDuration = 30

--- Reserved who-gets-phasing selector (ALL | COMPETITION | NORMAL).
--- Current builds apply ghosting to all active racers when enabled.
Config.PhasingMode = 'ALL'

Host tablet creates lobbies with Config.PhasingDuration. Changing the config only affects new races — already-created lobbies keep their stored phasing_seconds.

Player feel

• You can drive through other racers while ghosted
• You still collide with world props / traffic as usual for GTA ghost behavior
• Opacity comes back when the timer ends

Tips

• Short tracks / tight starts: keep phasing on (20–45s) so the pack can sort without pile-ups
• Drift scoring still runs while ghosted — duration is independent of mode
• To ban ghosting server-wide: Config.PhasingEnabled = false

Police dispatch

When enabled, starting a race can alert LEO packs (server-side only):

Config.Dispatch = {
    enabled = true,
    resource = 'auto',     -- or ps-dispatch, cd_dispatch, qs-dispatch, ...
    when = 'countdown',    -- countdown | go | both
    chance = 100,
    jobs = { 'police', 'leo', 'sheriff' },
    -- ...
}

Override OnPoliceRaceDispatch in server/edit.lua for custom packs.

Leaderboards

Results store best times / drift scores per track and class. Players browse boards in the tablet; admins may clear via tools in the UI when available.