mri_Qadmin — Manual

Painel de administração para servidores QBCore/Qbox: jogadores, veículos, itens, permissões por grupo, staff chat, logs, mapa e telas ao vivo, navegador de recursos e uma arquitetura de plugins para outros recursos se plugarem ao painel.

Sumário

1. Dependências
2. Instalação
3. Permissões (ACE)
4. Configuração
5. Comandos
6. Teclas
7. Painel — abas
8. Grupos e Master Admin
9. Logs
10. Navegador de recursos
11. Telas ao vivo (WebRTC)
12. Ações customizadas
13. Plugins
14. Banco de dados
15. Integrações
16. Entrypoints para outros recursos
17. Localização
18. Estrutura de arquivos

Dependências

Instalação

1. Copie a pasta mri_Qadmin para resources/.
2. Adicione ao server.cfg, depois de ox_lib, oxmysql e do framework:

   ensure mri_Qadmin
3. SQL — as tabelas são criadas automaticamente no start (server/db.lua lê e executa o database.sql). Importar na mão é opcional.
4. Primeiro acesso — nenhum jogador tem acesso ao painel por padrão. Pelo console do servidor, promova alguém a Master Admin:

   mri_qadmin.setmaster 1
   O Master Admin ignora todas as checagens e consegue abrir o painel para criar os grupos definitivos.
5. Escrita em outros recursos (opcional) — para o navegador de arquivos poder salvar em recursos de terceiros, libere cada um no server.cfg:

   add_filesystem_permission mri_Qadmin write <nome_do_resource>
   Veja Navegador de recursos.
6. Patch do ox_lib (opcional) — para que logs de outros recursos feitos com lib.logger apareçam no painel, aplique o patch descrito em OX_LIB_PATCH.md.

Permissões (ACE)

Todas as permissões nativas usam o prefixo qadmin.. O servidor é a única fonte de verdade: as definições vivem em server/permissions.lua e são enviadas para a NUI, que apenas renderiza o que recebe.

A referência completa, permissão por permissão, está em PERMISSIONS.md.

Na prática, as permissões não são escritas no server.cfg: elas são atribuídas a grupos pelo próprio painel, gravadas no banco e reaplicadas com lib.addAce a cada start. Um grupo pode ser vinculado a principals do FiveM (group.admin, job.police, gang.ballas) para herança automática, ou a personagens específicos (char:<citizenid>).

Configuração

Arquivo: shared/config.lua.

Boa parte desses campos também é editável pela aba Configurações do painel, sem restart — os valores alterados ali são gravados na tabela mri_qadmin_settings e passam a ter precedência sobre o arquivo.

Comandos

Os cinco comandos mri_qadmin.* só respondem quando source == 0, ou seja, apenas pelo console do servidor — não há como executá-los pelo chat, mesmo sendo admin.

Teclas

As duas são keybinds do ox_lib (mri:toogleAdmin e mri:toogleNoclip), reatribuíveis pelo jogador nas configurações do FiveM. Config.Keybindings = false desativa as duas.

Painel — abas

Cada aba é gated por sua própria permissão qadmin.page.* e cada ação dentro dela por uma qadmin.action.*.

Grupos e Master Admin

Grupos

Um grupo (mri_qadmin_groups) é um conjunto de permissões (mri_qadmin_group_permissions) com um label. As permissões do grupo são aplicadas como ACE via lib.addAce a cada start do recurso.

Um grupo pode ser alcançado de três formas:

• Principal do FiveM — vinculando o grupo a group.admin, job.police, gang.ballas etc.
• Personagem — vinculando um citizenid diretamente (mri_qadmin_character_groups).
• QBCoreAutoSync — com Config.QBCoreAutoSync = true, quem tem rank admin ou god no QBCore entra automaticamente no grupo admin do painel.

Master Admin

Status especial, concedido só pelo console, que ignora toda checagem de permissão. Fica gravado em mri_qadmin_masters (por license) e é reaplicado como ACE a cada start.

mri_qadmin.setmaster 1                  # por ID online
mri_qadmin.setmaster license:abcd1234   # por license
mri_qadmin.removemaster 1
mri_qadmin.purgemasters                 # limpa todos do banco

Use para o primeiro acesso e para recuperação — não como cargo do dia a dia.

Logs

O painel centraliza os logs do servidor. Cada log tem resource, category, level, message e um data opcional, e pode ir para três destinos ao mesmo tempo: buffer em memória (exibição instantânea), banco (mri_qadmin_logs) e webhook do Discord.

