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

# Exports & events

Public API of Cuxial PvP: exports to open the menu and state to know who is in a match.

Open the menu from your own resources and find out whether a player is fighting or spectating. Cuxial PvP has two client exports and two player state values; it exposes no server exports.

## Client exports

### toggleUI

Opens or closes the menu. The call is ignored while the player is in a match.

```lua
exports.CuxiaPvP:toggleUI(toggle)
```

| Parameter | Type    | Description                               |
| --------- | ------- | ----------------------------------------- |
| `toggle`  | boolean | `true` opens the menu, `false` closes it. |

**Returns:** nothing.

```lua
-- Open the menu with your own command
RegisterCommand('arena', function()
    exports.CuxiaPvP:toggleUI(true)
end, false)
```

### isPlaying

Tells whether the local player is in a match.

```lua
local playing = exports.CuxiaPvP:isPlaying()
```

**Returns:** `boolean`. `true` from the moment the match loads until it ends.

```lua
-- Skip your own death screen during a match
if exports.CuxiaPvP:isPlaying() then return end
```

## Player state

Both values are replicated, so they can be read on the client and on the server. Treat them as read only.

| State             | Type          | Value                                                                |
| ----------------- | ------------- | -------------------------------------------------------------------- |
| `inDuel`          | number \| nil | Id of the match the player is fighting in. `nil` outside a match.    |
| `spectatingMatch` | number \| nil | Id of the match the player is spectating. `nil` when not spectating. |

The id of a match is also the routing bucket it runs in.

{% tabs %}
{% tab title="Client" %}

```lua
if LocalPlayer.state.inDuel then
    -- the local player is in a match
end
```

{% endtab %}

{% tab title="Server" %}

```lua
local state = Player(source).state

if state.inDuel or state.spectatingMatch then
    -- the player is inside a match instance
end
```

{% endtab %}
{% endtabs %}

To react when a player enters or leaves a match:

```lua
AddStateBagChangeHandler('inDuel', nil, function(bagName, _, value)
    local player = GetPlayerFromStateBagName(bagName)
    if player == 0 then return end

    if value then
        -- entered the match with id `value`
    else
        -- left the match
    end
end)
```

## Events Cuxial PvP triggers on other scripts

These are client events sent to the scripts chosen in `data/config.lua`.

| Event                         | When                                                                    | Set in          |
| ----------------------------- | ----------------------------------------------------------------------- | --------------- |
| Each event of `revive.events` | After every duel round, on every Gun Game respawn and when a match ends | `revive`        |
| `av_weather:freeze`           | When a match starts and ends, with `weatherSystem = 'av'`               | `weatherSystem` |
| `cd_easytime:PauseSync`       | When a match starts and ends, with `weatherSystem = 'cd'`               | `weatherSystem` |

The revive events are triggered with no arguments. To plug in a script that needs something else, add your own event to `revive.events` and handle it:

```lua
AddEventHandler('myserver:pvpRevive', function()
    -- revive the local player with your own ambulance script
end)
```


---

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