Arquitetura, instalação, todas as opções do config.lua, loja.lua e logs.lua, convars, autenticação, sincronização, protocolo e atualizações do recurso fivedash.
O fivedash é o recurso que liga a cidade ao FiveDash. Ele roda no lado do servidor do FXServer, detecta a framework sozinho e faz valer no jogo o que o painel decide: libera e tira a whitelist, entrega as compras da loja e manda os logs dos scripts. Esta página é para quem administra o servidor ou desenvolve scripts e quer entender como ele funciona por dentro.
FXServer com Node 22: o fxmanifest.lua pede node_version "22". Use um artifact recente do FXServer.
Banco MySQL (para whitelist e loja): um destes drivers iniciado: oxmysql, ghmattimysql ou mysql-async. Sem driver, a conexão com o painel funciona, mas a whitelist fica só no Discord e a loja não entrega.
Chave do servidor: gerada em Servidor → Visão geral → Conexão com o jogo → Conectar servidor → Gerar chave. Só Dono e Admin da organização geram a chave.
Nome da pasta: mantenha a pasta como fivedash. Os scripts chamam exports.fivedash:… e conferem GetResourceState("fivedash").
Cidade (FXServer) FiveDash┌───────────────────────────────┐ HTTPS (sai) ┌──────────────────────┐│ fivedash/server/main.js │ ──────────────▶ │ POST /api/fivem/sync ││ ├─ detecção da framework │ ◀────────────── │ comandos pendentes ││ ├─ módulo Discord (whitelist) │ └──────────────────────┘│ ├─ módulo Loja (entregas) │ HTTPS (sai) ┌──────────────────────┐│ └─ módulo Logs (export) │ ──────────────▶ │ serviço de logs ││ MySQL da cidade (oxmysql…) │ └──────────────────────┘└───────────────────────────────┘
Só o servidor: todo o código roda em server/main.js (um único bundle). O client/main.js está vazio: nada roda no jogo dos jogadores, e o recurso não registra nenhum evento de rede (RegisterNetEvent). Jogadores não conseguem mandar comandos nem logs para ele.
Sempre de dentro para fora: o recurso chama o painel; o painel nunca chama a cidade. Não precisa abrir porta nem liberar IP.
Independente de framework: o recurso não depende de nenhuma framework. Ele descobre qual a cidade usa e conversa com ela por exports, eventos e pelo banco. Veja Frameworks.
Módulos:
Discord: aplica as liberações da whitelist (whitelist.allow) e tira de quem sai do Discord (whitelist.revoke).
Loja: grava cada entrega no MySQL da cidade antes de responder, entrega uma vez só (nunca duas) e espera o jogador entrar quando precisa dele online.
Logs: recebe exports.fivedash:log(...) dos scripts e manda em lotes.
No painel, vá em Servidor → Visão geral, no cartão Conexão com o jogo clique em Conectar servidor e depois em Gerar chave. Clique em Baixar fivedash.zip: o config.lua já vem com a chave.
Extraia na pasta resources
Extraia a pasta fivedash dentro de resources (ou de uma subpasta como resources/[fivedash]).
Inicie depois da framework
No server.cfg, coloque ensure fivedash depois do driver do banco e da framework:
shellscript
ensure oxmysqlensure qb-coreensure fivedash
Reinicie e confira
Reinicie o servidor (ou digite refresh e ensure fivedash no console). No console aparece [FiveDash] Conectado ao FiveDash como "Cidade Exemplo". e o painel mostra Conectado.
Já tinha o recurso instalado? Cole só a chave nova no fivedash/config.lua:
Lido só pelo servidor. Depois de mudar algo, rode restart fivedash.
Opção
O que faz
Padrão
Key
A chave do servidor no FiveDash (começa com fdk_). Vazia, o recurso não conecta e avisa no console
""
Framework
"auto" detecta sozinho. Para forçar: "creative-enchanted", "qbox", "qbcore", "esx", "ox-core" ou "vrp". Forçada e não encontrada, nenhuma é usada e o console mostra erro
"auto"
AutoUpdate
Instala sozinho as versões novas do recurso (os .lua de configuração ficam como estão). Desligado, só avisa no console
true
Debug
Mostra cada sincronização e comando no console, e as evidências da detecção
false
Duas opções não vêm no arquivo, mas são aceitas:
Opção
O que faz
Padrão
Url
Endereço do painel. O recurso baixado pelo painel já traz esta linha preenchida com https://fivedash.fivex.gg; deixe como veio
https://fivedash.fivex.gg (vem no download)
Locale
Idioma do console antes da primeira conexão: "pt-BR" ou "en". Depois, vale o Idioma da cidade do painel. O download já traz essa linha para cidades que não estão em português
português
Como as atualizações mexem nos arquivos de configuração#
Quando uma versão nova traz uma opção que o seu arquivo não tem, o recurso acrescenta essa opção (com o comentário e o valor padrão) antes do } final, sem mudar nem apagar o que você escreveu. Antes, ele guarda uma cópia em config.lua.bak (ou loja.lua.bak, logs.lua.bak). O console avisa quais opções entraram. Se o arquivo não tem a forma FiveDash = { ... }, ele não é tocado e as opções novas usam o padrão.
Opções da entrega da loja na cidade. Detalhes de cada tipo de entrega em Entrega no jogo.
Opção
O que faz
Padrão
Enabled
Liga a entrega da loja nesta cidade. Desligada, o site da loja para de vender até você ligar de novo
true
Notify
Avisa o jogador na tela quando a compra chega
true
NotifyTitle
Título do aviso (até 40 caracteres). "Loja" aparece no idioma da cidade
"Loja"
Announce
Anuncia para a cidade inteira quem comprou o quê (uma vez por pedido; presentes não são anunciados)
false
SpawnDelay
Segundos entre o jogador escolher o personagem e a entrega (de 0 a 120)
10
AllowedCommands
Comandos de console que a loja pode rodar. Vazio libera qualquer um, menos os bloqueados. Para travar, liste o começo de cada um: { "darmoedas", "addcar" }
{}
Comandos sempre bloqueados na entrega por comando, mesmo com AllowedCommands vazio: quit, stop, start, restart, ensure, refresh, exec, set, sets, setr, seta, rcon_password, sv_licensekey, sv_hostname, sv_maxclients, endpoint_add_tcp, endpoint_add_udp, load_server_icon e fivedash. Uma linha é um comando só: ; e quebras de linha são recusados. Cada comando roda no máximo 100 vezes por entrega.
Opções dos logs mandados pelo export exports.fivedash:log. Os webhooks não dependem deste arquivo.
Opção
O que faz
Padrão
Enabled
Liga o envio de logs pelo export. Desligado, as chamadas são ignoradas
true
PlayerInfo
Lê o passaporte e o nome do personagem de cada jogador do log, pela framework
true
Identifiers
Identificadores do jogador que vão em cada log. Aceitos: license, license2, discord, steam, fivem, xbl, live, ip
{ "license", "discord" }
Coords
Guarda a posição do primeiro jogador do log quando o script não manda coords
true
Disabled
Chaves de logs que nunca saem da cidade. Ex.: { "chat" }
{}
AllowedResources
Recursos que podem mandar logs. Vazio deixa qualquer um. Ex.: { "vrp", "inventory" }
{}
Echo
Mostra cada log no console quando entra (só para testes)
false
O ritmo de envio é fixo: um lote por segundo, até 250 logs por lote, e até 20.000 logs guardados na fila enquanto o painel estiver fora. Linhas antigas como FlushInterval, BatchSize e MaxQueue ficam no arquivo, mas são ignoradas.
Uma chave por servidor: a chave tem o formato fdk_ + 32 caracteres. O painel guarda só o hash dela e mostra apenas os 4 últimos caracteres (Recurso…a1b2). Ela aparece inteira uma vez, quando é gerada.
Cabeçalho: toda chamada manda Authorization: Bearer fdk_….
Uma cidade por chave: cada boot do recurso cria um ID de instância (X-FiveDash-Instance). Se a mesma chave estiver ligada em dois servidores ao mesmo tempo, o painel mantém o que já sincronizava e recusa o outro (409) até o primeiro ficar 10 segundos quieto (um restart). Assim, nenhuma entrega vai para a cidade errada nem acontece duas vezes.
Trocar ou desligar:Gerar nova chave substitui a chave na hora. Desconectar apaga a ligação e descarta os comandos que ainda não foram entregues.
O recurso faz uma sincronização atrás da outra com POST /api/fivem/sync. Cada uma leva o estado da cidade e os resultados dos comandos anteriores; a resposta traz os comandos novos. Quando não há nada, o painel segura a resposta por até 3 segundos (long polling), então uma liberação ou uma compra chega na cidade em poucos segundos.
Regra
Valor
Frequência máxima
1 sincronização por segundo por servidor (mais rápido recebe 429)
Espera sem comandos
até 3 segundos
Tempo limite da chamada
45 segundos
Sem conexão
tenta de novo de 2 s em 2 s, dobrando até 60 s, e avisa no console uma vez só
Framework detectada: id, name, version, features (whitelist, store), idKind (account, token ou discord) e warnings (no idioma da cidade). null sem framework
players, maxPlayers
Jogadores agora e sv_maxclients (padrão 32)
results
Resultado de cada comando: { "id", "ok": true } ou { "id", "ok": false, "code", "message" }
store
Estado da loja na cidade: ligada, problema, o que entrega, nome do ID e entregas esperando
deliveries
Entregas que mudaram de estado (done, waiting, failed), até 200 por sincronização
hold
false na primeira sincronização (e depois de uma queda), para o painel responder na hora
Libera o ID (e liga o Discord, quando vem) na whitelist da framework
whitelist.revoke
Tira a whitelist pelo ID e/ou pelo Discord e, se vier kickMessage, derruba o jogador com essa mensagem
store.deliver
Recebe as entregas de um pedido (com retry: true no Reenviar, só o que falhou roda de novo)
store.cancel
Pedido devolvido: descarta o que ainda espera na cidade
store.lookup
Pergunta para quem a compra iria (ID e nome do personagem, e se está online)
Todo comando é idempotente: se o resultado se perde e o comando volta, o recurso responde o que já fez, sem rodar de novo. Códigos de erro: not_found (o ID não existe no banco), unsupported (a framework não faz isso), invalid (ID em formato errado) e failed (outro problema, com message).
Os logs do export não passam pela sincronização: eles vão por outro caminho, para uma cidade cheia nunca atrasar os comandos.
O recurso pede o mapa dos logs em GET /api/fivem/logs/channels (com a mesma chave). O mapa diz quais chaves de log existem e para onde mandar, e vale por pouco tempo.
A cada segundo, manda até 250 logs em POST /api/fivem/logs, com gzip quando o lote passa de 1 KB.
Sem conexão, os logs ficam na fila (até 20.000) e vão quando o painel voltar.
O recurso e o painel combinam o formato das mensagens pelo campo protocol (GAME_PROTOCOL, hoje 1). Quando o painel muda algo que quebra versões antigas, ele sobe esse número e passa a responder 426 para recursos mais velhos, que mostram no console “versão do recurso não aceita mais” e pedem para baixar a nova. Mudanças que não quebram nada não mexem no número.
Com AutoUpdate = true (padrão), o recurso se atualiza sozinho:
A sincronização avisa que existe uma versão nova.
O recurso baixa cada arquivo e confere o tamanho e o SHA-256 antes de gravar qualquer coisa. Só podem ser atualizados fxmanifest.lua, server/*.js e client/*.js (até 10 MB cada). Os .lua de configuração nunca são tocados.
Grava os arquivos e confere cada um. Se um falha, os que já foram gravados voltam ao conteúdo anterior.
A versão nova entra no próximo restart do servidor, ou com restart fivedash no console. O recurso nunca se reinicia sozinho.
O painel mostra no cartão Conexão com o jogo: “Versão X do recurso disponível…”. Se uma atualização falha, o recurso tenta de novo em 10 minutos. Com AutoUpdate = false, ele só avisa no console: FiveDash X disponível (este é o Y). AutoUpdate está desligado no config.lua.
Para atualizar à mão: no cartão Conexão com o jogo, clique em Conectar servidor e depois em Baixar a última versão. Esse zip vem sem chave: troque só fxmanifest.lua, server/ e client/ e mantenha os seus .lua de configuração.
Preciso abrir alguma porta no servidor?
Não. O recurso só faz chamadas HTTPS para fora.
Posso usar a mesma chave em dois servidores (teste e produção)?
Não. Cada servidor do FiveDash tem a sua chave e só uma cidade fica ligada por vez. Crie outro servidor no painel para o ambiente de teste.
A atualização automática apaga minha configuração?
Não. config.lua, loja.lua e logs.lua nunca são sobrescritos. Opções novas são só acrescentadas, com cópia .bak antes.
Funciona sem framework?
Sim. A conexão funciona, a whitelist fica só no Discord e a loja entrega só por comandos de console.