> 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/features.md).
# Features guide
How Cuxial PvP plays in game: lobbies, duels, Gun Game, spectating, bets and the leaderboard.
What players see and do from the moment they open the menu until the match ends.
## The menu
Players open the menu with `/Cuxiall`, with the key they bound to it, or from wherever you call the `toggleUI` export. The menu cannot be opened during a match.
From the menu a player can:
* pick a game mode and create a lobby;
* join an open lobby, with its password if it has one;
* see the live matches, spectate them and bet;
* check the leaderboard of each game mode.
## Lobbies
The player who creates a lobby is its host. Only the host can assign players and start the match.
* A host can keep one lobby open at a time (`limits.maxLobbiesPerHost`).
* If the host leaves the lobby or the server, the lobby closes for everyone.
* A lobby with a password asks for it when joining.
* A full lobby rejects new players.
## Duels
Two teams fight in one of the maps of `data/maps.lua`.
### Creating a duel
| Option | Values |
| ----------- | ------------------------------------------------- |
| Size | From `1v1` up to `limits.maxTeamSize` per team |
| Game type | By rounds or by time |
| Rounds | From 1 up to `limits.maxRounds` |
| Time | From 1 up to `limits.maxTimeMinutes` minutes |
| Weapon | One of the weapons of `data/weapons.lua` |
| Map | One of the maps of `data/maps.lua` |
| Time of day | Day or night |
| Headshots | On or off: whether headshots deal critical damage |
| Armour | On or off: full armour at the start of each round |
| Spectators | On or off |
| Password | Optional |
### Playing
1. Players who join wait unassigned. The host places each one in team A or team B.
2. With at least one player on each team, the host starts the match.
3. Everyone is moved to the arena, to the spawn points of their team, and a countdown starts the round.
4. A round ends when a whole team is down. The team left standing scores a point; if both fall at once, both score.
5. Dead players watch their teammates until the round ends. ← and → switch between them.
**By rounds**, the first team to reach the chosen number of rounds wins. **By time**, rounds follow one another until the clock runs out and the team with more points wins; equal points is a draw.
During a match, teammates carry a marker above their head, stamina does not run out and TAB shows the scoreboard.
{% hint style="info" %}
A duel is cancelled when a player disconnects or leaves with `/exitduel`. A cancelled duel refunds every bet and does not count for the leaderboard.
{% endhint %}
## Gun Game
Free for all inside a zone. Everyone starts with the first weapon of the ladder and moves up one rung every `killsPerWeapon` kills. The last rung is the finisher: the first player to complete it wins.
### Creating a Gun Game
| Option | Values |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| Ladder length | How many weapons of `ladder` are played, taken from the top of the list. The finisher is always added at the end. |
| Player cap | Optional, 2 or more. Without it the lobby has no limit. |
| Armour | On or off |
| Spectators | On or off |
| Time of day | Day or night |
| Password | Optional |
### Playing
* The match needs 2 players to start (`minPlayers` in `data/modes.lua`).
* The zone is chosen by the server, rotating through the zones of `data/gungame_zones.lua`.
* Players appear at a random point of the zone, protected for `spawnProtectSeconds`. Shooting ends the protection.
* A dead player sees who killed them and respawns after `respawnSeconds`.
* A player who leaves the zone gets a warning and `outOfBoundsSeconds` to come back. After that they are moved back inside. The zone wall becomes visible when a player gets close to the edge.
* New players can join a match that has already started. They begin on the first rung.
* A player who leaves with `/exitduel` leaves alone. The match goes on while 2 players remain; the last one left wins.
## Spectating
The live matches list shows every running match that allows spectators.
* A spectator is moved to the match, watches through the players' camera and returns to where they were when they leave or the match ends.
* ← and → switch player, Backspace leaves.
* A player who is in a match cannot spectate another one.
## Bets
Players can bet cash on either team of a running duel from the live matches list.
* One bet per player and match. The amount is taken when the bet is placed.
* When the duel ends, the whole pool is shared among the players who bet on the winning team, in proportion to their stake.
* A draw or a cancelled duel refunds every bet.
* Stopping the resource refunds every open bet.
Each bettor gets a result screen with the final score and the amount won or refunded.
## Leaderboard
Each game mode has its own leaderboard with wins, losses, kills and deaths per character. It is ordered by wins, then by kills, and shows the first `leaderboard.maxEntries` players.
Only matches that reach their end are counted.
## What a match changes on the player
| While playing | When the match ends |
| ------------------------------------------------- | -------------------------------------------- |
| The player is moved to the match's routing bucket | Back to the main world, at `exitCoords` |
| Weapons in hand are replaced by the match weapon | Match weapons are removed |
| Armour is set by the match rules | The armour the player had before is restored |
| The time of day is frozen at day or night | Time sync is resumed |
| The inventory's weapon handling is paused | Handed back to the inventory |
---
# 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/features.md?ask=&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.