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

# Erros e Soluções

> Guia de solução de problemas comuns do dk_dances

Encontrou um problema? Comece pela mensagem que apareceu na tela ou no console — ela quase sempre está listada abaixo.

> [!NOTE]
>
> **Antes de qualquer coisa:** ligue o `debugMode` do lado afetado.
>
> * `config/client/config.lua` → mensagens no console **F8** do jogador
> * `config/server/config.lua` → mensagens no console do **servidor**
>
> Volte para `false` depois do teste.

## Instalação e autenticação

> **O recurso não inicia e acusa falta de dk\_snippets**
>
> **Problema.** O console reclama do `dk_snippets` ao iniciar o recurso.
>
> **Solução.** O `dk_snippets` é dependência do manifesto.
>
> **1. Confirme o nome da pasta**
>
> Precisa ser exatamente `dk_snippets`.
>
> **2. Confirme o nome da pasta do dances**
>
> A pasta instalada precisa se chamar exatamente `dk_dances` — o nome aparece nos `require`, exports, eventos e caminhos da interface.

> **A mensagem de autenticação não aparece**
>
> **Problema.** O console do servidor não mostra `authenticated` ao iniciar. No lugar aparece uma destas mensagens:
>
> | Mensagem no console | O que significa |
> | - | - |
> | `NOT authenticated » license.lua is missing or invalid` | O `license.lua` foi removido, está vazio ou ainda tem o texto de exemplo `__DK_LICENSE_TOKEN__` |
> | `NOT authenticated » LICENSE DENIED — check the authorized IP / license / product` | A licença foi **recusada**: IP não autorizado, licença expirada ou inválida, ou produto errado |
> | `OOPS! not authenticated this attempt. (backend unavailable?)` | O servidor de licenças não respondeu nessa tentativa |
> | `NOT authenticated » the backend did not confirm the license, retrying every 5 min` | As 3 tentativas do início falharam. O script continua tentando **a cada 5 minutos** |
>
> **Como o script tenta.** No início são **3 tentativas**, com 2 minutos entre elas, e depois uma a cada 5 minutos. Se o servidor de licenças voltar a responder, o script **autentica sozinho**, sem reiniciar nada.
>
> Já no `LICENSE DENIED` o script **para de tentar**: corrija o motivo e reinicie o recurso.
>
> **Soluções**
>
> **1. Verifique o license.lua**
>
> Ele veio junto do produto e precisa continuar na raiz do recurso, sem edição.
>
> **2. Verifique o IP**
>
> Confirme se o IP atual do servidor está cadastrado na licença.
>
> **3. Altere o IP**
>
> Acesse a sala **💻・comandos** no Discord e use o comando para alterar o IP.
>
> **4. Reinicie o recurso**
>
> Depois de corrigir, rode `restart dk_dances` (ou reinicie o servidor).
>
> A licença é exigida até para as danças que ficam na `stream/` do seu servidor.

## Tocando danças

