> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dkscripts.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks

> Bloqueie danças, restrinja por VIP e reaja a início, fim e compartilhamento sem alterar o core do script

Os hooks são funções chamadas pelo script em momentos específicos. Eles existem para integrar o dk\_dances com o resto do servidor **sem alterar o core**.

Ficam em `config/client/hooks.lua` e `config/server/hooks.lua`, e todos rodam sob `pcall`: um erro dentro de um hook aparece no console, mas **nunca derruba o recurso**.

> [!WARNING]
>
> Os hooks que começam com `onBefore` **cancelam a ação** quando retornam exatamente `false`. Retornar `nil` ou esquecer o `return` não cancela. Mas atenção: um **erro** dentro de um `onBefore` também **nega** a ação. É a escolha segura, mas significa que um hook com bug bloqueia as danças.

## A tabela `dance`

Os hooks recebem a dança do catálogo:

| Campo | Conteúdo |
| - | - |
| `id` | Identificador da dança |
| `label` | Nome mostrado ao jogador |
| `category` | `id` da categoria, ou `nil` |
| `origin` | `"gta"` ou `"exclusive"` |
| `dict`, `clip` | Dicionário e clipe. `nil` em uma ação |
| `loop`, `upperBody`, `movable` | Os valores da dança |
| `duration` | Segundos, ou `nil` |

Para decidir, use `id`, `category` e `origin`. Nos hooks do **client**, o `dict` de uma dança exclusiva já baixada leva o **número do restart** no nome (veja [Carregamento remoto](https://docs.dkscripts.com.br/scripts/dances/configs/remote-sync.md#reiniciar-o-recurso-sem-reabrir-o-jogo)). No **server**, o `dict` é o do catálogo.

## Client

Arquivo: `config/client/hooks.lua`

| Hook | Quando dispara | Retorno |
| - | - | - |
| `onReady()` | As danças já podem ser tocadas: depois que o servidor libera o download das exclusivas, ou ao iniciar quando `remote.enabled` é `false` | |
| `onBeforePlay(dance)` | Antes de tocar | `false` cancela |
| `onPlay(dance)` | A dança começou | |
| `onStop(dance)` | A dança terminou | |
| `onOpenUi()` | Antes de abrir o menu ou a barra de atalhos | `false` cancela |
| `onBeforePreview(dance)` | Antes de abrir a prévia | `false` cancela |

A prévia só mostra a animação: quem decide se o jogador **pode dançar** é o `onBeforePlay` do servidor.

### Bloquear dançar algemado

Casos comuns para o client: jogador algemado, em combate, ferido ou com outra interface aberta.

```lua theme={null}
onBeforePlay = function(dance)
    if IsPedCuffed(PlayerPedId()) then
        return false
    end

    return true
end,
```

### Bloquear o menu em combate

```lua theme={null}
onOpenUi = function()
    if IsPedInMeleeCombat(PlayerPedId()) then
        return false
    end

    return true
end,
```

## Server

Arquivo: `config/server/hooks.lua`

| Hook | Quando dispara | Retorno |
| - | - | - |
| `onBeforePlay(src, dance)` | Antes de aprovar a dança | `false` cancela (ex.: VIP) |
| `onPlay(src, dance)` | A dança começou | |
| `onStop(src, dance)` | A dança terminou (veja abaixo) | |
| `onBeforeShare(src, target, dance)` | Antes de enviar o convite de compartilhar ao jogador mais próximo (`target`) | `false` cancela |
| `onShare(src, target, dance)` | O jogador aceitou o convite | |

O `onStop` roda ao parar, ao **trocar de dança**, quando uma dança injetada é **removida** e quando o jogador **sai do servidor dançando**.

### Dança exclusiva só para VIP

```lua theme={null}
onBeforePlay = function(src, dance)
    if dance.category == "vip" then
        return exports["meu_script"]:isVip(src)
    end

    return true
end,
```

### Registrar quem dançou o quê

```lua theme={null}
onPlay = function(src, dance)
    print(("%d começou %s"):format(src, dance.id))
end,
```

## Client ou server?

* **Client**: bloqueio por algemas ou combate, integração com outras interfaces e qualquer coisa que dependa do estado local do personagem
* **Server**: regras de negócio, VIP, permissões, registro e qualquer coisa que **não pode** depender do client

> [!WARNING]
>
> Regra de decisão: se o hook precisa **impedir alguma coisa de verdade**, coloque a lógica no servidor. Um hook de client protege contra acidente, não contra má-fé.

Veja também [Exports](https://docs.dkscripts.com.br/scripts/dances/dev/exports.md): as funções que outros scripts podem chamar no dk\_dances.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.