Agency-Notify: notificações devem parecer iOS, não FiveM de 2014

O gueto das notificações

As notificações na maioria dos servidores FiveM ainda parecem o ESX padrão de 2019. Uma barra colorida básica no topo, talvez um ícone, uma linha de texto. Os jogadores se acostumaram a ignorá-las. Esse é um canal enorme desperdiçado para comunicar informações importantes.

Como são as notificações modernas

Agency-Notify oferece notificações no estilo toast que se empilham de forma organizada, aceitam conteúdo avançado (ícones, imagens, texto em várias linhas, botões de ação) e têm níveis de gravidade claros, com tratamentos visuais distintos. Sucesso, aviso, erro, informação, cada um tem sua própria animação, cor e peso tipográfico.

Agrupamento que evita spam

Se três notificações semelhantes forem disparadas em rápida sucessão, Agency-Notify as reúne em uma única notificação agrupada. Chega de três toasts idênticos de "Você ganhou $500" bloqueando a tela. Esse é o comportamento que os jogadores esperam de qualquer aplicativo moderno e que finalmente existe no FiveM.

API fácil para programadores

Uma chamada de função para disparar uma notificação de qualquer script: exports['agency-notify']:Show({title, body, icon, level, duration, actions}) . Retorna um ID que você pode usar para atualizar ou dispensar a notificação depois. Só isso. Sem dependência de framework, sem variáveis globais mágicas.

Standalone por um motivo

Agency-Notify é um componente independente de framework. Seus scripts QBCore, ESX e seu código personalizado standalone chamam a mesma API. É assim que você mantém uma linguagem visual consistente no servidor, entre dezenas de scripts de autores diferentes.

Instalação e configuração

Para colocar o Agency-Notify em funcionamento, você leva menos de dez minutos. Baixe o recurso da sua biblioteca do Tebex, arraste a pasta agency-notify para o diretório resources do servidor e adicione ensure agency-notify ao seu server.cfg. O recurso não depende de banco de dados, todo o estado das notificações é gerenciado na memória, no cliente.

Depois de iniciado, qualquer script do servidor pode chamar a API exports imediatamente. Não é necessária nenhuma configuração após a instalação para começar a disparar notificações, os padrões já são adequados.

Opções de configuração

Abra config.lua para personalizar os padrões visuais e de comportamento:

• Posição, fixação no canto superior direito (padrão), superior esquerdo, inferior direito ou inferior esquerdo.
• Máximo visível, quantas notificações se empilham antes que as mais antigas sejam dispensadas. O padrão é 5.
• Duração padrão, milissegundos até a dispensa automática. Notificações individuais podem substituir esse valor.
• Estilo de animação, slide-in-right (padrão), fade ou scale. Aplica-se globalmente a todas as notificações.
• Janela de agrupamento, janela de tempo em milissegundos na qual notificações idênticas são agrupadas.
• Som ativado, ative ou desative o discreto toque de notificação por nível de severidade.

Todas as configurações ficam em uma única tabela de configuração plana, sem estruturas aninhadas para procurar e sem configurações separadas para cliente e servidor.

Compatibilidade com frameworks

Agency-Notify é 100% standalone. Não importa frameworks nem depende de QBCore ou ESX. Isso significa:

• Funciona em qualquer servidor FiveM, independentemente do framework base.
• Trocar de framework mais tarde não interrompe as chamadas de notificação.
• Scripts de qualquer autor podem enviar notificações pela mesma API sem saber qual framework você usa.

Se você estiver substituindo um sistema de notificações existente (notify do ox_lib, QBNotify do QBCore etc.), basta atualizar a chamada do export nos seus scripts. A assinatura é parecida o suficiente com os padrões comuns para que localizar e substituir resolva a maioria das migrações.

Por que isso importa para o roleplay

As notificações são o principal canal de feedback entre os sistemas do servidor e os jogadores. Quando uma negociação de drogas é concluída, quando uma gangue rival entra no seu território ou quando um administrador precisa alertar todos sobre um evento, tudo isso passa pelas notificações. Se esse canal parecer ultrapassado ou for ignorado, comunicações críticas do servidor falham sem que ninguém perceba.

Jogadores que confiam no sistema de notificações prestam atenção nele. Jogadores que aprenderam a ignorar uma barra de notificações exagerada e feia deixam passar informações importantes e se sentem por fora. O sistema de agrupamento do Agency-Notify trata especificamente do problema de spam: se o seu servidor enviar três notificações rápidas durante um assalto, os jogadores verão uma única mensagem agrupada, em vez de três notificações competindo pela atenção.

Os níveis de severidade (success, warning, error, info) adicionam uma segunda camada de sinalização. Os jogadores aprendem rapidamente que verde significa algo bom e vermelho significa que precisam agir agora. Essa familiaridade com as cores reduz a carga cognitiva em situações de ação intensa.

Perguntas frequentes

Posso atualizar ou dispensar uma notificação depois que ela aparece?

Sim. O Show() export retorna um ID. Passe esse ID para exports['agency-notify']:Update(id, {body, level}) para alterar o conteúdo ou para exports['agency-notify']:Dismiss(id) para removê-la antes do tempo. Isso é útil para notificações de progresso cujo estado muda (por exemplo, "Processando…" → "Concluído").

Isso substitui as notificações do ox_lib?

Pode substituir. Agency-Notify cobre os mesmos casos de uso com um estilo visual diferente. Se você quiser uma estética de glassmorphism consistente com outros scripts Agency, a troca é simples. Se o seu servidor estiver muito integrado ao ox_lib e você gostar desse visual, não há problema em continuar usando o ox_lib para notificações, não há conflito.

Os jogadores podem personalizar a posição das notificações?

Não por padrão, a posição é definida nas configurações do servidor. Isso é intencional: os proprietários do servidor controlam a linguagem visual, não os jogadores individualmente. Se você quiser preferências por jogador, precisará salvar a escolha em um banco de dados e incluí-la nos dados do jogador na entrada.

Há um limite de frequência para evitar spam de notificações por scripts?

O sistema de agrupamento cuida automaticamente da deduplicação. Para limitar a frequência de forma rígida, defina Config.RateLimit = true e Config.RateLimitWindow = 1000 (ms) em config.lua. Isso limita quantas notificações únicas um mesmo script pode enviar dentro do intervalo.

Requisitos

• Servidor FiveM (qualquer framework ou standalone)
• conta cfx.re com uma chave de licença válida do Agency-Notify no seu keymaster
• Sem dependência de banco de dados
• Sem dependências de recursos externos

Comparação entre Agency-Notify e as alternativas

O ecossistema de notificações do FiveM oferece várias opções: notificações do ox_lib, notificações integradas do QBCore e diversos scripts standalone. Veja em quais situações cada opção faz sentido:

As notificações do ox_lib são competentes e recebem boa manutenção, mas seu estilo está vinculado à linguagem visual do ox_lib. Se o seu servidor já usa o ox_lib por completo, a consistência visual pode ser mais importante que a atualização. Se você estiver montando um conjunto de scripts focado na Agency, a estética correspondente do Agency-Notify combina melhor.

O QBNotify do QBCore é funcional, mas minimalista: não tem agrupamento, API de atualização nem botões de ação. Ele atende a casos de uso básicos e não custa nada a mais se você já usa QBCore. Se precisar de algo além de notificações simples, você já superou esse recurso.

Agency-Notify é voltado a servidores que tratam a experiência com notificações como um detalhe importante do produto, e não como algo secundário. Se você já pensou "nossas notificações são feias e os jogadores as ignoram", este script foi criado para resolver esse problema.