Documentación de Pase de temporada

ov-battlepass

Pase de temporada para qb-core: 250 niveles, carril gratuito y carril VIP, misiones diarias y semanales, cajas con premios, titulos, buzon de recompensas y un panel de administracion independiente (ov-battlepass-admin) incluido en el mismo producto.

Que hace

ov-battlepass da a los jugadores una progresion de temporada. Ganan XP jugando, suben de nivel y reclaman recompensas desde una interfaz propia que se abre con /pase (tecla F7 por defecto).

• 250 niveles por temporada (Config.Season.maxLevel), con curva configurable en tres modos: plana, lineal o tabla nivel a nivel.
• Dos carriles de recompensas: gratuito y VIP. El carril VIP arranca apagado y el administrador decide quien cuenta como VIP (por concesion manual desde el panel, por una tabla externa de perks o ambos).
• Recompensas generadas por plantillas: dinero en efectivo o banco, items de ox_inventory, cajas, entradas a eventos, potenciadores, titulos y desbloqueos propios (ropa, cosmeticos, efectos, disenos) que otros scripts consultan con HasUnlock. Los 500 espacios (250 niveles x 2 carriles) se pueden ajustar nivel por nivel.
• Cajas de premio (ovbp_caja_comun, ovbp_caja_vip, ovbp_caja_elite, ovbp_caja_legendaria) con tablas de loot ponderadas y apertura todo-o-nada desde el inventario.
• Misiones diarias y semanales con contadores, recompensa de XP y reclamo individual o en bloque.
• Motor de XP con lista blanca de fuentes, enfriamientos, topes por hora, tope diario y multiplicadores de fin de semana y de final de temporada. La XP solo entra desde el servidor.
• XP pasiva incluida: por tiempo jugado activo (sin contar AFK), por kilometros a pie y por kilometros conduciendo, medidos por el servidor.
• Buzon: las recompensas que no se pudieron entregar (por ejemplo, inventario lleno) quedan guardadas y el jugador las canjea despues.
• Ranking de temporada en la interfaz y avisos en pantalla de XP, subida de nivel y recompensas.
• Panel de administracion (ov-battlepass-admin): resumen, ajustes en caliente, carril VIP y recompensas, con permisos comprobados siempre en el servidor y registro de acciones.
• API de exports para que otros scripts den XP, sumen contadores y consulten nivel, VIP y desbloqueos.

Requisitos

• Servidor FiveM con qb-core (el recurso usa qb-core para el dinero y los datos del jugador), Lua 5.4 y base de datos MySQL o MariaDB con oxmysql.
• dependencies del fxmanifest.lua de ov-battlepass: ox_lib y oxmysql.
• dependencies de ov-battlepass-admin: ov-battlepass.
• Otros recursos que el codigo usa:
• qb-core (recurso obligatorio en la practica: entrega de dinero y grupo del jugador).
• ox_inventory: para entregar items, cajas, entradas y potenciadores, y para abrir las cajas desde el inventario.
• La tabla externa de perks (solo lectura) si eliges el criterio VIP por perks; es opcional y se configura desde el panel.
• Las cajas necesitan que declares 4 items en ox_inventory (ver Instalacion).

Instalacion

El recurso viene protegido con Asset Escrow de Cfx.re: se descarga del Portal de Cfx.re con la cuenta Cfx.re del comprador y solo funciona en servidores de esa cuenta. Segun el fxmanifest.lua de ov-battlepass, quedan sin cifrar la interfaz (html/), los archivos config/config.lua, config/config_admin.lua, config/config_crates.lua, config/config_levels.lua, config/config_missions.lua, config/config_rewards.lua, config/config_xp.lua y locales/es.lua. El panel ov-battlepass-admin deja sin cifrar su carpeta nui/.

