scully_emotemenu — Manual

Menu de animações para FiveM com emotes, danças, cenários, expressões faciais, estilos de caminhada, emotes com props, emotes sincronizados entre dois jogadores e efeitos de partícula. Standalone, com camada de compatibilidade opcional para QBCore.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Comandos
5. Teclas
6. Categorias de animação
7. Estrutura de uma animação
8. Emotes customizados
9. Binds de emote
10. Emotes sincronizados
11. Prop dump
12. Integrações
13. Entrypoints para outros recursos
14. Localização
15. Estrutura de arquivos

Dependências

Não usa framework, banco de dados nem ACE. Funciona standalone.

Instalação

1. Copie a pasta scully_emotemenu para resources/.
2. Adicione ao server.cfg:

   ensure scully_emotemenu
3. A pasta stream/ já traz as animações e props customizados; os .ytyp são declarados no fxmanifest.lua e carregam sozinhos.
4. Ajuste o idioma e as teclas em config.lua.
5. Conflitos — não rode junto com outro menu de emotes (rpemotes, dpemotes, qb-smallresources com emotes). Os comandos /e, /emote e /w colidem, e dois recursos disputando TaskPlayAnim no mesmo ped brigam entre si.

No boot, o servidor consulta o GitHub do autor e avisa no console se a versão instalada (1.9.9f) está desatualizada.

Configuração

Tudo fica em config.lua.

As três flags EnableNSFWEmotes, EnableGangEmotes e EnableSocialMovementEmotes removem a animação da lista inteira quando desligadas — ela some do menu, dos comandos e do radial. As flags EnableConsumableEmotes, EnableSynchronizedEmotes e EnableAnimalEmotes apenas escondem a categoria do menu; os comandos continuam funcionando.

Comandos

Todos os comandos são de client, sem restrição de permissão.

Os nomes dos comandos vêm de EmotePlayCommands, WalkSetCommands e MenuOpenCommands — renomeie no config se quiser outros.

Teclas

Todas as teclas são remapeáveis pelo jogador em Configurações > Controles > FiveM.

Categorias de animação

Cada categoria é um arquivo em data/animations/.

Cada arquivo tem um par _pt-br.lua com os comandos e rótulos traduzidos — ver Localização.

Estrutura de uma animação

{
    Label = 'Adjust Tie',        -- nome exibido no menu
    Command = 'adjusttie',       -- comando usado em /e adjusttie
    Animation = 'try_tie_positive_a',
    Dictionary = 'clothingtie',
    Options = {
        Duration = 5000,
        Flags = {
            Move = true,
        },
    },
}

Campos de topo

Options

Emotes customizados

O arquivo custom_emotes.lua existe para você adicionar animações sem tocar nos arquivos de data/animations/, que são sobrescritos a cada atualização do recurso.

return {
    Walks = {},
    Scenarios = {},
    Expressions = {},
    Emotes = {
        {
            Label = 'Meu Emote',
            Command = 'meuemote',
            Animation = 'idle_a',
            Dictionary = 'anim@amb@nightclub@lazlow@ig1_hi@',
            Options = {
                Flags = { Loop = true },
            },
        },
    },
    PropEmotes = {},
    ConsumableEmotes = {},
    DanceEmotes = {},
    SynchronizedEmotes = {},
    AnimalEmotes = {}
}

As listas são concatenadas às nativas na inicialização, no client e no servidor. Guarde uma cópia deste arquivo antes de atualizar o recurso.

Para registrar emotes em runtime, a partir de outro recurso, use o export registerEmote.

Binds de emote

O menu tem uma seção Emote Keybinds com 10 slots. Em cada slot você associa um comando de emote e um rótulo; a tecla em si é escolhida pelo jogador em Configurações > Controles, procurando por Emote Bind Slot 1 a 10.

Os binds são salvos localmente no KVP do cliente (scully_emotemenu_binds_v2), ou seja, ficam por máquina e sobrevivem a reconexões. O menu também permite exportar os binds para a área de transferência e limpar todos de uma vez.

Emotes sincronizados

Um emote sincronizado toca duas animações em par — uma no jogador que iniciou e outra em quem aceitou. O campo Options.Shared.OtherAnimation liga uma à outra.

Fluxo:

1. O jogador toca o emote (ex.: /e sbaseball). O client procura o jogador mais próximo em 3 metros.
2. O servidor entrega o convite ao alvo, que vê um alerta para aceitar ou recusar. Emotes com SkipRequest = true pulam esta etapa.
3. Ao aceitar, o servidor confere que os dois estão a menos de 5 metros e dispara as duas animações, uma em cada cliente.