Config.Logs = {
    Webhooks = {
        players     = "",   -- bans, kicks, revives
        bans        = "",
        inventory   = "",
        vehicles    = "",
        money       = "",
        server      = "",   -- clima, hora, anúncios
        permissions = "",
        chat        = "",
        system      = "",
        Fallback    = "",   -- recebe as categorias sem webhook próprio
    },
    ForwardEvent    = "",           -- evento de servidor disparado a cada log ("" desativa)
    DBEnabled       = true,
    MaxMemory       = 500,          -- quantidade de logs mantidos em memória
    ResourceMode    = 'blacklist',  -- 'blacklist' | 'whitelist'
    ResourceEntries = {},           -- { name = 'meu_resource', db = true, discord = false, relay = true }
    Categories      = { … },        -- id + label das categorias exibidas no painel
}

As categorias e destinos também são editáveis em runtime pela aba de configurações de logs; o que for salvo lá tem precedência sobre o Config (arquivo logs_settings.json).

Para receber logs de recursos que usam lib.logger do ox_lib, aplique o patch de OX_LIB_PATCH.md. Detalhes do formato em LOGS.md.

Navegador de recursos

A aba Recursos lista todos os recursos do servidor, permite start/stop/restart e traz um navegador de arquivos: explorar pastas, abrir e editar arquivos de texto, criar e excluir arquivos e pastas.

Escrita e o sandbox do FiveM. Desde os artifacts > 25770, o FiveM bloqueia a escrita de um recurso nos arquivos de outro recurso. Na prática:

• Leitura e navegação funcionam em todos os recursos.
• Salvar, criar e excluir só funcionam nos arquivos do próprio mri_Qadmin ou em recursos liberados explicitamente:

  add_filesystem_permission mri_Qadmin write <nome_do_resource>
  Uma linha por recurso — o FiveM não aceita wildcard. Depois de adicionar, reinicie o mri_Qadmin para reavaliar.

Quando o recurso não é gravável, o painel mostra um aviso de “somente leitura” com a linha exata a colar no server.cfg e desabilita os controles de escrita. A exclusão exige qadmin.action.change_resource e qadmin.action.resource_delete.

Telas ao vivo (WebRTC)

Transmissão da tela de um jogador para o painel, para monitoramento. O backend de sinalização é escolhido em Config.SignalingProvider:

Ações customizadas

Config.Actions, Config.PlayerActions e Config.OtherActions permitem declarar botões próprios no painel, que disparam eventos ou comandos. As ações padrão ficam em data/default_actions.lua (carregado via LoadResourceFile) e as criadas pelo painel são persistidas em mri_qadmin_actions.

O servidor valida o payload de cada ação antes de executá-la — só eventos explicitamente permitidos passam.

Plugins

Outros recursos podem registrar uma aba própria no sidebar do painel e adicionar suas permissões ao editor de grupos.

-- no server-side do plugin (ex.: mri_Qspawn/server/main.lua)
exports['mri_Qadmin']:RegisterPlugin({
    id            = 'spawns',                  -- slug lógico do plugin
    label         = 'Spawns',
    icon          = 'car',                     -- ícone lucide-react
    resource      = 'mri_Qspawn',              -- NOME DO RESOURCE (monta a URL cfx-nui-<resource>)
    htmlPath      = 'web/build/index.html',    -- opcional
    requiredPerms = { 'mri_Qspawn.admin', 'command' },
    permDefs      = {                          -- opcional: metadados por permissão
        { id = 'mri_Qspawn.admin', label = 'Administrador', desc = 'Acesso total ao painel de spawns' },
    },
    description   = 'Gerenciador de spawns',
})

• id e resource são coisas diferentes: id é o slug do plugin, resource é o nome do recurso usado para montar a URL do iframe.
• A visibilidade é OR: o plugin aparece para quem tiver qualquer uma das requiredPerms. Sem requiredPerms, aparece para todos.
• A checagem usa HasPerms, então honra o Master Admin e os principals estendidos (char:, job., gang.).
• Permissões válidas das requiredPerms (as que têm ponto e não são built-ins do FiveM, como command) entram automaticamente no editor de grupos, em uma categoria com o nome do plugin.
• Quando o recurso do plugin para, o Qadmin o remove do registry automaticamente.

