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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.rcore.cz/paid-resources/rcore_formula/configuration/races.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.