Agency-Notify: Las notificaciones deberían parecer de iOS, no de FiveM de 2014

El gueto de las notificaciones

Las notificaciones de la mayoría de los servidores FiveM todavía parecen las de ESX de 2019. Una barra básica de color en la parte superior, quizá un icono y una línea de texto. Los jugadores se han acostumbrado a ignorarlas. Es un canal de comunicación muy desaprovechado para transmitir información importante.

Cómo son las notificaciones modernas

Agency-Notify incluye notificaciones tipo toast que se apilan ordenadamente, admiten contenido enriquecido (iconos, imágenes, texto en varias líneas y botones de acción) y tienen niveles de gravedad claros con estilos visuales distintos. Los avisos de éxito, advertencia, error e información tienen cada uno su propia animación, color y grosor tipográfico.

Agrupación para evitar el spam

Si varias notificaciones similares aparecen seguidas en poco tiempo, Agency-Notify las combina en una sola notificación agrupada. Se acabaron las tres notificaciones idénticas de «Has ganado $500» bloqueando la pantalla. Es algo que los jugadores esperan de cualquier aplicación moderna y que por fin está disponible en FiveM.

API fácil de usar para desarrolladores

Una sola llamada a función para mostrar una notificación desde cualquier script: exports['agency-notify']:Show({title, body, icon, level, duration, actions}) . Devuelve un ID que puedes usar después para actualizar o cerrar la notificación. Eso es todo. Sin dependencias de frameworks ni variables globales mágicas.

Standalone por una razón

Agency-Notify es un componente independiente del framework. Tus scripts de QBCore, ESX y el código personalizado standalone usan todos la misma API. Así mantienes un lenguaje visual coherente en todo el servidor, incluso con decenas de scripts de distintos autores.

Instalación y configuración

Poner Agency-Notify en marcha lleva menos de diez minutos. Descarga el recurso desde tu biblioteca de Tebex, arrastra la agency-notify carpeta al directorio resources de tu servidor y añade ensure agency-notify a tu server.cfg . El recurso no depende de ninguna base de datos, todo el estado de las notificaciones se gestiona en memoria en el cliente.

Una vez en marcha, cualquier script de tu servidor puede usar la API de exports de inmediato. No hace falta configurar nada después de la instalación para empezar a enviar notificaciones, los valores predeterminados funcionan bien desde el primer momento.

Opciones de configuración

Abre config.lua para personalizar los valores visuales y de comportamiento predeterminados:

• Position, esquina superior derecha (predeterminada), superior izquierda, inferior derecha o inferior izquierda.
• Max visible, cuántas notificaciones se apilan antes de descartar las más antiguas. El valor predeterminado es 5.
• Default duration, milisegundos antes del cierre automático. Cada notificación puede sobrescribir este valor.
• Animation style, slide-in-right (predeterminado), fade o scale. Se aplica a todas las notificaciones de forma global.
• Group window, intervalo de tiempo en milisegundos durante el cual se agrupan las notificaciones idénticas.
• Sound enabled, activa o desactiva el sutil sonido de notificación para cada nivel de gravedad.

Todos los ajustes están en una única tabla de configuración plana, sin estructuras anidadas que revisar ni archivos de configuración separados para cliente y servidor.

Compatibilidad con frameworks

Agency-Notify es 100% standalone. No importa ningún framework ni depende de QBCore o ESX. Esto significa que:

• Funciona en cualquier servidor FiveM, independientemente del framework que uses.
• Cambiar de framework más adelante no rompe las llamadas a las notificaciones.
• Todos los scripts, de cualquier autor, pueden enviar notificaciones a través de la misma API sin saber qué framework usas.

Si vas a reemplazar un sistema de notificaciones existente (el notify de ox_lib, QBNotify de QBCore, etc.), solo tienes que actualizar la llamada al export en tus scripts. La firma es lo bastante parecida a los patrones habituales como para que buscar y reemplazar sirva en la mayoría de las migraciones.

Por qué esto importa para el roleplay

