QBCore, ESX o standalone: Cómo funcionan los scripts de Agency con tu framework

El problema de compatibilidad con frameworks

La mayoría de los scripts de FiveM vienen codificados para un solo framework. Si usas QBCore, usas scripts de QBCore. Quienes usan ESX se quedan con scripts de ESX. Quienes usan standalone suelen tener que improvisar. Agency Scripts se creó con la filosofía opuesta: el framework es un adaptador, no una suposición.

El patrón de adaptador

Cada script de Agency ofrece un pequeño conjunto de funciones de consulta: getPlayerData, getInventory, addMoney, removeItem, getJob. Incluimos adaptadores que conectan estas funciones con implementaciones de QBCore y ESX, listos para usar. Para standalone, implementas tú mismo las cuatro o cinco funciones, normalmente en una mañana de trabajo, y todos los scripts de Agency serán compatibles.

Qué significa esto en la práctica

Cuando cambias tu servidor de QBCore a ESX, algo que ocurre cada pocos años a medida que evolucionan los frameworks, no hace falta reinstalar ni reconfigurar los scripts de Agency. Cambias el adaptador y todo lo demás sigue funcionando. Esto es muy poco común en el ecosistema de FiveM y es la principal razón por la que los propietarios de servidores estandarizan nuestras herramientas a largo plazo.

Qué significa la etiqueta del framework en nuestras páginas de producto

Cuando una página de producto indica "QBCore, ESX", significa que incluimos adaptadores listos para ambos. Cuando indica "Standalone", significa que el script es independiente del framework, no necesita adaptador y funciona en cualquier servidor. En la práctica, casi todos los scripts de Agency se pueden usar en configuraciones standalone con un pequeño puente de compatibilidad.

Cuándo preguntar antes de comprar

Si tienes una configuración poco habitual, un framework personalizado, un QBCore muy modificado o algo hecho a medida, abre un ticket en nuestro Discord antes de comprar. Te diremos con sinceridad qué funcionará, qué requiere una adaptación menor y qué no vale la pena. Sin presión de venta, preferimos que compres un script que se ajuste a lo que necesitas antes que tres que no.

Cómo funciona el patrón de adaptador en la práctica

Al instalar un script de Agency, la carpeta del recurso contiene un framework subdirectorio con al menos tres archivos: qb.lua, esx.lua, y standalone.lua. El script principal detecta automáticamente qué framework está presente comprobando el export de QBCore o ESX. Se carga el archivo del adaptador correspondiente y los demás no. Esta detección automática ocurre antes de que se ejecute cualquier lógica del juego, no tiene ningún coste adicional en tiempo de ejecución.

Cada adaptador implementa la misma superficie de API interna. Si un script necesita darle dinero a un jugador, llama a Framework.AddMoney(src, amount) internamente. Esa función en qb.lua llama a la exportación de dinero de QBCore; en esx.lua llama al sistema de cuentas de ESX; en standalone.lua llama a la función que hayas definido en config.lua. Una llamada, tres implementaciones, cero cambios en los scripts entre frameworks.

Instalación en QBCore

En los servidores QBCore, la instalación suele constar de tres pasos: descarga el recurso, colócalo en la carpeta resources y añádelo a server.cfg. La detección del framework es automática. Si usas una versión de QBCore muy modificada (sistema de dinero personalizado, inventario personalizado, trabajos personalizados), quizá tengas que sobrescribir funciones específicas del adaptador en config.lua en lugar de editar qb.lua directamente. El método de sobrescritura de la configuración permite conservar los cambios al actualizar los recursos.

Instalación en ESX

La instalación en ESX sigue el mismo patrón. A veces hace falta un paso adicional: si tu versión de ESX es bastante antigua (anterior a la 1.7), algunas funciones del adaptador hacen referencia a nombres de exportación de ESX más recientes. El recurso incluye una opción de compatibilidad con versiones antiguas Config.ESXLegacy = true que cambia a llamadas de la API antigua de ESX en todos los scripts de Agency que la necesitan.