Para registrar apenas permissões, sem aba no painel, use RegisterPermissions (ver Entrypoints).

Banco de dados

Tabelas criadas automaticamente no start:

Integrações

qb-core / qbx_core

Framework base. Jogadores online e offline, jobs, gangues, dinheiro, metadata e notificações. Com Config.QBCoreAutoSync = true, ranks admin/god do QBCore viram membros do grupo admin do painel automaticamente.

Inventário

Detectado sozinho no start (ox_inventory, ps-inventory, lj-inventory ou qb-inventory) e reavaliado sempre que um deles inicia. Sustenta a aba Itens e as ações de inventário na aba Jogadores.

Combustível

Config.Fuel define qual recurso é chamado ao abastecer um veículo pelo painel: cdn-fuel, ps-fuel, LegacyFuel ou ox_fuel.

Concessionária

Com Config.Dealership = "mri", a aba Veículos gerencia o estoque do qbx_vehicleshop. ps-dealerships e none também são aceitos.

mri_Qsignaling

Servidor de sinalização das telas ao vivo quando Config.SignalingProvider = "websocket". O endereço vai em Config.WebRTCUrl.

ox_lib (logger)

Com o patch de OX_LIB_PATCH.md, qualquer recurso que use lib.logger com o serviço qadmin passa a mandar seus logs para o painel, sem precisar chamar AddLog diretamente.

Entrypoints para outros recursos

RegisterPlugin / UnregisterPlugin — servidor

Registram e removem uma aba do painel. Ver Plugins.

exports['mri_Qadmin']:RegisterPlugin({ id = 'spawns', label = 'Spawns', resource = 'mri_Qspawn', ... })
exports['mri_Qadmin']:UnregisterPlugin('spawns')

RegisterPermissions — servidor

Adiciona permissões ao editor de grupos sem registrar uma aba. A categoria é opcional; se não existir, é criada.

exports['mri_Qadmin']:RegisterPermissions({
    { id = 'meu_resource.admin', label = 'Administrador', desc = 'Acesso total' },
    { id = 'meu_resource.view',  label = 'Visualizar' },
}, { id = 'meu_resource', label = 'Meu Resource' })

AddLog — servidor

Envia um log para o painel (memória, banco e Discord, conforme o Config.Logs).

exports['mri_Qadmin']:AddLog(
    'meu_resource',   -- resource
    'players',        -- category (precisa existir em Config.Logs.Categories)
    'info',           -- level
    'Mensagem do log',
    { extra = 'dados opcionais' },
    source            -- opcional: admin responsável
)

Equivalente por evento, para quem não quer depender do export:

TriggerEvent('mri_Qadmin:server:AddLog', resource, category, level, message, data, source)

HasPerms / CheckPerms — servidor

HasPerms é o predicado silencioso; CheckPerms é o gate que notifica o jogador ao negar. Os dois aceitam uma permissão ou uma lista.

if not exports['mri_Qadmin']:HasPerms(source, 'qadmin.action.ban') then return end
if not exports['mri_Qadmin']:CheckPerms(source, { 'meu_resource.admin', 'command' }) then return end

Os dois honram o Master Admin e conferem também contra os identifiers do jogador, o que contorna o atraso de cache do IsPlayerAceAllowed nativo.

IsPlayerInPrincipal — servidor

Verifica se qualquer identifier do jogador pertence a um principal.

local ehAdmin = exports['mri_Qadmin']:IsPlayerInPrincipal(source, 'group.admin')

GeneratePlate — servidor

Gera uma placa no formato AA AA 000, garantindo que ainda não exista no banco.

local plate = exports['mri_Qadmin']:GeneratePlate()

ToggleUI / OpenUI / IsMenuVisible — cliente

Controlam a NUI do painel a partir de outro recurso.

exports['mri_Qadmin']:OpenUI()
exports['mri_Qadmin']:ToggleUI(false)
local aberto = exports['mri_Qadmin']:IsMenuVisible()

GetActions está declarado no bloco exports do fxmanifest.lua, mas não existe função global correspondente — chamá-lo falha. Os dados de ações são obtidos pelo callback mri_Qadmin:callback:GetActions.

Eventos server → client

Localização

As strings do recurso e da UI são traduzidas via ox_lib locale (ox_lib "locale" no fxmanifest.lua). Os arquivos ficam em locales/:

• pt-br.json — português do Brasil
• en.json — inglês
• es.json — espanhol

O locale ativo vem da convar do ox_lib:

