> 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/rules.md).

# Rules

Defines race rule enforcement and penalties for track limit violations.

This system can:

* Detect various track limit events (cuts, out-of-circuit, position gain, stopping)
* Apply penalties such as time penalties, money fines, return position requirements, or disqualification

***

### Global Settings

| Key       | Default | Description                                         |
| --------- | ------- | --------------------------------------------------- |
| `Enabled` | `true`  | Enables or disables the entire rule/penalty system. |

***

### Rules Data

All rules are configured inside `Config.Rules.Data` and keyed by a `TrackLimits.*` type.

```lua
Config.Rules.Data[TrackLimits.SOME_RULE] = { ... }
```

Each rule entry supports:

* `Enabled` *(bool)* → turn rule on/off
* Rule-specific configuration values *(timers, thresholds, etc.)*
* `Penalties` → list of penalties to apply when rule triggers

***

### Penalties

Penalties are processed in order and can include multiple types at once.

#### Penalty Types Used Here

| Type                      | Description                                                                             |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `Penalty.TIME`            | Adds a time penalty (milliseconds).                                                     |
| `Penalty.MONEY`           | Removes money from the player (currency amount).                                        |
| `Penalty.RETURN_POSITION` | Forces player to give back a gained position within a time limit, otherwise disqualify. |

> ⚠️ Values are typically expressed in **milliseconds** for time-based penalties.

***

## Track Limits Rules

### 1) TrackLimits.CHECKPOINT\_CUT

Prevents players from leaving the circuit **too close to the next checkpoint**.

| Key                | Default | Description                                                                                |
| ------------------ | ------- | ------------------------------------------------------------------------------------------ |
| `Enabled`          | `true`  | Enables checkpoint-cut detection.                                                          |
| `LastOutOfCircuit` | `3000`  | How many ms before the next checkpoint the player is not allowed to go out of the circuit. |

#### Penalties (Default)

| Penalty Type   | Value  | Meaning                        |
| -------------- | ------ | ------------------------------ |
| `Penalty.TIME` | `2500` | Adds a **+2.5s** time penalty. |

✅ Optional example (commented in config): money penalty can be added instead or alongside time.

***

### 2) TrackLimits.POSITION\_CUT

Triggers when a player goes out of the circuit **and gains a position in the same sector** (between checkpoints).

| Key       | Default | Description                       |
| --------- | ------- | --------------------------------- |
| `Enabled` | `false` | Enables position-cut enforcement. |

#### Penalties (Default)

| Penalty Type              | Value   | Meaning                                                                 |
| ------------------------- | ------- | ----------------------------------------------------------------------- |
| `Penalty.TIME`            | `1000`  | Adds a **+1.0s** time penalty.                                          |
| `Penalty.RETURN_POSITION` | `30000` | Player must return the position within **30s**, otherwise disqualified. |

***

### 3) TrackLimits.OUT\_OF\_CIRCUIT

Triggers if player stays out of the circuit for too long.

| Key       | Default | Description                               |
| --------- | ------- | ----------------------------------------- |
| `Enabled` | `true`  | Enables out-of-circuit enforcement.       |
| `Time`    | `10000` | Max allowed out-of-circuit duration (ms). |

#### Penalties (Default)

| Penalty Type    | Value  | Meaning                        |
| --------------- | ------ | ------------------------------ |
| `Penalty.TIME`  | `5000` | Adds a **+5.0s** time penalty. |
| `Penalty.MONEY` | `1500` | Charges the player **$1500**.  |

***

### 4) TrackLimits.STOPPING\_VEHICLE

Triggers if player stops the vehicle on track (or in prohibited area) for too long.

| Key              | Default | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `Enabled`        | `false` | Enables vehicle stopping rule.      |
| `WarningTime`    | `7500`  | Time (ms) before showing a warning. |
| `DisqualifyTime` | `10000` | Time (ms) before disqualification.  |

***

### Notes

* You can enable/disable each rule independently via its `Enabled` flag.
* Penalties can be combined (e.g., time + money).
* Use `Penalty.RETURN_POSITION` if you want competitive enforcement against gaining advantage.