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

# Catálogo de Danças

> Como cadastrar uma dança: campos, regras dos ids, origem, miniaturas e o que o servidor recusa na inicialização

O catálogo é a lista `dances` do `config/shared/config.lua`. É onde você cadastra as danças **suas**: as exclusivas da DK, as que ficam na `stream/` do servidor e as que só chamam outro script.

> [!NOTE]
>
> Animações de **outros recursos** não precisam ser copiadas para cá: elas entram pelo `config/server/inject.lua` ou pelo export `registerDance`. Veja [Injetar animações](https://docs.dkscripts.com.br/scripts/dances/dev/inject.md).

## Uma dança

```lua theme={null}
dances = {
    {
        id = "passinho_i_love_u_funk",
        label = "Passinho I LOVE U FUNK",
        category = "solo",
        dict = "dk@passinho_i_love_u_funk",
        clip = "danca",
        remote = true,
        loop = true,
        upperBody = false,
        movable = false,
        duration = 8,
    },
},
```

### Campos

| Campo | Obrigatório | O que faz |
| - | - | - |
| `id` | Sim | Identificador único. Veja as [regras dos ids](#regras-dos-ids) |
| `label` | Sim | Nome mostrado ao jogador |
| `dict` e `clip` | Os dois, ou nenhum | Dicionário de animação e o clipe dentro dele. Sem os dois, a dança é uma **ação** que só chama outro script. Veja [Danças que chamam outro script](https://docs.dkscripts.com.br/scripts/dances/dev/actions.md) |
| `category` | Não | `id` de uma das `categories`. Sem categorias configuradas, o filtro some |
| `origin` | Não | `"exclusive"` ou `"gta"`. Veja [Origem](#origem) |
| `file` | Não | Nome do `.ycd`. Sem ele, é o `dict` mais `.ycd` |
| `remote` | Não | `false` = o `.ycd` está na `stream/` deste recurso e a dança não baixa nada. Padrão `true` |
| `loop` | Não | Repete até o jogador parar |
| `upperBody` | Não | Anima só a parte de cima do corpo |
| `movable` | Não | Permite andar enquanto dança |
| `duration` | Não | Duração em segundos, **só para exibir** |
| `preview` | Não | Nome de um arquivo da pasta de miniaturas, ou `false` para ficar sem imagem. Veja [Miniaturas](#miniaturas) |
| `onPlay` / `onStop` | Só em ações | O que chamar quando a dança começa e quando para. Veja [Danças que chamam outro script](https://docs.dkscripts.com.br/scripts/dances/dev/actions.md) |

`loop`, `upperBody` e `movable` ficam `false` quando omitidos. Uma dança **sem `loop`** termina quando o clipe acaba, e o jogador volta ao normal.

### Origem

A origem define o **selo** e o **filtro Origem** do menu.

| `origin` | Significado |
| - | - |
| `"exclusive"` | Dança feita pela DK. Ganha o selo **Exclusiva** |
| `"gta"` | Animação do jogo base |

Sem `origin`, a dança é `exclusive` quando tem `file` ou é remota. Uma dança local sem `file` e sem `origin` aparece como **GTA**.

O filtro de origem e os selos só aparecem quando o catálogo tem as **duas origens**. Com o pacote do GTA ligado, eles aparecem sempre.

### Arquivo da dança

Uma dança remota baixa o `.ycd` dos servidores da DK. O nome do arquivo é o `file` ou, sem ele, o `dict` mais `.ycd`:

```lua theme={null}
{
    id = "samba",
    label = "Samba",
    dict = "dk@samba",
    clip = "samba_1",
},
```

Esta dança baixa `dk@samba.ycd`. Só ponha `file` quando o arquivo tiver **outro nome** que o dicionário:

```lua theme={null}
{
    id = "samba-lenta",
    label = "Samba lento",
    dict = "dk@samba",
    clip = "samba_2",
    file = "dk@dance@samba_pack.ycd",
},
```

O nome precisa terminar em `.ycd` e usar só letras, números, `_`, `@`, `.` e `-`.

### Dança local, na `stream/`

Com `remote = false` o `.ycd` fica na pasta `stream/` deste recurso e a dança não baixa nada:

```lua theme={null}
{
    id = "meu-samba",
    label = "Meu Samba",
    category = "party",
    origin = "exclusive",
    dict = "meupack@samba",
    clip = "samba_1",
    remote = false,
    loop = true,
},
```

Veja também [Carregamento remoto e sincronia](https://docs.dkscripts.com.br/scripts/dances/configs/remote-sync.md): os dois modos, a `stream/` e o que muda na proteção dos arquivos.

## Regras dos ids

O `id` é o nome da dança **para sempre**: ele vai nas favoritas dos jogadores, nos hooks (`dance.id`), nos logs e, se você guardar danças num banco de dados, nas tabelas.

* Cada dança tem um id **único**, **sem diferenciar maiúsculas de minúsculas**: `Samba` e `samba` são o mesmo id e o segundo é recusado
* Só **letras, números, `_` e `-`**, até **48 caracteres**
* O id **não depende da posição** da dança na lista. Tirar uma dança não muda o id de nenhuma outra, então não gere ids pela posição

> [!WARNING]
>
> **Nunca mude o id de uma dança que já está em uso** e nunca dê o id de uma dança removida a outra animação. As favoritas e os registros antigos passariam a apontar para a dança errada.

Os ids do pacote do GTA começam com `gta-` e **não mudam entre versões** do recurso. Esse prefixo é reservado a ele: uma dança **injetada** não pode usá-lo. Uma dança sua em `dances` com o mesmo id de uma do pacote **vence** a do pacote.

## Miniaturas

Cada dança usa a imagem `<pasta>/<id>.<extensão>`. Para a dança `meu-samba`, basta soltar `meu-samba.webp` em `web/public/previews/`. A pasta é lida direto pelo jogo, **sem build**: salve o arquivo e rode `restart dk_dances`.

```lua theme={null}
-- config/shared/config.lua
thumbnails = {
    folder = "web/public/previews",
    extension = "webp",
},
```

| Opção | Padrão | O que faz |
| - | - | - |
| `folder` | `"web/public/previews"` | Pasta dentro do recurso |
| `extension` | `"webp"` | Extensão do arquivo padrão. Todas as imagens usam a mesma |

* O nome do arquivo é o `id` da dança, **exatamente**
* Imagem **quadrada**: a lista mostra a 44×44 px e recorta o centro, então **96×96** é suficiente. WebP costuma pesar menos que PNG
* Dança **sem arquivo** aparece com as **iniciais** do nome
* As danças do pacote do GTA **não usam** miniatura
* Para uma dança com outra extensão ou outro nome, use `preview = "nome.jpg"` nela. `preview = false` deixa a dança sem imagem
* `thumbnails.folder` pode apontar para outra pasta do recurso, desde que esteja no `files` do `fxmanifest.lua`. Um caminho com `..` volta para a pasta padrão

## Por que minha dança foi recusada?

Entradas inválidas são **ignoradas**, e o motivo aparece no console do servidor ao iniciar, no formato `dances[3] (meu-samba): motivo`. As demais danças seguem normalmente.

| Motivo no console | O que fazer |
| - | - |
| `id must be a non-empty string` / `label must be...` | Preencha o `id` e o `label` |
| `needs dict and clip, or an onPlay handler` | Informe `dict` e `clip`, ou um `onPlay` se for uma ação |
| `dict must be...` / `clip must be...` | Informe os dois, não só um |
| `id must use letters, numbers, _ or - (max 48)` | Corrija o id conforme as [regras](#regras-dos-ids) |
| `duplicate id` | Outro id igual (sem diferenciar maiúsculas) já está no catálogo |
| `unknown category X` | A `category` não existe em `categories` |
| `origin must be gta or exclusive` | Use um dos dois valores |
| `remote dance needs a file like name.ycd...` | O `file` (ou o `dict` mais `.ycd`) não é um nome de arquivo `.ycd` válido |
| `duration must be a positive number` | Use um número maior que zero |
| `preview must be false or a file name like image.webp` | Use `false` ou só o nome do arquivo |
| `onPlay needs exactly one of event or export` | Cada parte tem um `event` **ou** um `export`, nunca os dois |

Veja também [Erros e Soluções](https://docs.dkscripts.com.br/scripts/dances/errors.md): mais problemas comuns e como resolver.


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