mri_Qchat — Manual

Substituto do chat padrão do FiveM com UI em React, canais separados (global, local, OOC, RP, staff, anúncios) e log opcional no Discord.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Comandos
5. Canais e cores
6. Cor de destaque
7. Log e evento de mensagens
8. Entrypoints para outros recursos
9. Build da UI
10. Estrutura de arquivos

Dependências

O recurso não usa ox_lib nem banco de dados.

Instalação

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

   ensure mri_Qchat
3. Remova ou desabilite o recurso chat padrão do cfx-server-data — os dois declaram ui_page e registram os mesmos eventos (chat:addMessage, chat:addSuggestion, chat:clear, _chat:messageEntered) e não podem rodar juntos.
4. Opcional: defina a cor de destaque e o webhook de log (veja Configuração).

Configuração

Arquivo: shared/config.lua.

Comandos

Digitar sem barra envia a mensagem para o canal LOCAL, respeitando o raio de Config.LocalDistance.

A permissão de staff é resolvida por exports.qbx_core:HasPermission(source, 'admin') ou 'god' — o console (source == 0) sempre passa. As sugestões de comando exibidas no autocomplete são filtradas por IsPlayerAceAllowed(player, 'command.<nome>'), ou seja, cada jogador só vê os comandos que pode executar.

Canais e cores

Essa paleta é independente da cor de destaque da UI: ela colore a mensagem, não a interface.

Cor de destaque

A cor de destaque da UI (bordas, botões, ícones) vem da convar global mri:color, compartilhada com o resto da suite MRI:

setr mri:color "#00E699"

Se a convar não estiver definida, o fallback é #00E699. Mudanças em runtime são detectadas por AddConvarChangeListener no servidor: a nova cor é validada (#RRGGBB) e propagada imediatamente para todos os clientes via mri_Qchat:client:accentColorChanged, sem restart.

Log e evento de mensagens

Toda mensagem que passa pelos comandos do recurso aciona duas saídas opcionais:

• Evento de servidor — se Config.EnableCustomEvent for true, o evento nomeado em Config.CustomEventName é disparado com { source, author, message, channel, timestamp }. O channel recebe RP_ME e RP_DO para /me e /do (mais específico que o canal RP usado na cor).
• Webhook do Discord — se Config.DiscordWebhook estiver preenchido, um embed com autor, mensagem, canal e source id é enviado via PerformHttpRequest.

Entrypoints para outros recursos

Enviar mensagem para o chat

O recurso implementa os eventos padrão do chat do FiveM, então qualquer código já escrito para o chat original funciona:

TriggerClientEvent('chat:addMessage', source, {
    channel = 'ANUNCIOS',
    args = { 'Sistema', 'Manutenção em 10 minutos.' },
    color = { 255, 215, 0 }
})
 
TriggerClientEvent('chat:clear', source)
TriggerClientEvent('chat:addSuggestion', source, '/meucomando', 'Descrição', {})
TriggerClientEvent('chat:removeSuggestion', source, '/meucomando')

O evento legacy chatMessage(author, color, text) também é aceito no client.

Consumir as mensagens (moderação, logs, tradução)

AddEventHandler('mri_Qchat:server:onMessage', function(data)
    -- data.source, data.author, data.message, data.channel, data.timestamp
end)

Renomeie o evento em Config.CustomEventName se precisar de outro nome.

Trocar a cor de destaque em runtime

SetConvarReplicated('mri:color', '#FF5500')

O listener do mri_Qchat aplica a cor em todos os clientes na hora.

Build da UI

A interface fica em web/ (React + Vite + Tailwind) e o bundle compilado em html/, que é o que o fxmanifest.lua carrega. Para alterar a UI, edite web/src/ e gere um novo build; sem rebuild, mudanças no código-fonte não aparecem no jogo.

Estrutura de arquivos

mri_Qchat/
├── client/
│   └── cl_chat.lua       — ponte NUI, foco do input, hide no pause/fade, comando /limpar
├── server/
│   └── sv_chat.lua       — comandos de canal, proximidade, sugestões, webhook, evento custom
├── shared/
│   ├── config.lua        — toda a configuração
│   └── sh_utils.lua      — conversão hex -> RGB das cores de canal
├── html/
│   ├── index.html        — UI compilada (carregada pelo fxmanifest)
│   └── assets/           — JS, CSS e imagem do build
├── web/                  — código-fonte React da UI (Vite + Tailwind)
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/Chat/
│   │   │   ├── ChatWindow.tsx    — janela arrastável e lista de mensagens
│   │   │   ├── InputBox.tsx      — input, autocomplete de comandos
│   │   │   ├── Message.tsx       — render de uma mensagem
│   │   │   ├── SettingsPanel.tsx — preferências do jogador
│   │   │   ├── Tabs.tsx          — abas de canal
│   │   │   └── TopBar.tsx        — barra superior
│   │   ├── hooks/useNuiEvent.ts
│   │   ├── lib/accentColor.ts    — aplica a cor de destaque recebida do client
│   │   └── utils/                — fetchNui, debugData, misc
│   └── vite.config.ts
└── fxmanifest.lua