> **Uma faixa avisa que as danças exclusivas estão indisponíveis**
>
> **Problema.** O menu mostra uma faixa: **"Conectando ao servidor de animações"** ou **"Servidor de animações fora do ar"**. Ao tocar uma exclusiva cujo arquivo não chegou a carregar, o jogador recebe **"As danças estão indisponíveis no momento"**.
>
> **Causa.** O serviço de animações da DK ainda está conectando ou está fora do ar.
>
> **Solução**
>
> * Aguarde alguns instantes e use o botão **Tentar de novo** da faixa
> * Confira a autenticação do recurso (seção **Instalação e autenticação**, acima)
> * Acompanhe o [status dos serviços](https://stats.uptimerobot.com/CRPwO1CRkn)
>
> Enquanto isso, as danças do **GTA** e as da **`stream/`** continuam funcionando normalmente.

> **“Você não pode dançar agora”**
>
> **Problema.** Ao tentar dançar, o jogador recebe esse aviso.
>
> **Causas possíveis**
>
> * O jogador está **morto** ou em **ragdoll** (`blockWhen.dead`, `blockWhen.ragdoll`)
> * O hook `onBeforePlay` do **client** ou do **server** retornou `false`
> * Um **erro** dentro de um `onBefore` também nega a ação
>
> **Solução**
>
> **1. Veja os bloqueios**
>
> Confira `blockWhen` em `config/client/config.lua`.
>
> **2. Veja os hooks**
>
> Revise `onBeforePlay` em `config/client/hooks.lua` e em `config/server/hooks.lua`. Retorne `true` no caminho em que a dança deve ser liberada: esquecer o `return` não cancela, mas um erro cancela.
>
> **3. Ligue o debug**
>
> Com `debugMode = true`, o erro de um hook aparece no console.

> **“Você não pode dançar dentro de um veículo / caindo / nadando”**
>
> **Causa.** O bloqueio correspondente de `blockWhen` está ligado e o jogador está na situação.
>
> **Solução**
>
> É o comportamento esperado. O pacote do GTA não traz danças de dentro de veículo. Se quiser liberar uma situação, desligue a opção em `blockWhen` no `config/client/config.lua`.

> **“Aguarde um instante” ou “Aguarde alguns segundos para iniciar outra dança exclusiva”**
>
> **Causa.** O cooldown do servidor entre dois inícios de dança do mesmo jogador.
>
> **Solução.** É proteção contra rajadas de download. Os valores ficam em `config/server/config.lua`:
>
> | Opção | Padrão | Vale para |
> | - | - | - |
> | `playCooldown` | `500` ms | Danças do GTA e da `stream/` |
> | `remotePlayCooldown` | `5000` ms | Danças exclusivas |
>
> A **prévia** não tem essa espera: o jogador pode ver as danças sem aguardar.

> **“Dança não encontrada”**
>
> **Problema.** O jogador recebe esse aviso ao usar `/danca <id>` ou um atalho.
>
> **Causas possíveis**
>
> * O **id** foi digitado errado (a busca do menu mostra o id certo)
> * A dança foi **removida** do catálogo, ou recusada na inicialização
> * A dança era **injetada** por um recurso que parou ou reiniciou
>
> **Solução**
>
> Confira o id no menu, e olhe o console do servidor logo depois do início do recurso para ver se a dança foi recusada.

> **A dança para sozinha**
>
> **Problema.** O jogador começa a dançar e a animação some, para ele e para quem está perto.
>
> **Causas possíveis**
>
> * A tecla de cancelar ações do servidor (por exemplo o <kbd>F6</kbd> do vRP) ou outro script apagou a animação
> * A dança **não é em loop** e o clipe terminou
> * O jogador morreu, caiu, nadou ou entrou em um veículo
>
> **Solução.** Por padrão (`forceReplay = false`), uma animação cancelada de fora **encerra** a dança de verdade. Para uma dança em loop voltar sozinha, ligue `forceReplay = true` em `config/client/config.lua`.
>
> Mesmo com `forceReplay = true`, os bloqueios de `blockWhen` ainda encerram a dança, e se a animação não volta depois de **5 tentativas seguidas** ela também é encerrada.

> **“A animação ficou em estado inválido no seu jogo”**
>
> **Problema.** O aviso pede para fechar e abrir o FiveM para dançar.
>
> **Causa.** O jogo não solta o dicionário de uma dança que estava em uso quando o recurso para: ele fica carregado e vazio. Só fechar e abrir o FiveM limpa.
>
> **Solução**
>
> **1. Feche e abra o FiveM**
>
> Resolve para o jogador.
>
> **2. Se voltar a aparecer, investigue**
>
> Ligue `debugMode` em `config/client/config.lua`. O **F8** mostra o que o jogo tinha carregado quando o recurso subiu e o que cada download encontrou. Leve essa saída ao suporte.
>
> O dk\_dances evita isso nos restarts: a cada início, as danças baixadas ganham um número no nome dentro do jogo, e o dicionário preso do restart anterior fica para trás, sem uso.

> **Uma dança exclusiva fica em “Baixando” ou marca “Falhou”**
>
> **Problema.** O estado da dança no menu não sai de **Baixando**, ou vira **Falhou**.
>
> **Causas possíveis**
>
> * O serviço de animações está fora do ar
> * O **nome do arquivo** no catálogo está errado (`file`, ou o `dict` quando não há `file`)
> * O arquivo não existe nos servidores da DK
> * A licença não foi validada
>
> **Solução**
>
> **1. Confira o nome**
>
> O arquivo é o `file` ou o `dict` mais `.ycd`. `dict = "dk@samba"` baixa `dk@samba.ycd`.
>
> **2. Toque a dança manualmente**
>
> Tocar a dança **sempre tenta** de novo. Sozinho, o script tenta depois de 2 min, 4, 8, 16... com teto de 6 h.
>
> **3. Confira a autenticação**
>
> Veja a seção **Instalação e autenticação**, no início desta página.

## Catálogo e miniaturas

> **A dança que eu cadastrei não aparece no menu**
>
> **Diagnóstico.** Olhe o console do servidor logo depois de iniciar o recurso. Cada entrada recusada vem no formato:
>
> ```
> dances[3] (meu-samba): duplicate id
> ```
>
> **Soluções.** Veja a tabela de motivos em [Catálogo de Danças](https://docs.dkscripts.com.br/scripts/dances/configs/catalog.md). Os mais comuns:
>
> * **`duplicate id`** — o id repete outro (maiúsculas não contam)
> * **`unknown category X`** — a `category` não existe em `categories`
> * **`needs dict and clip, or an onPlay handler`** — falta `dict` ou `clip`
> * **`id must use letters, numbers, _ or - (max 48)`** — id com espaço, acento ou longo demais
>
> Se a dança existe mas o **filtro de categoria** não aparece, é porque não há categorias configuradas. O filtro de **origem** só aparece quando o catálogo tem as duas origens.

> **A miniatura da dança não aparece**
>
> **Problema.** A dança mostra só as iniciais do nome.
>
> **Soluções**
>
> **1. Confira o nome do arquivo**
>
> Precisa ser o `id` da dança, **exatamente**, mais a extensão de `thumbnails.extension`: `meu-samba.webp`.
>
> **2. Confira a pasta**
>
> O padrão é `web/public/previews/`. Se mudou `thumbnails.folder`, a pasta precisa estar no `files` do `fxmanifest.lua`.
>
> **3. Reinicie o recurso**
>
> Não precisa de build, mas precisa de `restart dk_dances`.
>
> As danças do **pacote do GTA** não usam miniatura. Para uma dança com outra extensão, use `preview = "nome.jpg"` nela.

> **O número da dança no menu mudou**
>
> **Causa.** O número é a **posição da dança no catálogo**. O pacote do GTA vem primeiro e as suas danças depois, na ordem de `dances`.
>
> **Solução**
>
> Acrescente a dança nova **no fim** da lista `dances`. O número só muda se você esconder categorias do pacote (`gta.hide`) ou mudar a ordem. O **id** da dança não muda nunca.

> **Uma dança injetada sumiu do menu**
>
> **Causa.** Quando o recurso que registrou a dança **para**, as danças dele saem do menu sozinhas e quem estava dançando uma delas é parado.
>
> **Solução**
>
> O recurso dono precisa **registrar de novo** quando o dk\_dances reinicia. Veja o exemplo com `onResourceStart` em [Injetar Animações](https://docs.dkscripts.com.br/scripts/dances/dev/inject.md).

## Outros jogadores

> **Vejo o outro jogador parado, mas ele está dançando**
>
> **Problema.** Um jogador dança uma dança exclusiva e quem está perto o vê parado.
>
> **Causas possíveis**
>
> * É a **primeira vez** que você vê essa dança: o dançarino aparece parado pelo tempo do download mais `watchGrace`, e depois passa a dançar
> * A sincronia está desligada (`remote.sync = false`)
> * O dançarino está **além** de `remote.syncRadius`
> * O servidor **não** usa OneSync
> * O arquivo falhou ao baixar (veja acima)
>
> **Soluções**
>
> **1. Aguarde alguns segundos**
>
> O reparo é automático: com o arquivo pronto, o jogador pede ao servidor que o dançarino repita a animação, até 3 vezes.
>
> **2. Confira a sincronia**
>
> `remote.sync = true` em `config/shared/config.lua`, e OneSync ativo.
>
> **3. Ajuste a distância ou o intervalo**
>
> `remote.syncRadius` aceita até 150 m. `sync.watchGrace` em `config/client/config.lua` define quanto o dançarino espera antes do pedido.
>
> Danças do **GTA** e as da **`stream/`** não têm esse atraso: não há arquivo para baixar.

> **O objeto da dança só aparece para mim**
>
> **Causa.** Com `networked = true` os outros jogadores veem o objeto, mas isso precisa de **OneSync** e de um servidor que deixe o client criar entidades. Se o servidor recusar, o objeto aparece só para você.
>
> **Solução**
>
> * Ative o OneSync
> * Ponha o `sv_entityLockdown` em um valor diferente de `strict` no `server.cfg`
> * Confira `networked = true` em `config/client/props.lua`
>
> A **prévia** nunca mostra o objeto para os outros: o clone só existe na sua tela.

> **O objeto da dança não aparece**
>
> **Causas possíveis**
>
> * `enabled = false` em `config/client/props.lua`
> * Nenhuma `rule` bate com a dança
> * O **modelo** não existe na build do servidor: nesse caso o objeto é ignorado e a dança toca sem ele
> * Uma regra anterior com `props = {}` tirou o objeto
>
> **Solução**
>
> Lembre que vale a **primeira regra que bater**. Ligue o `debugMode`: o F8 avisa de modelo indisponível e de objeto desconhecido. Veja [Objetos nas Danças](https://docs.dkscripts.com.br/scripts/dances/configs/props.md).

> **O compartilhar não funciona**
>
> **Avisos e causas**
>
> | Aviso | Causa |
> | - | - |
> | **"Não há ninguém por perto para receber a dança"** | Ninguém dentro de `share.radius`, no mesmo routing bucket e autenticado |
> | **"Você já tem um convite aguardando resposta"** | Quem compartilha só pode ter um convite por vez |
> | **"Aguarde alguns segundos para compartilhar de novo"** | O `share.cooldown` do servidor ainda não passou |
> | **"Você não pode compartilhar agora"** | O hook `onBeforeShare` do servidor negou o convite (ou deu erro) |
>
> Quem já recebeu um convite não recebe outro até responder. Se a dança não existe na build de quem recebe, o menu dele abre normal, sem seleção.

## ⌨️ Teclas e interface

> **A tecla do menu não abre nada**
>
> **Causas possíveis**
>
> * O jogador **já tinha um bind salvo** para essa ação: o FiveM guarda a tecla no perfil dele, e mudar `openKey` no config afeta só quem ainda não tem bind
> * Outro script usa a mesma tecla
> * O hook `onOpenUi` do client retornou `false`
>
> **Solução**
>
> O jogador pode remapear em **Configurações → Atalhos** do FiveM. Teste também pelo comando `/dancas`: se ele abre e a tecla não, o problema é o bind.

> **A barra de atalhos não abre**
>
> **Causas possíveis**
>
> * `shortcuts.enabled = false`
> * Chamada pelo export `openShortcuts` com o **menu já aberto**: o export devolve `false` (com o menu aberto, a barra já aparece colada embaixo dele)
> * O hook `onOpenUi` do client negou
>
> **Solução**
>
> Confira `shortcuts.enabled` em `config/client/config.lua` e os hooks. O `commands.shortcuts` vazio desliga só o comando, não a tecla.

> **A prévia não abre**
>
> **Avisos e causas**
>
> | Aviso | Causa |
> | - | - |
> | **"Não há espaço aqui para a prévia"** | Parede entre o jogador e o clone, ou câmera colada demais (`checkSpace`, `cameraDistance`) |
> | **"Pare de dançar para ver a prévia"** | O jogador está dançando. A prévia só funciona com ele parado |
>
> Outras causas: `preview.enabled = false` ou o hook `onBeforePreview` do client negou. Se o arquivo da dança ainda está baixando, a prévia **espera o download**.
>
> Em um corredor estreito ou com parede atrás do jogador, tente `checkSpace = false` ou uma `cameraDistance` menor.

> **A cor da interface não mudou**
>
> **Solução**
>
> **1. Confira o arquivo**
>
> O arquivo é `web/build/theme.css`, e os valores são `R, G, B` separados por vírgula (`201, 240, 58`), sem `rgb()` nem `#`.
>
> **2. Reinicie o recurso**
>
> Rode `restart dk_dances` e abra o menu de novo.

> **[Precisa de ajuda?](https://dkscripts.com.br/discord)**
>
> Abra um ticket no nosso Discord para suporte técnico. Leve a mensagem do console e o que estava no `debugMode`.


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