Las notificaciones son el principal canal de comunicación entre los sistemas del servidor y los jugadores. Cuando termina un trato de drogas, cuando una banda rival entra en tu territorio o cuando un admin necesita avisar a todos de un evento, todo eso pasa por las notificaciones. Si ese canal parece anticuado o los jugadores lo ignoran, la comunicación crítica del servidor falla sin que nadie se dé cuenta.

Los jugadores que confían en su sistema de notificaciones le prestan atención. Quienes ya se han acostumbrado a ignorar una barra de notificaciones molesta y poco atractiva se pierden cosas y sienten que no están al tanto. El sistema de agrupación de Agency-Notify aborda específicamente el problema del spam: si tu servidor envía tres notificaciones seguidas durante un atraco, los jugadores ven un único mensaje agrupado en lugar de tres avisos compitiendo por su atención.

Los niveles de gravedad (success, warning, error, info) añaden una segunda capa de información. Los jugadores aprenden rápido que el verde significa buenas noticias y el rojo, que hay que actuar de inmediato. Esta comprensión de los colores reduce la carga cognitiva en situaciones de mucha acción.

Preguntas frecuentes

¿Puedo actualizar o descartar una notificación después de que aparezca?

Sí. El Show() La exportación devuelve un ID. Pásalo a exports['agency-notify']:Update(id, {body, level}) para cambiar el contenido, o a exports['agency-notify']:Dismiss(id) para eliminarlo antes de tiempo. Esto es útil para notificaciones de progreso cuyo estado cambia (p. ej., "Procesando…" → "Listo").

¿Esto reemplaza las notificaciones de ox_lib?

Puede hacerlo. Agency-Notify cubre los mismos casos de uso con un estilo visual diferente. Si quieres una estética glassmorphism coherente con otros scripts de Agency, cambiar es sencillo. Si tu servidor está muy integrado con ox_lib y te gusta ese aspecto, puedes seguir usando ox_lib para las notificaciones, no hay ningún conflicto.

¿Los jugadores pueden personalizar la posición de las notificaciones?

No de forma predeterminada, la posición se elige en la configuración del servidor. Es intencional: los propietarios del servidor controlan el lenguaje visual, no los jugadores. Si quieres permitir preferencias individuales, tendrás que guardar la elección en una base de datos y pasarla a través de los datos del jugador al conectarse.

¿Hay un límite de frecuencia para evitar que los scripts envíen notificaciones spam?

El sistema de agrupación se encarga de eliminar duplicados automáticamente. Para establecer un límite estricto, configura Config.RateLimit = true y Config.RateLimitWindow = 1000 (ms) en config.lua. Esto limita cuántas notificaciones únicas puede enviar un mismo script dentro del intervalo.

Requisitos

• Servidor de FiveM, compatible con cualquier framework o standalone
• cuenta de cfx.re con una clave de licencia válida de Agency-Notify en tu keymaster
• Sin dependencia de base de datos
• Sin dependencias de recursos externos

Comparación de Agency-Notify con otras opciones

El ecosistema de notificaciones de FiveM ofrece varias opciones: las notificaciones de ox_lib, las notificaciones integradas de QBCore y varios scripts standalone. Aquí te explicamos cuándo conviene cada una:

Las notificaciones de ox_lib son eficaces y están bien mantenidas, pero su estilo está ligado al lenguaje visual de ox_lib. Si tu servidor ya usa ox_lib en todas partes, la coherencia visual puede ser más importante que la mejora. Si estás creando un stack centrado en Agency, la estética a juego de Agency-Notify encaja mejor.

QBNotify de QBCore es funcional, pero minimalista: no tiene agrupación, API de actualización ni botones de acción. Sirve para casos básicos y no cuesta nada adicional si ya usas QBCore. Si necesitas algo más que notificaciones sencillas, se te ha quedado corto.

Agency-Notify está pensado para servidores que consideran la experiencia de las notificaciones un detalle importante del producto, no algo secundario. Si alguna vez has pensado "nuestras notificaciones se ven mal y los jugadores las ignoran", este script existe para resolver ese problema.