setr ox:locale "pt-br"

Os idiomas oferecidos na UI são os listados em Config.SupportedLanguages. Para adicionar um novo, crie locales/<codigo>.json seguindo a estrutura dos existentes, adicione a entrada em Config.SupportedLanguages e reinicie o recurso.

Estrutura de arquivos

mri_Qadmin/
├── client/
│   ├── main.lua              — bootstrap da NUI e roteamento de callbacks
│   ├── utils.lua             — ToggleUI/OpenUI/IsMenuVisible, CheckPerms via callback
│   ├── data.lua              — cache dos dados sincronizados do servidor
│   ├── chat.lua              — staff chat
│   ├── inventory.lua         — abertura e leitura de inventários
│   ├── misc.lua              — keybinds do painel e do noclip
│   ├── notify.lua            — notificações internas
│   ├── noclip.lua            — noclip
│   ├── players.lua           — vitais, coordenadas e ações sobre jogadores
│   ├── spectate.lua          — espectar jogador
│   ├── teleport.lua          — teleportes
│   ├── toggle_laser.lua      — laser (dev mode)
│   ├── troll.lua             — ações de troll
│   ├── vehicles.lua          — spawn, conserto, mods e placa
│   ├── wall.lua              — ESP/wallhack
│   ├── world.lua             — clima e hora
│   ├── key_capture.lua       — captura de tecla para as configurações
│   ├── nearby_scanner.lua    — scanner de entidades próximas (dev mode)
│   ├── vip.lua               — VIP
│   ├── logs.lua              — logs no cliente
│   ├── webrtc.lua            — captura e envio da tela (telas ao vivo)
│   └── plugins.lua           — recebe a lista de plugins visíveis
├── server/
│   ├── db.lua                — cria as tabelas lendo o database.sql
│   ├── main.lua              — inicialização e core object
│   ├── utils.lua             — HasPerms, CheckPerms, IsPlayerInPrincipal, GeneratePlate
│   ├── permissions.lua       — definições de permissão, ACE, Master Admin, RegisterPermissions
│   ├── groups.lua            — CRUD de grupos e vínculos
│   ├── data_sync.lua         — envia definições e dados para a NUI
│   ├── logs.lua              — buffer, banco, webhooks, AddLog
│   ├── chat.lua              — staff chat e menções
│   ├── commands.lua          — comandos do painel
│   ├── players.lua           — moderação, teleporte, dinheiro, job/gangue
│   ├── inventory.lua         — operações de inventário
│   ├── inventory_callback.lua— callbacks de inventário para a NUI
│   ├── items.lua             — base de itens
│   ├── vehicle.lua           — estoque, spawn e ações de veículo
│   ├── locations.lua         — locais de teleporte
│   ├── peds.lua              — troca de model
│   ├── actions.lua           — ações customizadas e validação de payload
│   ├── settings.lua          — configurações editáveis pelo painel
│   ├── resources.lua         — start/stop/restart e gate de escrita do sandbox
│   ├── resource_fs.js        — navegação no filesystem dos recursos
│   ├── server_data.lua       — dados gerais do servidor
│   ├── spectate.lua          — espectar
│   ├── teleport.lua          — teleporte
│   ├── trolls.lua            — trolls
│   ├── wall.lua              — cores do ESP por principal
│   ├── vip.lua               — VIP
│   ├── key_manager.lua       — keybinds
│   ├── webrtc.lua            — sinalização das telas ao vivo
│   ├── updates.lua           — verificação de atualização
│   └── plugins.lua           — registry de plugins (RegisterPlugin/UnregisterPlugin)
├── shared/
│   └── config.lua            — Config, detecção de inventário, Debug e Notify
├── data/
│   ├── default_actions.lua   — ações padrão (lidas via LoadResourceFile)
│   ├── object.lua            — hash → nome de objeto (usado pelo scanner e pelo laser)
│   ├── ped.lua               — lista de peds
│   └── weapons.lua           — lista de armas
├── locales/
│   ├── pt-br.json
│   ├── en.json
│   └── es.json
├── web/build/                — UI compilada (ui_page) + tiles do mapa
├── database.sql              — todas as tabelas do recurso
├── PERMISSIONS.md            — referência completa de permissões
├── LOGS.md                   — formato e categorias de log
├── OX_LIB_PATCH.md           — patch do lib.logger para integrar logs de terceiros
└── fxmanifest.lua