mri_Qbox — Manual

Recurso guarda-chuva da suite MRI: reúne os menus F9/F10, o sistema de staff e VIP, e um conjunto de módulos opcionais de combate, veículos e interação que ligam os demais recursos MRI ao qbx_core.

Sumário

1. Dependências
2. Instalação
3. Permissões (ACE)
4. Configuração
5. Comandos
6. Teclas
7. Menus F9 e F10
8. Staff
9. VIP
10. Módulos
11. Integrações
12. Entrypoints para outros recursos
13. Estrutura de arquivos

Dependências

Os menus F9/F10 disparam comandos de outros recursos (doorlock, blip, bau, npc, objectspawner, elevador, garagelist, craft:create, open_jobs, spotlight, weather, adm…). Cada entrada só funciona se o recurso que registra aquele comando estiver instalado — o mri_Qbox não valida isso.

Instalação

1. Copie a pasta mri_Qbox para resources/.
2. Adicione ao server.cfg, depois de ox_lib, qbx_core, oxmysql, ox_inventory e ox_target:

   ensure mri_Qbox
3. Libere a ACE de admin (ver Permissões (ACE)).
4. Ajuste config.lua — quase todos os módulos vêm com toggle = false e precisam ser ligados individualmente.
5. Não há SQL para importar. Staff e VIP são gravados na metadata do player (players.metadata), tabela que o qbx_core já cria.

Permissões (ACE)

Os comandos administrativos usam restricted = 'group.admin' do ox_lib:

add_ace group.admin command allow
add_principal identifier.fivem:1 group.admin

Além disso, o recurso concede principals dinamicamente:

• Ao entrar no servidor, quem tem metadata.staff recebe o principal correspondente (group.admin, group.mod, group.support) via lib.addPrincipal.
• Ao entrar, quem tem metadata.vip recebe o principal com o nome do tier (tier1, …).

Ou seja, o cargo de staff é persistido na metadata do personagem e reaplicado como ACE a cada login — não é preciso mexer no server.cfg para cada admin.

Configuração

Arquivo principal: config.lua (tabela global cfg).

Chaves de config sem implementação

cfg.SqlBackup e cfg.AutoUpdater existem no config.lua, mas nenhum arquivo do repositório lê essas chaves. Alterá-las não tem efeito.

Configs por módulo

Comandos

/god, /tpway, /setargang e /cutscene estão sem restrição — o restricted está comentado no código-fonte de /god e /tpway.

Teclas

As duas são keybinds do ox_lib (menu_jogador_keybind e menu_admin_keybind), então o jogador pode reatribuí-las nas configurações do FiveM.

Menus F9 e F10

F9 — menu do jogador

Entradas fixas: Identificação (/id), Emprego (/job), Gangue (/gang), Ver Reputação (/rep), Ver Habilidades (/skill) e Waypoints (limpar marcadores e configurações).

“Gerenciar Emprego” e “Gerenciar Gangue” só aparecem se o mri_Qjobsystem disser que o jogador é chefe ou recrutador.

F10 — menu de administração

Entradas fixas: Abrir Painel (/adm), Customizar Veículo (/customs), Relógio (hora, escala de tempo, congelar tempo), Clima (/weather) e Gerenciamento.

O submenu Gerenciamento agrupa comandos de outros recursos: Portas (doorlock), Blips (blip), Baús (bau), NPC (npc), Props (objectspawner), Elevador (elevador), Outdoors/Posters (rw_draw++), Garagens (garagelist), Crafting (craft:create / craft:edit), Grupos (createjob / open_jobs) e Spotlight. Se o mri_Qvinewood estiver iniciado, aparece também a entrada Vinewood.

Menus extensíveis

Os três menus aceitam entradas de outros recursos em runtime — ver Entrypoints. Os alvos válidos são 'player' (F9), 'f10' (F10) e 'management' (submenu Gerenciamento).

Staff

O cargo de staff é gravado em metadata.staff do personagem, com o valor no formato group.<cargo> (group.admin, group.mod, group.support).

• /staff <id> add <cargo> — grava a metadata e concede o principal na hora.
• /staff <id> rem — remove o principal e limpa a metadata.
• No login (QBCore:Server:OnPlayerLoaded), o principal é reaplicado a partir da metadata.
• O painel de staff (registrado no menu de Gerenciamento) lista todos os personagens do banco com metadata de staff, online e offline, e permite alterar o cargo de jogadores offline via mri_Qbox:server:manageStaff.

