> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/core/cuxial-safezones/configuration.md).

# Configuration

Every option of Cuxial Safezones explained: the config file and the settings of each zone.

Server-wide options live in `shared/config.lua`. Everything that belongs to a single zone is set in the panel and stored in the database. Restart the resource after changing the config file.

## Command · `command`

| Option | Type   | Default       | What it does                                                                                           |
| ------ | ------ | ------------- | ------------------------------------------------------------------------------------------------------ |
| `name` | string | `'crearzona'` | Command that opens the panel, without the slash.                                                       |
| `ace`  | string | `'admin'`     | ACE permission needed to create, edit, turn off or delete zones. The server checks it on every change. |

## Interface

| Option   | Type         | Default      | What it does                |
| -------- | ------------ | ------------ | --------------------------- |
| `accent` | string (hex) | configurable | Accent colour of the panel. |

## Effects · `features`

Server-wide switches. Turning one off disables that effect in every zone, and the panel shows it as off instead of offering it.

| Option     | Type    | Default | What it does                                                                      |
| ---------- | ------- | ------- | --------------------------------------------------------------------------------- |
| `maxSpeed` | boolean | `true`  | `true` applies the speed limit of each zone. `false` never limits speed.          |
| `textUI`   | boolean | `true`  | `true` shows the sign of each zone. `false` hides all signs.                      |
| `driveBy`  | boolean | `true`  | `true` lets zones block drive-by. `false` never blocks it.                        |
| `weapons`  | boolean | `true`  | `true` lets zones block weapons. `false` never blocks them.                       |
| `debug`    | boolean | `true`  | `true` lets staff draw the volume of a zone in the world. `false` never draws it. |

{% hint style="info" %}
Invincibility has no switch. It applies in every active zone, except to players covered by an exception. On leaving, the zone only removes the invincibility it gave: a player who was already invincible on entering, for example with the god mode of an administration menu, keeps it.
{% endhint %}

## Speed

| Option          | Type   | Default | What it does                                                                             |
| --------------- | ------ | ------- | ---------------------------------------------------------------------------------------- |
| `speedDivisor`  | number | `3.6`   | Converts the speed typed in the panel to the game unit. `3.6` = the panel works in km/h. |
| `speedInterval` | number | `1000`  | Milliseconds between speed limit refreshes while a vehicle is inside a zone.             |

## Blockable controls · `blockControls`

List of controls the panel lets staff block in a zone. Each entry has a `value` (GTA control number) and a `label` (text shown in the panel). The labels in the file are examples to rename.

| Default `value` | Control      |
| --------------- | ------------ |
| `140`           | Melee attack |
| `24`            | Attack       |
| `25`            | Aim          |
| `257`           | Shoot        |

{% hint style="warning" %}
This list is also the allow-list. A control that is not in it cannot be blocked by any zone, and removing one takes it out of the zones that used it the next time the resource starts.
{% endhint %}

## Exception groups · `bypassGroups`

| Option         | Type      | Default              | What it does                                                                                                                      |
| -------------- | --------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `bypassGroups` | string\[] | `{ 'admin', 'mod' }` | Permission groups that can be used in zone exceptions, written without the `group.` prefix. The panel offers them as suggestions. |

A group gives nothing by being in this list: each zone decides who skips what. A player belongs to a group when they hold that permission in your framework (`admin`, `mod`…), checked through `cuxial_bridge`. Groups typed by hand in a zone are checked the same way.

## Limits · `limits`

| Option           | Type   | Default | What it does                                         |
| ---------------- | ------ | ------- | ---------------------------------------------------- |
| `writes`         | number | `12`    | Changes a staff member can save within one `window`. |
| `window`         | number | `10000` | Length of that window, in milliseconds.              |
| `maxPoints`      | number | `64`    | Maximum vertices per zone.                           |
| `maxBypassRules` | number | `12`    | Maximum exceptions per zone.                         |

## Editor · `creator`

| Option        | Type   | Default | What it does                                                                    |
| ------------- | ------ | ------- | ------------------------------------------------------------------------------- |
| `startHeight` | number | `5`     | Metres between your position and the ceiling of the zone when the editor opens. |

## Settings of each zone

Set in the panel when creating or editing a zone.

| Setting          | Values                     | What it does                                                                                                                                      |
| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name             | 4 to 20 characters, unique | Identifies the zone. The characters `< > " ' &` are removed.                                                                                      |
| Maximum speed    | 0 to 300                   | Limit for the vehicle a player is in. `0` = no limit. The vehicle recovers its normal top speed on leaving.                                       |
| Allow weapons    | On or off                  | Off blocks weapons inside the zone. Needs `ox_inventory`.                                                                                         |
| Allow drive-by   | On or off                  | Off blocks shooting from a vehicle.                                                                                                               |
| Sound            | On or off                  | Plays a sound when entering and leaving.                                                                                                          |
| Draw the volume  | On or off                  | Draws the zone in the world for every player, to check its shape.                                                                                 |
| Blocked controls | From `blockControls`       | Controls disabled inside the zone.                                                                                                                |
| Exceptions       | Up to `maxBypassRules`     | Who skips which rules. See below.                                                                                                                 |
| Sign             | On or off                  | Shows a sign while inside: text up to 40 characters or up to 8 coloured segments, position, font, finish, size and optional icon with its colour. |

### Exceptions

An exception targets a **job** or a **group**, and lists what it skips: invincibility, weapons, drive-by, speed or blocked controls.

* **Job**: optionally from a minimum grade upwards, and optionally only on duty.
* **Group**: one of the groups in `bypassGroups`, or any other framework permission typed by hand.
* One exception per job or group. An exception that skips nothing is not saved.
* Changing job, grade or duty status applies at once, without leaving the zone.

## Common changes

**Rename the command**

{% code title="shared/config.lua" %}

```lua
command = {
    name = 'safezones',
    ace = 'admin',
},
```

{% endcode %}

**Work in mph instead of km/h**

{% code title="shared/config.lua" %}

```lua
speedDivisor = 2.236936,
```

{% endcode %}

Change the unit in the `speed_limited` text of `locales/en.json` to match.

**Let zones block jumping**

{% code title="shared/config.lua" %}

```lua
blockControls = {
    { value = 140, label = 'Melee (R)' },
    { value = 24,  label = 'Attack (left click)' },
    { value = 25,  label = 'Aim (right click)' },
    { value = 257, label = 'Shoot' },
    { value = 22,  label = 'Jump' },
},
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/core/cuxial-safezones/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.