> For the complete documentation index, see [llms.txt](https://documentation.rcore.cz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.rcore.cz/paid-resources/rcore_formula/configuration/races.md).

# Races

Race-related configuration for creating, joining, and running track races. Configuration is located in `configs/config.race.lua`.

***

## Overview

`Config.Race` controls:

* Minimum requirements for race creation (racers, laps)
* Who is allowed to create races
* Join point entity + target interaction
* Countdown before race start
* Checkpoint marker appearance
* Points system (positions + fastest lap)
* Prize pool rules and payout distribution

***

## Settings

| Key             | Default | Description                                                           |
| --------------- | ------- | --------------------------------------------------------------------- |
| `MinimumRacers` | `2`     | Minimum number of racers selectable/required in the create race menu. |
| `MinimumLaps`   | `2`     | Minimum number of laps selectable/required in the create race menu.   |
| `Countdown`     | `5000`  | Countdown time in **milliseconds** before the race starts.            |

***

## CreateRestriction

Defines who can create a new race at the track join point.

### Default (Everyone can create)

```lua
CreateRestriction = {
  type = RaceCreateRestriction.ALL
}
```

### Job Restriction Example

Only players with a specific job and minimum grade can create races.

```lua
CreateRestriction = {
  type = RaceCreateRestriction.JOB,
  data = {
    job = 'fia',
    grade = 0
  }
}
```

### Admin Restriction Example

Only admins can create races.

```lua
CreateRestriction = {
  type = RaceCreateRestriction.ADMIN
}
```

| Key                            | Description                                      |
| ------------------------------ | ------------------------------------------------ |
| `CreateRestriction.type`       | Restriction mode (`ALL`, `JOB`, `ADMIN`).        |
| `CreateRestriction.data.job`   | *(JOB only)* Job name required to create a race. |
| `CreateRestriction.data.grade` | *(JOB only)* Minimum job grade required.         |

***

## JoinPoint

Join point is where players can create or join races.

### Entity

Controls what entity is spawned at the join point (usually a ped).

| Key                      | Default                   | Description                               |
| ------------------------ | ------------------------- | ----------------------------------------- |
| `JoinPoint.Entity.Model` | `` `s_m_m_cntrybar_01` `` | Model used for the join point ped/object. |
| `JoinPoint.Entity.Type`  | `1`                       | Entity type: `1 = PED`, `3 = OBJECT`.     |

### Target (Optional)

Only works if a target system is installed and configured via the bridge.

| Key                         | Default        | Description                              |
| --------------------------- | -------------- | ---------------------------------------- |
| `JoinPoint.Target.Icon`     | `'fas fa-car'` | Target icon shown in the interaction UI. |
| `JoinPoint.Target.Distance` | `4.0`          | Max interaction distance in meters.      |

***

## CheckpointMarker

Checkpoint marker settings shown on the track.

| Key                        | Default                 | Description                                                                          |
| -------------------------- | ----------------------- | ------------------------------------------------------------------------------------ |
| `CheckpointMarker.Enabled` | `true`                  | If `true`, checkpoint markers will be visible during the race.                       |
| `CheckpointMarker.Type`    | `43`                    | FiveM marker type. Reference: <https://docs.fivem.net/docs/game-references/markers/> |
| `CheckpointMarker.Scale`   | `{ 10.0, 0.01, 2.0 }`   | Marker scale as `{ X, Y, Z }`.                                                       |
| `CheckpointMarker.Color`   | `{ 235, 158, 52, 100 }` | Marker color as `{ R, G, B, A }` (A = alpha/transparency).                           |

***

## Points

Points are awarded after all racers finish. These points are used in:

* team leaderboards
* racer leaderboards
* race leaderboards

### Position Points

By default, points are set similarly to the real-life points system.

| Position | Points |
| -------- | ------ |
| 1        | 25     |
| 2        | 18     |
| 3        | 15     |
| 4        | 12     |
| 5        | 10     |
| 6        | 8      |
| 7        | 6      |
| 8        | 4      |
| 9        | 2      |
| 10       | 1      |

### Fastest Lap Bonus

| Key                 | Default | Description                                                                                  |
| ------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `Points.FastestLap` | `1`     | Bonus points awarded to the racer who sets the fastest lap. Added on top of position points. |

***

## PrizePool

Prize pool is money distributed to racers based on their final positions.

### Multipliers & Limits

| Key                                   | Default   | Description                                                                     |
| ------------------------------------- | --------- | ------------------------------------------------------------------------------- |
| `PrizePool.RegistrationFeeMultiplier` | `1.1`     | Multiplies the registration fee (e.g. `1000` → `1100`).                         |
| `PrizePool.PrizePoolMultiplier`       | `1.0`     | Multiplies the prize pool total (e.g. `10000` → `10000`).                       |
| `PrizePool.MaximumPoolAmount`         | `1000000` | Caps the prize pool amount (if calculated pool exceeds this, this max is used). |

### Distribution

Percentage split of the final prize pool per finishing position.

| Position | Share        |
| -------- | ------------ |
| 1        | 0.40 (40%)   |
| 2        | 0.20 (20%)   |
| 3        | 0.10 (10%)   |
| 4        | 0.05 (5%)    |
| 5        | 0.05 (5%)    |
| 6        | 0.05 (5%)    |
| 7        | 0.05 (5%)    |
| 8        | 0.05 (5%)    |
| 9        | 0.025 (2.5%) |
| 10       | 0.025 (2.5%) |

> ✅ Tip: Make sure the distribution adds up to `1.0` (100%) if you want the full prize pool to be paid out.