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

# Carregamento Remoto e Sincronia

> De onde vêm os arquivos das danças exclusivas, como funciona o download sob demanda e como os jogadores veem a dança uns dos outros

As danças exclusivas da DK são arquivos `.ycd` que ficam nos servidores da DK e são **baixados durante o jogo**. Esta página explica quando o download acontece, como evitá-lo e como o jogador vê a dança de quem está perto.

## Carregamento remoto

```lua theme={null}
-- config/shared/config.lua
remote = {
    enabled = true,
    sync = true,
    syncRadius = 150.0,
},
```

| Opção | Padrão | O que faz |
| - | - | - |
| `enabled` | `true` | Os `.ycd` vêm dos servidores da DK. `false` desliga o download para **todas** as danças |
| `sync` | `true` | Liga a [sincronia entre jogadores](#sincronia-entre-jogadores) |
| `syncRadius` | `150.0` | Distância, em metros, em que a sincronia vale (aceita `1` a `150`) |

Os arquivos são baixados **sob demanda**: quando o jogador toca a dança pela primeira vez, ou quando vê alguém dançando uma dança que ainda não tem.

### Sem baixar nada

**Todas as danças**

`remote.enabled = false` em `config/shared/config.lua`. Nenhuma dança é baixada e o serviço de animações **não é consultado**.

**Só algumas**

`remote = false` na própria dança. As outras continuam baixando.

```lua theme={null}
{
    id = "meu-samba",
    label = "Meu Samba",
    dict = "meupack@samba",
    clip = "samba_1",
    remote = false,
},
```

Nos dois casos o `.ycd` fica na pasta **`stream/`** deste recurso. Crie a pasta ao lado do `fxmanifest.lua`, com o nome que a dança usa em `file` ou, sem ele, o `dict` mais `.ycd`:

```
dk_dances/
├── stream/
│   └── dk@passinho_i_love_u_funk.ycd    # dict = "dk@passinho_i_love_u_funk"
└── fxmanifest.lua
```

> [!WARNING]
>
> **Os arquivos em `stream/` deixam de ter a proteção do carregamento remoto**: quem tem acesso ao servidor tem os `.ycd`.

* A **licença continua sendo exigida**
* Uma dança local continua com o selo **Exclusiva** se tiver `file` ou `origin = "exclusive"`. Sem nenhum dos dois ela aparece como **GTA** no filtro de origem

### Serviço de animações fora do ar

Se o serviço estiver fora do ar ou ainda conectando, o menu **abre normalmente**: as danças do GTA e as da `stream/` funcionam, e uma faixa avisa que as exclusivas estão indisponíveis, com o botão **Tentar de novo**.

### Tempo entre danças

Cada dança remota iniciada faz quem está perto baixar o arquivo, então o servidor segura o ritmo. Em `config/server/config.lua`:

| Opção | Padrão | Vale para |
| - | - | - |
| `remotePlayCooldown` | `5000` ms (aceita `2000` a `30000`) | Início de dança remota (as exclusivas) do mesmo jogador |
| `playCooldown` | `500` ms (aceita `0` a `10000`, `0` desliga) | As demais: GTA base e `stream/` |

O limite maior é o que impede um jogador de fazer os outros baixarem arquivos novos **em rajada**. A prévia não tem essa espera.

## Sincronia entre jogadores

Para ver a dança de outro jogador, o arquivo dela precisa estar baixado **em você também**. Cada jogador baixa só o que está vendo.

Com `remote.sync = true` (padrão):

* O servidor publica, no **state** de cada jogador, qual dança remota ele está dançando. Danças do GTA base e as da `stream/` não entram, porque não têm arquivo
* A cada `watchInterval` ms, cada jogador confere os dançarinos a até `remote.syncRadius` metros. Se um deles dança uma dança remota cujo arquivo você ainda não tem, o arquivo é **baixado na hora**
* Quem está longe não baixa nada até se aproximar, e quem acabou de entrar baixa só o que vê
* Um arquivo baixado vale **até o jogador sair do servidor**: ver a mesma dança de novo não pede nada aos servidores da DK
* Na primeira vez que um jogador vê uma dança que não tinha, o dançarino aparece **parado por alguns segundos** (o tempo do download mais `watchGrace`) e depois passa a dançar

A sincronia depende de **OneSync**: do state dos jogadores e da posição que o servidor confere no pedido de repetição.

### Opções

| Arquivo | Opção | Padrão | O que faz |
| - | - | - | - |
| `config/shared` | `remote.sync` | `true` | Liga a sincronia (server e client) |
| `config/shared` | `remote.syncRadius` | `150.0` | Distância em que a sincronia vale: o jogador baixa as danças de quem está dentro dela e o servidor só aceita o pedido de repetição dentro dela (aceita `1` a `150`) |
| `config/server` | `sync.resyncGap` | `3000` | Milissegundos mínimos entre dois pedidos de repetição para o **mesmo** dançarino |
| `config/client` | `sync.watchInterval` | `500` | De quanto em quanto tempo, em ms, o jogador confere os dançarinos por perto. Aceita `250` ou mais |
| `config/client` | `sync.watchGrace` | `1000` | Milissegundos que um dançarino com arquivo pronto pode ficar parado antes de o jogador pedir a repetição. Aceita `500` ou mais |

Um `watchInterval` menor baixa mais cedo ao se aproximar, com uma conferência um pouco mais frequente.

### Verificar e reparar

O GTA aplica a animação de um dançarino no momento em que ela chega. Quem ainda não tinha o arquivo (ou acabou de chegar perto) vê o dançarino parado, **mesmo depois de baixar**.

Por isso, com o arquivo pronto e o dançarino sem aparecer dançando por `watchGrace` ms, o jogador pede ao servidor que ele **repita a animação**, até 3 pedidos por dançarino e dança.

O servidor só repassa o pedido se o alvo estiver mesmo dançando uma dança remota, no mesmo bucket e a até `remote.syncRadius` metros, e no máximo uma vez por `resyncGap` ms por dançarino. O jogador espera pelo menos 3 s entre dois pedidos para o mesmo dançarino, para não gastar uma tentativa que o servidor recusaria.

### Arquivos que falham ao baixar

Um arquivo que falha (serviço fora, nome errado no catálogo, ausente nos servidores da DK) **não é abandonado**: ele é tentado de novo depois de 2 min, depois 4, 8, 16... com teto de 6 h.

* Uma queda do serviço se recupera em minutos
* Um arquivo realmente quebrado custa um pedido por jogador a cada 6 h
* **Tocar a dança manualmente tenta sempre**

### Reiniciar o recurso sem reabrir o jogo

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 (sem o clipe) e só fechar e abrir o FiveM limpava, o que atingia até quem estava só olhando um dançarino.

Por isso, a cada início do recurso, as danças baixadas ganham um número no nome do arquivo e do dicionário **dentro do jogo** (ex.: `dk@passinho_i_love_u_funk_1700000000`):

* Todos os clientes recebem o mesmo número junto do hash, então o dançarino e quem o vê usam o mesmo nome
* O arquivo nos servidores da DK continua o mesmo, só o nome que o jogo conhece muda
* O dicionário preso do restart anterior fica para trás, sem uso, e o novo nasce limpo
* Os **nomes originais** seguem valendo no catálogo e nas regras de `props`. Nos hooks do client, o `dict` de uma dança exclusiva já traz o número: decida por `id`, `category` ou `origin`

Ao parar, o recurso também para a animação de cada dançarino que o jogador vê e solta os dicionários carregados. Se o jogador observa um dançarino e o dicionário está vazio ou perdido, ele tira da memória e registra o arquivo de novo (no máximo uma vez a cada 30 s por arquivo).

Com `debugMode` ligado em `config/client/config.lua`, o **F8** mostra o que o jogo tinha carregado quando o recurso subiu, o que cada download encontrou e, ao parar, quantos dançarinos foram parados e quantos dicionários soltos.

### Proteção do state

O jogador consegue escrever no próprio state, a não ser que o `server.cfg` tenha:

```cfg theme={null}
set sv_stateBagStrictMode true
```

O servidor já **desfaz** qualquer valor que não tenha publicado, mas com o modo estrito o jogador nem chega a escrevê-lo.

> [!WARNING]
>
> Ative o modo estrito só se os outros scripts do seu servidor **não dependem** de o jogador escrever state.

Veja também [Configurações do Server](https://docs.dkscripts.com.br/scripts/dances/configs/sv-config.md): cooldowns, compartilhar, sincronia e logs.


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