Hooks

Os hooks são funções chamadas pelo script em momentos específicos. Eles existem para integrar o dk_dances com o resto do servidor sem alterar o core. Ficam em config/client/hooks.lua e config/server/hooks.lua, e todos rodam sob pcall: um erro dentro de um hook aparece no console, mas nunca derruba o recurso.

Os hooks que começam com onBefore cancelam a ação quando retornam exatamente false. Retornar nil ou esquecer o return não cancela. Mas atenção: um erro dentro de um onBefore também nega a ação. É a escolha segura, mas significa que um hook com bug bloqueia as danças.

A tabela `dance`

Os hooks recebem a dança do catálogo:

Campo	Conteúdo
`id`	Identificador da dança
`label`	Nome mostrado ao jogador
`category`	`id` da categoria, ou `nil`
`origin`	`"gta"` ou `"exclusive"`
`dict`, `clip`	Dicionário e clipe. `nil` em uma ação
`loop`, `upperBody`, `movable`	Os valores da dança
`duration`	Segundos, ou `nil`

Para decidir, use id, category e origin. Nos hooks do client, o dict de uma dança exclusiva já baixada leva o número do restart no nome (veja Carregamento remoto). No server, o dict é o do catálogo.

Client

Arquivo: config/client/hooks.lua

Hook	Quando dispara	Retorno
`onReady()`	As danças já podem ser tocadas: depois que o servidor libera o download das exclusivas, ou ao iniciar quando `remote.enabled` é `false`
`onBeforePlay(dance)`	Antes de tocar	`false` cancela
`onPlay(dance)`	A dança começou
`onStop(dance)`	A dança terminou
`onOpenUi()`	Antes de abrir o menu ou a barra de atalhos	`false` cancela
`onBeforePreview(dance)`	Antes de abrir a prévia	`false` cancela

A prévia só mostra a animação: quem decide se o jogador pode dançar é o onBeforePlay do servidor.

Bloquear dançar algemado

Casos comuns para o client: jogador algemado, em combate, ferido ou com outra interface aberta.

onBeforePlay = function(dance)
    if IsPedCuffed(PlayerPedId()) then
        return false
    end

    return true
end,

onOpenUi = function()
    if IsPedInMeleeCombat(PlayerPedId()) then
        return false
    end

    return true
end,

Server

Arquivo: config/server/hooks.lua

Hook	Quando dispara	Retorno
`onBeforePlay(src, dance)`	Antes de aprovar a dança	`false` cancela (ex.: VIP)
`onPlay(src, dance)`	A dança começou
`onStop(src, dance)`	A dança terminou (veja abaixo)
`onBeforeShare(src, target, dance)`	Antes de enviar o convite de compartilhar ao jogador mais próximo (`target`)	`false` cancela
`onShare(src, target, dance)`	O jogador aceitou o convite

O onStop roda ao parar, ao trocar de dança, quando uma dança injetada é removida e quando o jogador sai do servidor dançando.

Dança exclusiva só para VIP

onBeforePlay = function(src, dance)
    if dance.category == "vip" then
        return exports["meu_script"]:isVip(src)
    end

    return true
end,

Registrar quem dançou o quê

onPlay = function(src, dance)
    print(("%d começou %s"):format(src, dance.id))
end,

Client ou server?

Client: bloqueio por algemas ou combate, integração com outras interfaces e qualquer coisa que dependa do estado local do personagem
Server: regras de negócio, VIP, permissões, registro e qualquer coisa que não pode depender do client

Regra de decisão: se o hook precisa impedir alguma coisa de verdade, coloque a lógica no servidor. Um hook de client protege contra acidente, não contra má-fé.

Veja também Exports: as funções que outros scripts podem chamar no dk_dances.

Informações Gerais

Scripts

A tabela `dance`

Client

Bloquear dançar algemado

Bloquear o menu em combate

Server

Dança exclusiva só para VIP

Registrar quem dançou o quê

Client ou server?

​A tabela dance

​Client

​Bloquear dançar algemado

​Bloquear o menu em combate

​Server

​Dança exclusiva só para VIP

​Registrar quem dançou o quê

​Client ou server?

A tabela `dance`

Client

Bloquear dançar algemado

Bloquear o menu em combate

Server

Dança exclusiva só para VIP

Registrar quem dançou o quê

Client ou server?