> 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/leisure/cuxial-pvp/configuration.md).

# Configuration

Every option of Cuxial PvP explained: rules, limits, maps, weapons, Gun Game and zones.

Everything you can adjust lives in the `data` folder. Restart the resource after any change.

| File                     | What it holds                                       |
| ------------------------ | --------------------------------------------------- |
| `data/config.lua`        | General behaviour, commands, limits, integrations   |
| `data/settings.lua`      | Armour amount and the hours of day and night        |
| `data/modes.lua`         | Which game modes are open and their minimum players |
| `data/maps.lua`          | Duel arenas                                         |
| `data/weapons.lua`       | Duel weapons                                        |
| `data/gungame.lua`       | Gun Game ladder and timings                         |
| `data/gungame_zones.lua` | Gun Game zones, written by the zone tool            |

## General

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

```lua
return {
    debug = false,
    weatherSystem = 'av',
    exitCoords = vector4(0.0, 0.0, 72.0, 0.0),
    -- ...
}
```

{% endcode %}

| Option          | Type    | Default             | What it does                                                                                         |
| --------------- | ------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| `debug`         | boolean | `false`             | `true` prints traces to the console.                                                                 |
| `weatherSystem` | string  | `'av'`              | Script used to freeze the time of day during a match. `'av'` = `av_weather`, `'cd'` = `cd_easytime`. |
| `exitCoords`    | vector4 | example             | Where players are sent when a match ends. Change it to a place on your map.                          |
| `zoneToolAce`   | string  | `'cuxialpvp.zones'` | ACE permission required to save a zone drawn with the zone tool.                                     |

## Commands · `commands`

| Option       | Type   | Default      | What it does                                                             |
| ------------ | ------ | ------------ | ------------------------------------------------------------------------ |
| `openMenu`   | string | `'Cuxiall'`  | Command that opens the menu. It is also the entry players bind a key to. |
| `exitDuel`   | string | `'exitduel'` | Command to leave the current match.                                      |
| `createZone` | string | `'pvpzone'`  | Command that opens the zone tool.                                        |

## Zone wall · `boundary`

The wall that marks the edge of a Gun Game zone.

| Option | Type   | Default | What it does                                                                       |
| ------ | ------ | ------- | ---------------------------------------------------------------------------------- |
| `near` | number | `15.0`  | Distance in metres from the edge at which the wall becomes visible.                |
| `rise` | number | `9.0`   | Height of the wall above the player, in metres, for zones saved without a ceiling. |
| `drop` | number | `2.5`   | Depth of the wall below the player, in metres, for zones saved without a floor.    |

## Fallback values · `defaults`

Applied by the server when a duel is created without a valid value.

| Option        | Type   | Default    | What it does                        |
| ------------- | ------ | ---------- | ----------------------------------- |
| `gameType`    | string | `'rounds'` | Game type. `'rounds'` or `'time'`.  |
| `rounds`      | number | `3`        | Rounds needed to win.               |
| `timeMinutes` | number | `5`        | Length of a timed duel, in minutes. |
| `dayTime`     | string | `'day'`    | Time of day. `'day'` or `'night'`.  |

## Limits · `limits`

| Option              | Type   | Default | What it does                                               |
| ------------------- | ------ | ------- | ---------------------------------------------------------- |
| `maxTeamSize`       | number | `30`    | Maximum players per team in a duel.                        |
| `maxRounds`         | number | `99`    | Maximum rounds a host can ask for.                         |
| `maxTimeMinutes`    | number | `60`    | Maximum length of a timed duel, in minutes.                |
| `maxLobbies`        | number | `50`    | Maximum open lobbies on the whole server.                  |
| `maxLobbiesPerHost` | number | `1`     | Lobbies a single player can host at once.                  |
| `createCooldownMs`  | number | `3000`  | Milliseconds a player waits before creating another lobby. |

## Discord pictures · `discord`

| Option     | Type   | Default | What it does                                                                                                                      |
| ---------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `botToken` | string | `''`    | Discord bot token used to load each player's real picture, banner and accent colour. Empty = the default Discord avatar is shown. |

The bot needs no permissions and does not have to be in any Discord server.

{% hint style="danger" %}
A bot token is a password. Never share `data/config.lua` with the token inside, and reset the token in the Discord developer portal if the file leaves your hands.
{% endhint %}

## Revive · `revive`

How the script brings a player back to life between rounds and at the end of a match.

| Option    | Type      | Default      | What it does                                                                                        |
| --------- | --------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `enabled` | boolean   | `true`       | `true` triggers the events below. `false` triggers none.                                            |
| `events`  | string\[] | two examples | Client events of your ambulance script that revive the player. Leave only the one your server uses. |
| `delay`   | number    | `500`        | Milliseconds to wait before reviving at the end of a match.                                         |

## Leaderboard · `leaderboard`

| Option           | Type    | Default | What it does                                                 |
| ---------------- | ------- | ------- | ------------------------------------------------------------ |
| `clearOnRestart` | boolean | `false` | `true` wipes the leaderboard every time the resource starts. |
| `maxEntries`     | number  | `30`    | Players shown on each leaderboard.                           |

## Match settings · `data/settings.lua`

| Option                | Type   | Default | What it does                                                    |
| --------------------- | ------ | ------- | --------------------------------------------------------------- |
| `armor.armorValue`    | number | `100`   | Armour given when a match is played with armour. From 0 to 100. |
| `dayTime.hours.day`   | number | `12`    | Hour of the clock used for a day match.                         |
| `dayTime.hours.night` | number | `0`     | Hour of the clock used for a night match.                       |

## Game modes · `data/modes.lua`