Cancelar o emote de qualquer um dos lados encerra a animação dos dois.

Prop dump

Com EnablePropDump = true, o servidor varre todas as animações a cada start e regrava o prop_dump.lua na raiz do recurso com a lista completa de props usados por emotes, em formato de tabela de hashes:

return {
	[`p_amb_bottle_01`] = true,
	[`prop_cs_burger_01`] = true,
}

Serve para alimentar a whitelist de objetos do seu anti-cheat. Depois de gerar o arquivo, dá para desligar a flag para não regravá-lo a cada restart.

Integrações

QBCore (compat/qbcore.lua)

O arquivo só age se o qb-core estiver presente (GetResourceState diferente de unknown/missing). Ele registra os eventos legacy do qb-smallresources/rpemotes e os traduz para os exports oficiais, bloqueando a ação se o jogador estiver morto, em last stand ou algemado (metadados isdead, inlaststand, ishandcuffed).

O comentário no topo do arquivo avisa que essa camada pode ser removida no futuro: prefira os exports oficiais em código novo.

Radial do ox_lib

Com EnableRadialMenu = true, o recurso adiciona um item “Emotes” ao radial global do ox_lib, com submenus para caminhadas e expressões e uma opção de cancelar. Emotes com Hide = true não aparecem no radial.

Entrypoints para outros recursos

Todos os exports são de client.

Menu

exports.scully_emotemenu:toggleMenu()
exports.scully_emotemenu:closeMenu()
 
-- Abre um alerta listando as animações de uma categoria.
-- Categorias válidas: Emotes, Walks, Scenarios, Expressions, PropEmotes,
-- ConsumableEmotes, DanceEmotes, SynchronizedEmotes, AnimalEmotes.
exports.scully_emotemenu:listEmotes('Emotes')

Tocar e cancelar

-- Toca pelo Command da animação. O 3º argumento é opcional e aplica o emote em outro ped.
exports.scully_emotemenu:playEmoteByCommand('adjusttie', variant, ped)
 
-- Toca passando a tabela da animação diretamente.
exports.scully_emotemenu:playEmote(emoteTable, variant)
 
exports.scully_emotemenu:cancelEmote()

Emotes registrados

-- Registra uma animação em runtime, indexada pelo campo Name.
exports.scully_emotemenu:registerEmote({
    Name = 'meuemote',
    Type = 'Emotes',              -- 'Walks' faz o playRegisteredEmote chamar setWalk
    Animation = 'idle_a',
    Dictionary = 'anim@amb@nightclub@lazlow@ig1_hi@',
    Options = { Flags = { Loop = true } },
})
 
exports.scully_emotemenu:playRegisteredEmote('meuemote')

Emotes registrados assim não aparecem no menu — servem para outros recursos dispararem animações próprias reaproveitando o gerenciamento de props e partículas.

Caminhada e expressão

local walk = exports.scully_emotemenu:getCurrentWalk()
exports.scully_emotemenu:setWalk('move_m@hipster@a')
exports.scully_emotemenu:resetWalk()
 
local expression = exports.scully_emotemenu:getCurrentExpression()
exports.scully_emotemenu:setExpression('mood_angry_1')
exports.scully_emotemenu:resetExpression()

Caminhada e expressão são persistidas no KVP do cliente (animations_walkstyle e animations_expression) e reaplicadas a cada spawn.

Estado

-- true enquanto uma animação do recurso está tocando.
local inEmote = exports.scully_emotemenu:isInEmote()
 
-- Última animação tocada e a variante usada.
local emote, variant = exports.scully_emotemenu:getLastEmote()
 
-- Bloqueia o jogador de usar qualquer emote, comando ou tecla do recurso.
exports.scully_emotemenu:setLimitation(true)
local limited = exports.scully_emotemenu:isLimited()

Use setLimitation(true) em situações como algemas, morte ou minigames — é o mesmo gancho que o compat/qbcore.lua usa.

Substituir notificação e textUI

exports.scully_emotemenu:customNotifyFn(function(type, message)
    -- type é 'error' ou 'success'
    exports.meu_hud:Notify(message, type)
end)
 
exports.scully_emotemenu:customHelpAlertFn(function(icon, text)
    exports.meu_hud:ShowHelp(text, icon)
end)