VIP

Ligado por cfg.vipmenu.Enable. O tier é gravado em metadata.vip e vira principal de ACE com o mesmo nome do tier.

• Salário — a cada PaycheckInterval minutos, cada jogador online com VIP recebe Roles[tier].payment na conta definida em CashType.
• Peso do inventário — no login e a cada alteração de VIP, o peso máximo é definido como Roles[tier].inventory * 1000 gramas. Quem não é VIP usa Roles.nenhum.inventory — por isso a chave nenhum é obrigatória.
• Painel — entrada no menu F10; lista VIPs online e offline e permite adicionar/remover.

Módulos

Cada módulo é ligado individualmente pelo config.lua. Os que estão desligados fazem return no topo do arquivo e não custam nada.

Combate (modules/mri/client-side/combat-modules/)

Veículos (modules/mri/client-side/vehicles-modules/)

Target (modules/mri/client-side/target-modules/)

Utilitários

Módulos independentes (modules/*/)

Integrações

mri_Qjobsystem

O menu F9 chama CheckPlayerIsbossByJobSystemData e CheckPlayerIrecruiterByJobSystemData para decidir se mostra “Gerenciar Emprego” e “Gerenciar Gangue”. A chamada é direta, sem GetResourceState — sem o mri_Qjobsystem iniciado, o menu do jogador não abre.

mri_Qadmin

setPlayerJob e setPlayerGang verificam GetResourceState('mri_Qadmin'). Se estiver iniciado, disparam mri_Qadmin:server:SetJob / mri_Qadmin:server:SetGang. Caso contrário, caem no fallback do ps-adminmenu.

qbx_management

Fonte da lista de jogadores próximos usada nos painéis de staff e VIP (qbx_management:server:getPlayers) e do boss menu aberto por /menu <job>.

mri_Qvinewood

Se estiver iniciado, adiciona a entrada “Vinewood” no submenu de Gerenciamento (executa /vinewood).

ox_inventory

Além dos usos diretos (peso, itens, stash temporário), o recurso registra dois hooks swapItems: um para o drop de itens como prop e outro para o drag-craft.

Entrypoints para outros recursos

Menus — cliente

Adicionar e remover entradas dos menus F9/F10/Gerenciamento em runtime. É o mecanismo que os outros recursos MRI usam para se plugarem ao painel.

exports.mri_Qbox:AddPlayerMenu({          -- menu F9
    title = 'Minha opção',
    icon = 'star',
    iconAnimation = 'fade',
    description = 'Descrição da opção',
    arrow = true,
    onSelectFunction = function() ExecuteCommand('meucomando') end,
    onSelectArg = nil,                    -- opcional: argumento passado para onSelectFunction
})
exports.mri_Qbox:RemovePlayerMenu('Minha opção')
 
exports.mri_Qbox:AddManageMenu({ ... })   -- submenu Gerenciamento (dentro do F10)
exports.mri_Qbox:RemoveManageMenu('Minha opção')
 
exports.mri_Qbox:AddItemToMenu('f10', { ... })  -- menu F10 direto ('f10' | 'management' | 'player')
exports.mri_Qbox:RemoveItemFromMenu('f10', 'Minha opção')

GetRayCoords — cliente

Abre o seletor de coordenadas por raycast. Bloqueia até o jogador confirmar (E = vector3, G = vector4) ou cancelar (Q). Retorna o vetor e já copia para o clipboard; retorna false se cancelado.

local coords = exports.mri_Qbox:GetRayCoords()

Request — cliente

Diálogo Sim/Não em menu do ox_lib. Bloqueia até a resposta e retorna booleano.

local confirmou = exports.mri_Qbox:Request('Título', 'Texto da pergunta', 'top-right')

CanCarryItem — cliente

Verifica se o jogador aguenta o peso de amount unidades do item.

local pode = exports.mri_Qbox:CanCarryItem('water', 5)

setPlayerJob / setPlayerGang — cliente

Abrem diálogos de seleção de job/gangue e grade e aplicam no jogador alvo (via mri_Qadmin ou ps-adminmenu).

exports.mri_Qbox:setPlayerJob(targetServerId)   -- job opcional; se omitido, abre o seletor
exports.mri_Qbox:setPlayerGang(targetServerId)

addVip / removeVip — cliente

Usados pelo painel de VIP. Tratam jogador online (via comando /vipadm) e offline (via evento mri_Qbox:server:manageVip).

exports.mri_Qbox:addVip({
    vipData = { source = 1, citizenId = 'ABC12345', name = 'Nome Sobrenome', offline = false },
    newRole = 'tier1',
    callback = function() end,   -- opcional
})

VipAdm — servidor

Mesma lógica do comando /vipadm, chamável de outro recurso. Retorna true em caso de sucesso.

exports.mri_Qbox:VipAdm(source, { id = targetId, tipo = 'add', tier = 'tier1' })

addRecipe — cliente e servidor

Adiciona uma receita de drag-craft em runtime; a chamada sincroniza automaticamente o outro lado.

exports.mri_Qbox:addRecipe('garbage metalscrap', {
    duration = 2000,
    costs  = { garbage = { need = 1, remove = true }, metalscrap = { need = 1, remove = true } },
    result = { { name = 'lockpick', amount = 1 } },
})

A chave da receita é "<itemA> <itemB>"; a ordem inversa também é aceita no momento do craft.

itemPlace — servidor

Export desenhado para ser usado como hook de item do ox_inventory (campo export em data/items.lua). Coloca o prop do item no chão à frente do jogador e bloqueia o uso dentro de veículo.

['cadeira'] = {
    label = 'Cadeira',
    weight = 1000,
    prop = 'prop_chair_01a',
    export = 'mri_Qbox.itemPlace',
},

GlobalState UIColors

O recurso publica um esquema de cores em GlobalState.UIColors, consumido pelos demais recursos MRI:

{ success = '#51CF66', info = '#668CFF', warning = '#FFD700', danger = '#FF6347' }

Para alterar, edite modules/mri/client-side/ox_lib-modules/context.lua e modules/mri/client-side/main.lua — a tabela está duplicada nos dois arquivos.

Estrutura de arquivos

mri_Qbox/
├── config.lua                                   — cfg: VIP, drop de itens, combate, veículos, target
├── modules/
│   ├── cinematic/                               — cinemática de boas-vindas (/cinematic)
│   │   ├── client/client.lua                    — planos de câmera, música, teleporte final
│   │   ├── client/config.lua                    — lista de shots (posição, look-at, duração, texto, hora)
│   │   └── server/server.lua                    — comando /cinematic (group.admin)
│   ├── dragCraft/                               — craft arrastando um item sobre outro
│   │   ├── config.lua                           — RECIPES
│   │   ├── client/client.lua                    — progress bar e callbacks client
│   │   └── server/server.lua                    — hook swapItems, fila de craft, addRecipe
│   ├── itemCarry/                               — prop visual ao carregar item
│   │   ├── client/c_itemCarry.lua               — anexa o prop, restringe andar/veículo
│   │   └── server/data.lua                      — CARRY_ITEMS
│   ├── itemcollection/                          — pegar/colocar props do mundo como item
│   │   ├── shared/shared.lua                    — mapa prop → item, derivado do ox_inventory
│   │   ├── client/client.lua                    — target "Pegar" em objetos do mundo
│   │   └── server/server.lua                    — pickup e export itemPlace
│   ├── waterCooler/                             — beber e encher garrafa
│   │   ├── config/config.lua                    — props-alvo, distâncias, itens, hidratação
│   │   ├── client/client.lua                    — target, animação, skill check
│   │   └── server/server.lua                    — hidratação, troca de garrafa, anti-abuso
│   └── mri/
│       ├── client-side/
│       │   ├── main.lua                         — GlobalState.UIColors
│       │   ├── combat-modules/                  — ragdoll, recoil, blind fire, combat roll, free punch, POV
│       │   ├── vehicles-modules/                — drift, wheelbreak, explosão, volante, controle no ar, placas
│       │   ├── target-modules/                  — lixeiras, entrada por porta, trunkchest (comentado)
│       │   ├── ox_lib-modules/                  — menus F9/F10, painel staff, painel VIP, inputs, oncache
│       │   ├── ox_inventory-modules/            — CanCarryItem
│       │   └── utilities-modules/               — comandos, cutscene, raycast/Request, props indestrutíveis, maskfix
│       └── server-side/
│           ├── ox_lib-modules/                  — drop de itens como prop, staff, VIP (salário e peso)
│           └── utilities-modules/               — comandos admin, identifiers no connect, /viewallitems
├── web-side/                                    — NUI do contador de pontos de drift
│   ├── index.html
│   ├── core.js
│   └── icones/
└── fxmanifest.lua