Catálogo de Danças

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.

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.

Uma dança

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
`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
`category`	Não	`id` de uma das `categories`. Sem categorias configuradas, o filtro some
`origin`	Não	`"exclusive"` ou `"gta"`. Veja 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
`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

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:

{
    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:

{
    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:

{
    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: 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

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.

-- 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
`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: mais problemas comuns e como resolver.

Informações Gerais

Scripts

Uma dança

Campos

Origem

Arquivo da dança

Dança local, na `stream/`

Regras dos ids

Miniaturas

Por que minha dança foi recusada?

​Uma dança

​Campos

​Origem

​Arquivo da dança

​Dança local, na stream/

​Regras dos ids

​Miniaturas

​Por que minha dança foi recusada?

Uma dança

Campos

Origem

Arquivo da dança

Dança local, na `stream/`

Regras dos ids

Miniaturas

Por que minha dança foi recusada?