Agency-ProgressBar: el detalle de interfaz que mejora discretamente cada script

Un script pequeño, un impacto enorme

Las barras de progreso aparecen por todas partes en FiveM: forzar cerraduras, reparar, blanquear dinero, minar, prestar asistencia médica. Las implementaciones predeterminadas son funcionales, pero simples. Agency-ProgressBar es nuestra propuesta de cómo debería sentirse esta utilidad cuando alguien se preocupa por los detalles.

Anatomía de una buena barra de progreso

Una buena barra de progreso comunica cuatro cosas al mismo tiempo: qué acción está ocurriendo, cuánto has avanzado, cuánto tiempo queda y si puedes cancelar. La mayoría de las implementaciones solo cubren las dos primeras. Agency-ProgressBar muestra las cuatro, con animaciones sutiles que hacen que el progreso se vea fluido, no entrecortado.

Una cancelación que funciona

Cuando el jugador cancela la acción, se activa una breve animación de desvanecimiento que reduce la opacidad de la barra a cero en 300ms. No desaparece de golpe. Los desarrolladores pueden registrar una función de callback de cancelación para que los scripts hagan la limpieza necesaria cuando los jugadores abandonan una acción a mitad del progreso.

Posicionamiento contextual

La barra aparece cerca del elemento relevante en pantalla: sobre tu cabeza para las acciones dirigidas a ti y sobre el NPC objetivo para las acciones interactivas. Ya no tienes que mirar el estado de la acción en la parte inferior de la pantalla mientras algo sucede arriba. Este sutil cambio de UX es algo que los jugadores notan, aunque no sepan cómo describirlo.

El patrón de exports

Como todos nuestros scripts de utilidades, Agency-ProgressBar ofrece una API sencilla de exports: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone})Instálalo en cualquier script en cuestión de minutos. Se integra con Agency-Notify, Agency-Hud y el resto de nuestro ecosistema sin ninguna configuración especial.

Instalación y configuración

Agency-ProgressBar es una utilidad lista para instalar, sin dependencias de bases de datos. Descárgalo desde Tebex, coloca la carpeta en el directorio de resources y añade ensure agency-progressbar a server.cfgEso es todo. El recurso empieza a funcionar de inmediato y cualquier script puede llamar a la API de exports después del siguiente reinicio.

Si vas a reemplazar una barra de progreso existente (progressBar de ox_lib, qb-progressbar, etc.), buscar y reemplazar el nombre de la llamada export suele resolver la mayoría de las migraciones en minutos. La estructura de parámetros está diseñada para parecerse a los patrones habituales de la comunidad.

Opciones de configuración

Abre config.lua para ajustar los valores predeterminados:

• Posición predeterminada, sobre la cabeza del jugador (predeterminada) o fija en el centro inferior.
• Esquema de colorel gradiente de color del relleno. Admite un solo color, un gradiente de dos tonos o colores asignados según la gravedad (verde para normal, naranja para lento y rojo para crítico).
• Tecla de cancelación, la tecla que cancela una barra de progreso cancelable. Predeterminada: retroceso.
• Animación de cancelación, desvanecimiento (predeterminada), salida deslizante o desaparición instantánea.
• Visualización del tiempo, muestra los segundos restantes (predeterminada), el porcentaje o nada.
• Duración mínima, las acciones que duren menos que este límite omiten la barra por completo. Valor predeterminado: 500ms.

Compatibilidad con frameworks

Agency-ProgressBar es totalmente standalone y no tiene dependencias de frameworks. Funciona igual en QBCore, ESX y configuraciones de servidor personalizadas. La API de exports es el único punto de integración: no hay variables globales compartidas, eventos de frameworks ni comprobaciones de permisos. Instálalo y llámalo desde cualquier script, independientemente de su origen.

Por qué esto importa para el roleplay