One block per game mode: `duel` and `gungame`.

| Option       | Type    | Default | What it does                                                                |
| ------------ | ------- | ------- | --------------------------------------------------------------------------- |
| `available`  | boolean | `true`  | `false` rejects the creation of lobbies of that mode.                       |
| `minPerTeam` | number  | `1`     | Duels. Players needed on each team to start.                                |
| `minPlayers` | number  | `2`     | Gun Game. Players needed to start.                                          |
| `lateJoin`   | boolean | `true`  | Gun Game. `true` lets players join a match that has already started.        |
| `spectate`   | boolean | `true`  | `true` lists the mode's matches as live matches and allows spectating them. |

## Duel maps · `data/maps.lua`

Each entry is an arena. The ones included are examples: replace them with arenas of your server.

{% code title="data/maps.lua" %}

```lua
{
    value = 'warehouse',
    label = 'Warehouse',
    spectatorSpawn = vector4(0.0, 0.0, 80.0, 0.0),
    coords = {
        team1 = {
            vector4(10.0, 0.0, 72.0, 90.0),
            vector4(10.0, 2.0, 72.0, 90.0),
        },
        team2 = {
            vector4(-10.0, 0.0, 72.0, 270.0),
            vector4(-10.0, 2.0, 72.0, 270.0),
        },
    },
},
```

{% endcode %}

| Field                          | Type       | What it does                                                                              |
| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------- |
| `value`                        | string     | Unique identifier of the map. Also the name of its picture.                               |
| `label`                        | string     | Name shown in the menu.                                                                   |
| `spectatorSpawn`               | vector4    | Where spectators are placed. Without it, the first spawn of team 1 is used.               |
| `coords.team1`, `coords.team2` | vector4\[] | Spawn points of each team. With more players than points, the points are reused in order. |

The picture of a map is `web/build/maps/<value>.png`.

## Duel weapons · `data/weapons.lua`

{% code title="data/weapons.lua" %}

```lua
return {
    { value = 'WEAPON_PISTOL',       label = 'Pistol',        roll = false },
    { value = 'WEAPON_COMBATPISTOL', label = 'Combat Pistol', roll = false },
}
```

{% endcode %}

| Field   | Type    | What it does                                                                                 |
| ------- | ------- | -------------------------------------------------------------------------------------------- |
| `value` | string  | Weapon name. It must exist on your server.                                                   |
| `label` | string  | Name shown in the menu.                                                                      |
| `roll`  | boolean | `true` makes the weapon selectable only when the host turns on the roll option of the lobby. |

The picture of a weapon is `web/build/weapons/<value>.png`.

## Gun Game · `data/gungame.lua`

| Option                | Type      | Default            | What it does                                                                                                                    |
| --------------------- | --------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `killsPerWeapon`      | number    | `3`                | Kills needed to move up one rung.                                                                                               |
| `ladder`              | string\[] | 12 weapons         | Weapons in order, from first to last, without the finisher. The host chooses how many are played; the list is cut from the end. |
| `finisher`            | string    | `'WEAPON_MACHETE'` | Last weapon of every match, whatever the ladder length.                                                                         |
| `respawnSeconds`      | number    | `5`                | Seconds a dead player waits before respawning.                                                                                  |
| `spawnProtectSeconds` | number    | `3`                | Seconds of invulnerability after spawning. Shooting ends it.                                                                    |
| `outOfBoundsSeconds`  | number    | `6`                | Seconds a player can stay outside the zone before being moved back in.                                                          |
| `boundsCheckMs`       | number    | `1000`             | Milliseconds between checks of who is outside the zone. Lower is more precise and costs more.                                   |

With `ox_inventory` running, ladder weapons take their name and icon from it.

## Gun Game zones · `data/gungame_zones.lua`

This file is written by the zone tool. Draw zones in game with `/pvpzone gungame <name>`; see [Commands & permissions](/scripts/leisure/cuxial-pvp/commands.md#zone-tool).

{% hint style="warning" %}
The zone tool rewrites the whole file every time a zone is saved. Edit it by hand only to remove or rename a zone, and keep the format.
{% endhint %}

| Field          | Type       | What it does                                                                                      |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `value`        | string     | Identifier, built from the name: `gg_` plus the name in lower case. Also the name of its picture. |
| `label`        | string     | Name shown in the menu.                                                                           |
| `points`       | vector2\[] | Corners of the zone, three or more.                                                               |
| `minZ`, `maxZ` | number     | Floor and ceiling of the zone.                                                                    |

The picture of a zone is `web/build/zones/<value>.webp`. A zone without picture shows its name and an icon.

## Player banners

The respawn card of Gun Game shows a banner behind the killer's name. To give a player a custom one, add a picture named after their Discord ID:

```
web/build/banners/123456789012345678.webp
```

With a bot token set, the player's own Discord banner takes priority.

## Common changes

### Open only duels

{% code title="data/modes.lua" %}

```lua
gungame = {
    id = 'gungame',
    available = false,
    -- ...
},
```

{% endcode %}

### Shorter, faster Gun Game

{% code title="data/gungame.lua" %}

```lua
killsPerWeapon = 2,
respawnSeconds = 3,
```

{% endcode %}

### Rename the commands

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

```lua
commands = {
    openMenu = 'pvp',
    exitDuel = 'leavepvp',
    createZone = 'pvpzone',
},
```

{% endcode %}

### Use cd\_easytime and your own revive event

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

```lua
weatherSystem = 'cd',

revive = {
    enabled = true,
    events = { 'esx_ambulancejob:revive' },
    delay = 500,
},
```

{% 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/leisure/cuxial-pvp/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.