Instalación en Standalone

Standalone es donde históricamente muchos propietarios de servidores han tenido problemas con otros scripts. La opción standalone de Agency Scripts está claramente definida y bien documentada. Para cada script, el archivo del adaptador standalone indica exactamente qué funciones tienes que implementar. La mayoría de los scripts requieren entre cuatro y ocho funciones. Cada función incluye un comentario que explica qué debería devolver. Una implementación típica de standalone lleva entre una y tres horas, según la complejidad de tu sistema personalizado de datos de jugadores.

Cuando hayas implementado el adaptador para un script de Agency, los siguientes te llevarán mucho menos tiempo, ya que las mismas funciones personalizadas suelen servir para varios recursos.

Por qué esto importa para el funcionamiento del servidor a largo plazo

Los frameworks de FiveM no son permanentes. Es probable que los servidores que llevan funcionando tres años o más ya hayan afrontado al menos un cambio importante de framework, quizá migrando de una bifurcación comunitaria de ESX a la versión principal de ESX, o de una versión antigua de QBCore a la actual. Los servidores que dependen de scripts ligados a un framework pagan un alto coste de migración: cada script debe actualizarse o sustituirse cuando el framework cambia de forma significativa.

La arquitectura de adaptadores de Agency Scripts hace que una migración de framework afecte solo a la capa del adaptador. Los datos de Agency-Phone, los registros de Agency-Admin, el historial de transacciones de Agency-Blackmarket y el progreso de los jugadores en Agency-Minerjob se mantienen intactos. Cambias los archivos del adaptador, actualizas config.lua y los scripts siguen funcionando. Este es el verdadero valor a largo plazo del enfoque de compatibilidad: no solo admite varios frameworks, también protege tu servidor frente a la evolución de los frameworks.

Preguntas frecuentes

¿Todos los scripts de Agency usan el mismo patrón de adaptadores?

Sí. Todos los scripts de Agency de pago y la mayoría de los gratuitos usan este patrón. Las únicas excepciones son los recursos exclusivamente de interfaz, como Agency-Loadingscreen y Agency-Notify, que no interactúan con ningún framework y funcionan igual en todas partes.

¿Puedo combinar adaptadores de frameworks? Por ejemplo, ¿usar el sistema de dinero de QBCore y un inventario standalone?

Sí, mediante las sobrescrituras de configuración. Configura la detección de framework como QBCore y luego sobrescribe funciones específicas del adaptador en config.lua para que llamen a tu sistema de inventario personalizado en lugar del de QBCore. El sistema de sobrescrituras existe precisamente para servidores con configuraciones híbridas.

¿Qué pasa si se populariza un framework nuevo que todavía no es compatible?

Abre un ticket de soporte en Discord. Evaluamos las solicitudes de compatibilidad con frameworks nuevos según su adopción en la comunidad. Históricamente, hemos añadido compatibilidad en un plazo de 2-4 semanas para frameworks con comunidades importantes. Mientras tanto, puedes usar la opción standalone como solución temporal con cualquier framework.

¿Se actualizan los adaptadores cuando se actualiza el propio framework?

Sí. Cuando QBCore o ESX publica un cambio incompatible, lanzamos actualizaciones de los adaptadores a los pocos días de la publicación del framework. Los suscriptores activos reciben notificaciones de las actualizaciones a través de Tebex. Esta es una de las razones por las que existe el modelo de suscripción: el mantenimiento de los adaptadores es un trabajo continuo, no un coste único.

Resumen de requisitos por framework

• QBCore, cualquier versión reciente de QBCore. Detección automática, sin configuración para las instalaciones estándar.
• ESX, ESX Legacy 1.7+ o la versión principal de ESX. Activa la opción de compatibilidad con versiones antiguas para las versiones anteriores.
• StandaloneImplementa entre 4 y 8 funciones por script en config.lua. Configuración única, reutilizable en los scripts de Agency.
• Todos los requisitoscuenta de cfx.re con una licencia válida, servidor FiveM con Artifacts 5181 o superior recomendado.