1. Descarga el recurso desde el Portal de Cfx.re y copia las carpetas ov-battlepass y ov-battlepass-admin en resources/.
2. Base de datos: no hace falta importar nada. Al arrancar, el recurso crea sus 14 tablas con prefijo ov_battlepass_ (CREATE TABLE IF NOT EXISTS). La carpeta sql/ incluye 01_schema.sql solo como copia de cortesia para revisarlo o aplicarlo a mano. El comando de consola ovbp esquema comprueba que las tablas existan.
3. Declara en ox_inventory (archivo data/items.lua) los items de las cajas ovbp_caja_comun, ovbp_caja_vip, ovbp_caja_elite y ovbp_caja_legendaria, con consume = 1 y server = { export = 'ov-battlepass.openCrate' }. El recurso incluye las imagenes en html/img/ (ovbp_caja_*.png); copialas a las imagenes de tu inventario si quieres el icono en la mochila. Los nombres de los items de premio de config/config_crates.lua tambien deben existir en tu ox_inventory; los que falten se descartan del sorteo y se avisa en consola.
4. Agrega en server.cfg (despues de sus dependencias y de qb-core): `` ensure oxmysql ensure ox_lib ensure qb-core ensure ox_inventory ensure ov-battlepass ensure ov-battlepass-admin ``
5. Concede el permiso de administracion (ACE por defecto ov.battlepass): `` add_ace group.admin ov.battlepass allow ` Tambien tienen acceso los jugadores cuyo grupo de qb-core este en Admin.groups (por defecto god y admin`).
6. Ajusta las fechas de la temporada en config/config.lua (Config.Season.startsAt y endsAt; los valores incluidos son de ejemplo) y reinicia el servidor.
7. Este recurso no lee convars del server.cfg.

Configuracion

Los archivos de config/ sirven de semilla en la primera arrancada. Los ajustes que cambies despues desde el panel o con /pasead se guardan en la tabla ov_battlepass_settings y mandan sobre lo escrito en los archivos.

config/config.lua

config/config_levels.lua: Levels.mode = 'flat' (opciones flat, linear, table) y Levels.flat.xpPerLevel = 2000. El progreso se guarda como XP total, asi que cambiar la curva recalcula los niveles de todos.

config/config_xp.lua

config/config_missions.lua: Missions.dailyCount = 5, Missions.weeklyCount = 4, Missions.deterministicSeed = true, y los pools Missions.daily y Missions.weekly (una mision nueva es una fila con id, label, desc, counter, target, xp, icon).

config/config_rewards.lua: Rewards.templates (plantillas por tipo de nivel), Rewards.pattern (hitos 50/100/150/200, nivel 250 y una caja cada 10 niveles), Rewards.overrides (ajustes nivel a nivel) y Rewards.vip (valores iniciales del carril VIP: trackEnabled = false, mode = 'disabled').

config/config_crates.lua: CrateLoot.settings (cooldownMs = 1500, maxRolls = 10) y CrateLoot.boxes, con guaranteed, rolls y pool ponderado por caja.

config/config_admin.lua: Admin.ace = 'ov.battlepass', Admin.groups = { 'god', 'admin' }, Admin.command = 'pasead', Admin.bootCommand = 'ovbp', Admin.requireBothChecks = false, Admin.maxManualXp = 100000, Admin.allowSetLevel, Admin.allowRevokeClaims, Admin.logAllActions = true.

Comandos y permisos

Jugadores

Administracion (ACE ov.battlepass o grupo en Admin.groups; la consola siempre puede)

Exports del servidor (los usan otros scripts): AddXp(ref, fuente, opciones), AddCounter(ref, contador, delta), AddDistance(ref, metros, velocidad, esConductor), GetCounter, GetProgress, GetLevel, GetTotalXp, HasLevel, IsVip, GetUnlocks, HasUnlock(ref, tipo, id), GetSnapshot, GetMultiplier, GetDailyCap, GetSources, CanUseSource, IsReady, GetMissions, GetMissionSummary, GetMissionPools, GetClaimSummary, GetMailbox, OpenCrate, y el gancho de inventario openCrate. Tambien hay eventos de servidor (sin RegisterNetEvent, un cliente no puede dispararlos): ov-battlepass:server:addXp y ov-battlepass:server:addCounter, ademas de ov-battlepass:server:crateOpened que se emite al abrir una caja. Ejemplo:

exports['ov-battlepass']:AddXp(source, 'job_complete')
exports['ov-battlepass']:AddCounter(source, 'locations_visited', 1)

