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

# Injetar Animações

> Coloque no menu as animações de outro recurso, de uma lista antiga ou de um menu que você está trocando, sem reescrever o catálogo

Animações suas — de outro recurso, de uma lista antiga, de um menu que você está trocando — entram no menu do dk\_dances por **duas portas**, que fazem a mesma coisa.

> **config/server/inject.lua**
>
> Arquivo seu **dentro do dk\_dances**. Roda no servidor quando o recurso inicia.

> **Exports do servidor**
>
> Para outro recurso seu registrar as danças dele: `registerDance` e `unregisterDance`.

## O arquivo `inject.lua`

Ele roda no servidor **uma vez**, quando o dk\_dances inicia, e recebe `inject`:

| Função | O que faz |
| - | - |
| `inject.registerDance(dance)` | Põe **uma** dança no menu. Devolve `true`, ou `false` e o motivo (o motivo também aparece no console) |
| `inject.unregisterDance(id)` | Tira do menu uma dança que este arquivo pôs |

O arquivo vem **sem nada ativo** e com exemplos comentados. Para várias danças, use um loop.

### Uma dança

```lua theme={null}
return function(inject)
    inject.registerDance({
        id = "meupack-samba",
        label = "Samba do Zé",
        dict = "meupack@samba",
        clip = "samba_1",
        category = "party",
        origin = "exclusive",
        loop = true,
        duration = 12,
    })
end
```

### Uma lista, com loop

Cada dança tem o id escrito por você.

```lua theme={null}
return function(inject)
    local dances = {
        {
            id = "meupack-forro",
            label = "Forró",
            dict = "meupack@forro",
            clip = "forro_1",
        },
        {
            id = "meupack-axe",
            label = "Axé",
            dict = "meupack@axe",
            clip = "axe_1",
            movable = true,
        },
    }

    for _, dance in ipairs(dances) do
        dance.origin = "exclusive"
        inject.registerDance(dance)
    end
end
```

### Convertendo a lista de outro menu

Aqui cada item é `{ id, nome, dicionário, clipe, flag da animação }`. A flag é a do `TaskPlayAnim`: `1` repete, `16` anima só o corpo de cima, `32` deixa andar.

```lua theme={null}
return function(inject)
    local animations = {
        { "antigo-bolero", "Bolero", "antigo@bolero", "bolero_1", 1 },
        { "antigo-lambada", "Lambada", "antigo@lambada", "lambada_1", 49 },
    }

    for _, animation in ipairs(animations) do
        inject.registerDance({
            id = animation[1],
            label = animation[2],
            dict = animation[3],
            clip = animation[4],
            loop = animation[5] & 1 == 1,
            upperBody = animation[5] & 16 == 16,
            movable = animation[5] & 32 == 32,
        })
    end
end
```

Mantenha os **ids antigos** na conversão (`antigo-bolero`). Se o seu servidor guardava as animações favoritas dos jogadores por esses ids em algum banco, eles continuam apontando para a dança certa.

## Registrando por outro recurso

No `server.lua` do outro recurso, pelo export. O dk\_dances precisa estar iniciado, e é preciso **registrar de novo quando ele reinicia**, por isso o evento abaixo.

```lua theme={null}
local function injectDances()
    for _, dance in ipairs(Config.dances) do
        local ok, problem = exports.dk_dances:registerDance(dance)

        if not ok then
            print(("dk_dances recusou %s: %s"):format(dance.id, problem))
        end
    end
end

AddEventHandler("onResourceStart", function(resourceName)
    if resourceName == "dk_dances" then
        injectDances()
    end
end)

if GetResourceState("dk_dances") == "started" then
    injectDances()
end
```

Para tirar uma dança antes de o recurso parar:

```lua theme={null}
exports.dk_dances:unregisterDance("meupack-samba")
```

## Campos aceitos

São os de `dances` em `config/shared/config.lua`:

`id`, `label`, `dict`, `clip`, `category`, `origin`, `loop`, `upperBody`, `movable`, `duration`, `preview`, `onPlay` e `onStop`.

Com estas diferenças:

| Campo | Diferença na dança injetada |
| - | - |
| `file` e `remote` | **Ignorados.** A dança injetada é sempre local, com o `.ycd` na `stream/` de algum recurso do servidor, e nunca passa pelos servidores da DK |
| `category` | Se usada, precisa existir em `categories` |
| `origin` | Sem ele, a dança aparece como **GTA** no filtro de origem. Use `origin = "exclusive"` para o selo **Exclusiva** |
| `id` | Segue as [regras dos ids](https://docs.dkscripts.com.br/scripts/dances/configs/catalog.md#regras-dos-ids). Ids com o prefixo `gta-` são do pacote do jogo base e **não valem aqui** |

## Regras

* **Id repetido, id do pacote do GTA ou id fora das regras** são recusados, e o motivo vem no retorno e no console
* **O dono da dança é o recurso que a registrou.** Só ele a remove, e só ele a registra de novo com o mesmo id (a nova versão troca a antiga **no mesmo lugar**). Outro recurso não toma o id
* Quando o recurso dono **para**, as danças dele saem do menu sozinhas e quem estava dançando uma delas é parado. Quando ele inicia de novo, registra outra vez
* Os jogadores recebem as danças novas **em lote** (um evento só para uma sequência de registros), e quem entra depois pede o que já foi injetado
* Valem os mesmos hooks do servidor (`onBeforePlay` etc.), o `playCooldown` e os [objetos](https://docs.dkscripts.com.br/scripts/dances/configs/props.md) de qualquer dança local
* Só o **servidor** injeta. O client não tem export de registro
* A categoria de log `inject` (em `config/server/logs.lua`) registra cada dança registrada ou removida

> [!WARNING]
>
> O `.ycd` das danças injetadas precisa estar na `stream/` de algum recurso do servidor. O dk\_dances **não** baixa arquivos para elas.

Veja também [Danças que chamam outro script](https://docs.dkscripts.com.br/scripts/dances/dev/actions.md): uma entrada do menu que, em vez de tocar uma animação, chama um evento ou export de outro script.


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