Permite trocar as notificações e o textUI do ox_lib pelos do seu HUD sem editar o recurso.

Menu de binds

exports.scully_emotemenu:OpenBindMenu()

Eventos de client

Espelham os exports, para quem prefere disparar por evento a partir do servidor.

TriggerClientEvent('scully_emotemenu:toggleMenu', src)
TriggerClientEvent('scully_emotemenu:closeMenu', src)
TriggerClientEvent('scully_emotemenu:cancelEmote', src)
TriggerClientEvent('scully_emotemenu:play', src, emoteTable, variant)
TriggerClientEvent('scully_emotemenu:playByCommand', src, 'adjusttie', variant)
TriggerClientEvent('scully_emotemenu:registerEmote', src, emoteTable)
TriggerClientEvent('scully_emotemenu:playRegisteredEmote', src, 'meuemote')
TriggerClientEvent('scully_emotemenu:setWalk', src, 'move_m@hipster@a')
TriggerClientEvent('scully_emotemenu:resetWalk', src)
TriggerClientEvent('scully_emotemenu:setExpression', src, 'mood_angry_1')
TriggerClientEvent('scully_emotemenu:resetExpression', src)
TriggerClientEvent('scully_emotemenu:toggleLimitation', src, true)
TriggerClientEvent('scully_emotemenu:listEmotes', src, 'Emotes')

Statebags

Localização

O idioma do menu é resolvido nesta ordem:

1. a convar ox_locale do servidor, se existir um locales/<codigo>.lua correspondente;
2. o Config.Language;
3. en como último recurso.

setr ox_locale "pt-br"

Note que a convar é ox_locale (com underline), não ox:locale.

Idiomas disponíveis em locales/: cs, da, de, en, es, et, fa, fi, fr, hu, id, it, nl, no, pl, pt, pt-br, ro, ru, sv, tl, tr, vi, zhcn, zhtw.

Comandos traduzidos

Além das strings da interface, os arquivos data/animations/*_pt-br.lua traduzem os comandos e rótulos das próprias animações. Eles são carregados como aliases: a animação em inglês continua funcionando, e a versão traduzida vira um comando adicional apontando para a mesma animação. No menu, aparece só a variante do idioma escolhido — e a entrada em inglês só reaparece quando não existe tradução para ela.

Para adicionar um idioma novo, crie locales/<codigo>.lua seguindo a estrutura dos existentes. Traduzir os comandos das animações exige criar também os arquivos data/animations/<categoria>_<codigo>.lua e registrar o sufixo no translationMapping do client/main.lua.

Estrutura de arquivos

scully_emotemenu/
├── client/
│   ├── main.lua              — menu, radial, comandos, teclas, props, ptfx, emotes sincronizados
│   └── keybinds.lua          — 10 slots de bind de emote, persistidos em KVP
├── server/
│   └── main.lua              — spawn e limpeza de props, roteamento dos emotes sincronizados, prop dump
├── compat/
│   └── qbcore.lua            — eventos legacy animations:* (só ativa se o qb-core existir)
├── data/
│   ├── animations/
│   │   ├── emotes.lua                  — emotes gerais
│   │   ├── dance_emotes.lua            — danças
│   │   ├── prop_emotes.lua             — emotes com props
│   │   ├── consumable_emotes.lua       — comer, beber, fumar
│   │   ├── synchronized_emotes.lua     — emotes em par
│   │   ├── animal_emotes.lua           — emotes de peds animais
│   │   ├── walks.lua                   — estilos de caminhada
│   │   ├── scenarios.lua               — cenários nativos
│   │   ├── expressions.lua             — expressões faciais
│   │   └── *_pt-br.lua                 — comandos e rótulos traduzidos, carregados como aliases
│   └── ped_types.lua         — grupos de modelos de ped (dogs, cats, birds…) usados pela flag PedTypes
├── locales/                  — 25 idiomas da interface (.lua)
├── docs/                     — documentação por export, evento e statebag (markdown)
├── html/                     — resíduo de uma NUI antiga: não é declarado no fxmanifest nem usado pelo código
├── stream/
│   ├── [Animations]/         — dicionários de animação customizados
│   └── [Props]/              — modelos e .ytyp dos props
├── config.lua                — toda a configuração
├── custom_emotes.lua         — suas animações, preservadas entre atualizações
├── prop_dump.lua             — lista de props gerada automaticamente (whitelist de anti-cheat)
├── version.txt               — versão usada na checagem de update
└── fxmanifest.lua