Un script pequeño, un efecto enorme
Las barras de progreso aparecen por todas partes en FiveM — ganzúas, reparaciones, blanqueo de dinero, minería, asistencia médica. Las implementaciones por defecto son funcionales, pero planas. Agency-ProgressBar es nuestra visión de cómo debería sentirse esta utilidad cuando a alguien le importan los detalles.
La anatomía de una buena barra de progreso
Una buena barra de progreso comunica cuatro cosas a la vez: qué acción está ocurriendo, cuánto has avanzado, cuánto tiempo queda y si puedes cancelar. La mayoría de implementaciones solo cubren las dos primeras. Agency-ProgressBar muestra las cuatro, con animaciones sutiles que hacen que el progreso se sienta fluido en lugar de a saltos.
Cancelación que funciona
La cancelación iniciada por el jugador dispara una breve animación de fade-out que devuelve la opacidad de la barra a cero en 300ms. Sin desaparición brusca. Los desarrolladores pueden registrar un callback de cancelación para que los scripts se limpien correctamente cuando los jugadores abandonan una acción a medias.
Posicionamiento contextual
La barra aparece cerca del elemento relevante en pantalla — sobre tu cabeza para acciones dirigidas a ti mismo, sobre el NPC objetivo para acciones interactivas. Se acabó leer el estado de la acción en la parte inferior de la pantalla mientras algo ocurre arriba. Este posicionamiento contextual es una mejora de UX sutil que los jugadores sienten sin poder nombrarla.
El patrón de exports
Como todos nuestros scripts de utilidad, Agency-ProgressBar expone una API de exports simple: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). Lo integras en cualquier script en minutos. Se combina con Agency-Notify, Agency-Hud y el resto de nuestro ecosistema sin ninguna configuración especial.
Instalación y Configuración
Agency-Progressbar se instala como un recurso de utilidad de FiveM. No requiere dependencias de base de datos ya que opera puramente en el lado del cliente. Después de agregar a server.cfg, está inmediatamente disponible a través de exports para cualquier otro recurso.
Opciones de Configuración
- Posición predeterminada — parte inferior de la pantalla, centro o sobre la cabeza del personaje
- Esquema de colores — paleta predeterminada o colores personalizados por código HTML
- Velocidad de animación — qué tan rápido aparece y desaparece la barra
- Tecla de cancelación — qué teclas permiten cancelar la barra de progreso en curso
Compatibilidad con Frameworks
Agency-Progressbar es completamente independiente del framework. Funciona igual en ESX, QBCore y servidores standalone. No hay dependencias de framework en absoluto: la barra de progreso es puramente interfaz de usuario del cliente con devoluciones de llamada opcionales del servidor.
Por Qué Esto Importa para el Roleplay
Las barras de progreso hacen que las acciones se sientan deliberadas. Sin ellas, el roleplay se convierte en una serie de pulsaciones de teclas instantáneas sin peso o consecuencia. Con Agency-Progressbar, cada acción tiene duración y puede ser interrumpida, lo que crea tensión y drama en los escenarios de RP.
Uso en Scripts Personalizados
Agency-Progressbar brilla realmente cuando lo integras en tus propios recursos. La llamada API del lado del cliente es simple y directa. Puedes encadenar múltiples barras de progreso para acciones complejas de varios pasos — cada etapa con su propia etiqueta, duración y condiciones de cancelación.
Casos de Uso Concretos
- Reanimar a un jugador caído — 10 segundos, cancelable si el jugador se mueve
- Registrar un vehículo — 5 segundos, requiere estar junto al vehículo
- Plantar un explosivo — 30 segundos, larga para crear tensión dramática
- Recoger recursos — 3 segundos por recurso recolectado
- Abrir una cerradura — 8 segundos con ganzúa
Preguntas Frecuentes
- ¿Puede Agency-Progressbar integrarse con animaciones de personajes? Sí, puedes especificar un diccionario y clip de animación que se reproduce mientras avanza la barra.
- ¿Qué pasa si el servidor lag hace que la barra se complete antes que la acción del servidor? El callback incluye validación del lado del servidor para confirmar que la acción fue válida.
- ¿Pueden los jugadores cancelar la barra de progreso? Configurable por acción — algunas acciones pueden ser cancelables, otras no.
Acerca de Agency Scripts
Agency Scripts es una colección de recursos premium de FiveM diseñados para servidores de roleplay que se toman en serio la inmersión. Cada recurso está construido con los mismos principios: compatibilidad multi-framework, rendimiento optimizado y configuración flexible para adaptarse a cualquier concepto de servidor.
Todos los recursos de Agency están disponibles a través del sistema de licencias de cfx.re Keymaster. Una vez comprado, puedes desplegar el recurso en cualquier servidor que poseas, con soporte activo disponible a través del Discord de Agency Scripts.
Soporte y Comunidad
La comunidad de Agency Scripts incluye miles de servidores de FiveM que utilizan estos recursos. El Discord oficial es donde los desarrolladores comparten sus configuraciones, hacen preguntas y sugieren nuevas características. Las actualizaciones son regulares e incluyen tanto correcciones de errores como nuevas características basadas en los comentarios de la comunidad.
Para preguntas de instalación, problemas de compatibilidad o solicitudes de características, Discord es el mejor canal. La documentación se mantiene actualizada y cubre todas las configuraciones con ejemplos prácticos. También hay una wiki comunitaria activa con guías contribuidas por los propios operadores de servidores.
Por Qué los Servidores Eligen Agency Scripts
La razón principal por la que los servidores de FiveM eligen Agency Scripts es la consistencia. Cuando todas tus herramientas vienen del mismo proveedor, tienen el mismo estilo de configuración, el mismo soporte y el mismo estándar de calidad. No hay sorpresas al actualizar un recurso porque saben qué esperar. Para los administradores de servidores que quieren pasar más tiempo en el roleplay y menos en solucionar problemas de scripts, esa consistencia tiene un valor real.
Requisitos del Sistema
Para usar los recursos de Agency Scripts, tu servidor FiveM necesita cumplir con los siguientes requisitos mínimos:
- Versión de servidor FiveM — artifact 4752 o superior recomendado
- Framework — ESX 1.2+, QBCore (cualquier versión principal), o configuración standalone
- Base de datos — MariaDB o MySQL 5.7+ con oxmysql como capa de base de datos
- ox_lib — recomendado para elementos UI mejorados, no siempre obligatorio
Los recursos de Agency Scripts están probados en los artifacts de servidor más recientes y se actualizan regularmente para mantenerse al día con los cambios de FiveM. Si usas un artifact particularmente antiguo y encuentras problemas, actualizar el servidor suele ser el primer paso de diagnóstico.
Licencias y Keymaster
Como todos los recursos premium de FiveM, los recursos de Agency Scripts se licencian a través del sistema Keymaster de cfx.re. Compras el recurso en el Tebex de Agency Scripts, luego aparece en tu cuenta de Keymaster donde puedes vincularlo a los identificadores de tu servidor. Las licencias son per-servidor pero no tienen fecha de caducidad una vez compradas.