> For the complete documentation index, see [llms.txt](https://visionstore.gitbook.io/visionstore-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://visionstore.gitbook.io/visionstore-docs/scripts/boxing-creator/developers/server-hooks.md).

# Server hooks

Every server hook in open/sv\_hooks.lua, with its arguments and examples.

Edit `open/sv_hooks.lua`. Fill in the functions you need and leave the others empty.

{% hint style="info" %}
**"can..." hooks decide.** Return `false, 'message'` to refuse: the player sees your message through the configured notification system. Return nothing (or `true`) to allow.
{% endhint %}

## Reference

| Hook           | Arguments                       | When                                                |
| -------------- | ------------------------------- | --------------------------------------------------- |
| `canJoin`      | `source, match, corner`         | A player tries to take a corner. Can refuse         |
| `onJoin`       | `source, match, corner`         | A player took a corner                              |
| `canBet`       | `source, match, corner, amount` | A spectator tries to bet. Can refuse                |
| `onBet`        | `source, match, corner, amount` | A bet went through                                  |
| `onMatchStart` | `match`                         | Both ready, purses taken, betting / walk-out begins |
| `onRoundStart` | `match, round`                  | A round's countdown starts                          |
| `onHit`        | `match, hit`                    | A punch counted                                     |
| `onKnockdown`  | `match, corner, knockdowns`     | A fighter went down                                 |
| `onRoundEnd`   | `match, round, cards`           | A round ended and was scored                        |
| `onMatchEnd`   | `match, result`                 | The fight is over                                   |

### `hit`

```lua
hit = {
    attacker = 12, victim = 7,  -- server ids
    corner = 'red',             -- the attacker's corner
    damage = 8.4,               -- ring damage dealt
    heavy = true,               -- power punch?
    combo = 3,                  -- current hit streak
    hp = 91.6,                  -- victim's HP left
    raw = 21,                   -- damage GTA reported
}
```

### `cards`

The three judges' scores for the round: `{ { red = 10, blue = 9 }, { red = 10, blue = 9 }, { red = 10, blue = 10 } }`.

### `result`

```lua
result = {
    kind = 'ko',            -- ko | tko | decision | ringout | towel | forfeit | nocontest
    winner = 'red',         -- 'red' | 'blue' | nil (draw / no contest)
    decision = 'split',     -- decisions only: unanimous | majority | split
                            --   draws: unanimous_draw | majority_draw | split_draw
    reason = nil,           -- extra context, e.g. 'disconnect', 'admin', 'interference'
    round = 3,
    purse = 5000,
    red  = { name, landed, heavy, damage, maxCombo, kd, rating, delta, earned },
    blue = { ... },
}
```

## Examples

{% tabs %}
{% tab title="Job-only fights" %}

```lua
function Hooks.canJoin(source, match, corner)
    local player = Bridge.player(source)
    local job = player and player.PlayerData and player.PlayerData.job
    if not job or job.name ~= 'boxer' then
        return false, 'Only licensed boxers can fight here.'
    end
end
```

{% endtab %}

{% tab title="Require a membership item" %}

```lua
function Hooks.canJoin(source, match, corner)
    if exports.ox_inventory:Search(source, 'count', 'gym_pass') < 1 then
        return false, 'You need a gym pass to fight.'
    end
end
```

{% endtab %}

{% tab title="Winner bonus + item" %}

```lua
function Hooks.onMatchEnd(match, result)
    if result.kind == 'nocontest' or not result.winner then return end
    local winner = match[result.winner]
    Bridge.give(winner.source, 'cash', 250, 'boxing-win-bonus')
    exports.ox_inventory:AddItem(winner.source, 'trophy_small', 1)
    Bridge.notifyText(winner.source, 'Bonus: $250 and a trophy!', 'success')
end
```

{% endtab %}

{% tab title="Cap bets for new players" %}

```lua
function Hooks.canBet(source, match, corner, amount)
    local stats = exports['Chapo_BoxingCreator']:GetPlayerStats(source)
    if stats and stats.wins + stats.losses < 3 and amount > 1000 then
        return false, 'Fight 3 times before betting more than $1,000.'
    end
end
```

{% endtab %}
{% endtabs %}

## Helpers you can use in hooks

| Helper                                             | What it does                                                     |
| -------------------------------------------------- | ---------------------------------------------------------------- |
| `Bridge.notifyText(source, text, kind)`            | Show a message (`'inform'`, `'success'`, `'error'`, `'warning'`) |
| `Bridge.give(source, account, amount, reason)`     | Give money (`'cash'` / `'bank'`)                                 |
| `Bridge.take(source, account, amount, reason)`     | Take money. Returns `false` if they can't afford it              |
| `Bridge.player(source)`                            | The framework's player object                                    |
| `Bridge.citizenId(source)` / `Bridge.name(source)` | Character id / name                                              |
| `Bridge.framework`                                 | `'qbx'`, `'qb'`, `'esx'` or `'standalone'`                       |


---

# 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://visionstore.gitbook.io/visionstore-docs/scripts/boxing-creator/developers/server-hooks.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.