Las barras de progreso son un elemento básico de UX que aparece en decenas de momentos del juego: forzar cerraduras, esposar, fabricar, curar, recoger pruebas y hackear. Cuando esas barras tienen un aspecto distinto o se comportan de forma incoherente entre diferentes scripts, generan un ruido visual sutil que perjudica la coherencia del servidor.

Cuando todas las barras de progreso de tu servidor usan Agency-ProgressBar, el lenguaje visual es uniforme. Los jugadores aprenden intuitivamente qué significa la barra y cómo se comporta. La cancelación funciona siempre de la misma manera. La tipografía coincide con el resto de tu interfaz. Son detalles pequeños, pero en conjunto hacen que la experiencia de juego sea notablemente más pulida.

El posicionamiento contextual importa más de lo que parece. Una barra anclada a la cabeza de tu personaje mientras fuerzas una cerradura mantiene tu atención en la acción, no en una esquina de la pantalla. En momentos tensos, por ejemplo, si te persiguen mientras fuerzas una cerradura, esto ayuda a que los jugadores mantengan la orientación espacial mientras la barra está visible.

Preguntas frecuentes

¿Puedo ejecutar varias barras de progreso al mismo tiempo?

Sí. Cada Play() llamada devuelve un ID y gestiona su propio estado. Las barras se apilan verticalmente sobre el jugador con un espaciado adecuado. Esto resulta útil para acciones de varios pasos en las que hay que ver al mismo tiempo el progreso de tareas en paralelo, aunque en la mayoría de las situaciones de RP solo se usa una barra a la vez.

¿Cómo puedo adjuntar una barra de progreso a un objeto o NPC en lugar de al jugador?

Pasa un campo target = {type = 'entity', id = entityNetId} en la tabla de opciones. La barra aparece sobre la entidad especificada, en lugar de sobre el jugador. Úsalo para acciones de reparación, acciones médicas con jugadores abatidos o cualquier situación en la que el foco de la acción esté en otro elemento.

¿Se puede hacer que la barra no se pueda cancelar desde el servidor?

Sí. Configura canCancel = false al llamar a Play(). La tecla de cancelación no tiene efecto y no se reproduce ninguna animación de cancelación. Esto es adecuado para acciones impuestas por el servidor, como animaciones de arresto o escenas cinemáticas con guion, en las que una interrupción del jugador rompería el flujo.

¿Funciona con las animaciones de ox_lib?

Sí. Agency-ProgressBar no depende de ningún sistema de animaciones: gestionas las animaciones en tu propio script junto con la llamada a la barra de progreso. La barra es únicamente un elemento de la interfaz. Puedes combinarla con cualquier biblioteca de animaciones o con llamadas directas a las animaciones de FiveM, de forma independiente.

Requisitos

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

Ejemplos prácticos de integración

Estos son algunos patrones habituales para integrar Agency-ProgressBar con scripts existentes:

Ganzuado: Llama a Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) al iniciar un intento de ganzuado. Combínalo con el minijuego de ganzuado, que se ejecuta en paralelo. Si el minijuego falla, llama a Dismiss() con el ID devuelto. Si tiene éxito, deja que la barra termine con normalidad.

Tratamiento médico: Usa target = {type = 'entity', id = patientNetId} para situar la barra encima del paciente en lugar del paramédico. Los jugadores que observan la escena ven el progreso en el punto del tratamiento, no sobre la cabeza del paramédico.

Recogida de pruebas: Configura canCancel = false para la recogida de pruebas con guion que no debería poder interrumpirse, por ejemplo, para evitar que los jugadores cancelen y no dejen huellas en la escena. La barra que no se puede cancelar comunica al jugador que esta acción es obligatoria, no opcional.

Acciones del servidor: Muestra una barra de progreso en el cliente mientras se ejecuta una acción del servidor de forma asíncrona. Cuando se recibe la respuesta del servidor, deja que la barra termine o descártala antes, según el resultado del servidor. La duración visual debería aproximarse al tiempo de procesamiento esperado del servidor.