Exports del cliente: GetState, GetProgress, GetLevel, IsVip, GetMissions, OpenPass, ClosePass, IsPassOpen. El evento de cliente ovbp:client:open (y close, toggle) permite abrir el pase desde otro menu.

Como se usa

1. El jugador abre el pase con /pase o F7 y ve su nivel, su XP y las tarjetas de recompensa de cada carril.
2. Gana XP jugando: tiempo activo, caminando, conduciendo y con las acciones que tu servidor conecte a AddXp (trabajos, entregas, carreras, eventos, etc.).
3. Al subir de nivel, la recompensa pasa a estar disponible; el jugador la reclama desde la tarjeta o con "reclamar todo".
4. Las cajas se entregan al inventario y se abren usandolas; si no cabe todo el loot, la caja no se abre y se conserva.
5. En la seccion de misiones, el jugador completa las diarias y semanales y reclama su XP.
6. Si una recompensa no se pudo entregar, queda en el buzon para canjearla despues.
7. Los hitos (niveles 50, 100, 150, 200 y 250) otorgan titulos.

Para administradores

• Poner en marcha una temporada: ajusta Config.Season (fechas, codigo y nombre) y usa /ovbp temporada estado, /ovbp temporada activar [code] y /ovbp temporada cerrar [code]. Lo ya entregado se conserva al cerrar.
• Encender el carril VIP: el carril VIP arranca apagado. Desde el panel (/paseadmin, pestana "Carril VIP") o con /pasead vip on, elige el criterio (manual para concesiones propias del panel, perks para leer una tabla externa, any para ambos) y concede VIP con /pasead vip dar.
• Cambiar recompensas: el panel permite editar el contenido de un nivel y carril sin tocar archivos; /pasead recompensa limpiar devuelve ese nivel al valor de la configuracion.
• Ajustes en caliente: la pestana "Ajustes" muestra y modifica los ajustes guardados; defecto devuelve un ajuste a su valor inicial.
• Dar XP manualmente: /ovbp xp [id] [cantidad] (cantidad negativa para restar; tope por operacion en Admin.maxManualXp).
• Conectar tus scripts de trabajo: el pase solo da XP desde las fuentes declaradas en config_xp.lua. Para que un trabajo de tu servidor de XP, llama a exports['ov-battlepass']:AddXp(source, 'job_complete') (o la fuente que corresponda) desde el servidor, nunca desde el cliente.
• Diagnostico: /ovbp validar revalida la configuracion y muestra errores y avisos; si hay un error grave el pase entra en modo seguro y lo indica en consola.

Preguntas frecuentes

Necesito importar el SQL? No. Las tablas se crean al arrancar. sql/01_schema.sql es solo una copia de cortesia.

El jugador no recibe XP por sus trabajos. Solo dan XP por si solos el tiempo activo, los kilometros a pie y los kilometros conduciendo. El resto de fuentes (trabajos, entregas, eventos...) requieren que tu script llame a AddXp.

La temporada aparece cerrada o no suma XP. Revisa que las fechas de Config.Season incluyan el dia actual y usa /ovbp temporada estado. Las fechas incluidas son de ejemplo.

Las cajas no se abren. Comprueba que declaraste los items ovbp_* en ox_inventory con el export ov-battlepass.openCrate y que los items de premio existan; la consola avisa de los que falten.

Puedo cambiar el numero de niveles o su coste? Si: Config.Season.maxLevel y config/config_levels.lua. Al cambiar la curva, los niveles se recalculan desde la XP total.

Como veo los errores? En la consola del servidor, con el prefijo [ov-battlepass]; /ovbp validar repite la validacion de la configuracion.

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re y en la tienda. Antes de actualizar, guarda una copia de la carpeta config/ y de tus ajustes. Los ajustes hechos desde el panel viven en la base de datos y no se pierden al reemplazar el recurso. Para soporte, abre un ticket en el Discord de la tienda: [enlace de soporte]. Indica las versiones de ov-battlepass (0.3.0 en el manifest actual) y ov-battlepass-admin (1.0.0), y el mensaje de la consola.