Documentación de Sistema VIP

ov_vip

Sistema VIP por niveles para qb-core: dinero inicial, armas, vehiculos, kit, salario, bono de velocidad, zona de pruebas y proteccion contra duplicacion de armas, todo desde un menu con /vip.

Que hace

ov_vip administra membresias VIP con fecha de caducidad y entrega a cada nivel un paquete de beneficios configurable. Los jugadores lo manejan desde un menu (NUI) que se abre con /vip; el personal lo otorga y retira con comandos.

Siete niveles ya configurados en Config.Niveles: pvp, elitepvp, bronce, silver, gold, diamond y lanzamiento, cada uno con su dinero inicial, cupo de armas, cupo y categorias de vehiculos, salario, bono de velocidad y comandos incluidos.
Dinero inicial y bonos que se pagan al recibir el VIP o al reclamar el arma.
Reclamo de armas desde el menu, con numero de serie unico por arma registrado en un libro contable en la base de datos, municion cargada de serie y reposicion de armas perdidas.
Reclamo de vehiculos por nivel y categoria: se inserta en player_vehicles con patente nueva y se entrega en un garaje.
Kit (/kit) con espera configurable, y comandos de apariencia (/ropa, /peluqueria, /armario) y efecto de neones /rgb segun el nivel.
Salario periodico al banco para los niveles que lo tienen, y bono de velocidad en vehiculos.
Zona de pruebas aislada (routing bucket propio) para probar armas y vehiculos antes de reclamarlos.
Fabricacion de municion y reparacion de armas VVS (con minijuego de ox_lib).
Antiduplicacion: hooks sobre ox_inventory, bloqueo de traspaso de armas, auditor automatico y registro de auditoria.
Caducidad automatica: al terminar el VIP se retira lo concedido (armas, municion del reclamo y objetos no consumibles del kit); el dinero cobrado y los vehiculos entregados se conservan.
API de exports para otras partes del servidor (tienda, panel de staff, trabajos).

Requisitos

Servidor FiveM con framework qb-core, Lua 5.4 y base de datos MySQL o MariaDB con oxmysql.
dependencies del fxmanifest.lua: qb-core, ox_inventory, ox_lib, oxmysql.
Otros recursos que el codigo usa o espera:
illenium-appearance: los comandos /ropa, /peluqueria y /armario abren sus menus; si no esta iniciado, el jugador recibe un aviso de que no esta disponible.
Tablas player_vehicles y garage_locations (esta ultima, de jg-advancedgarages): la entrega de vehiculos escribe en player_vehicles y busca el garaje de destino en garage_locations. Sin un garaje valido, el reclamo se rechaza.
0r-vehiclekeys (opcional): si esta iniciado, entrega las llaves al probar un vehiculo.
routing-fix (opcional): el recurso le avisa con eventos al abrir y cerrar sesiones de prueba.
ov_cola (opcional): comparte la prioridad VIP en la cola de conexion (ver Config.EventosCompatCola).
Los items de armas del catalogo (shared/armas.lua, 178 entradas) y los items del kit deben existir en ox_inventory; las armas o items que no existan se omiten y se avisa en consola. Los modelos de las armas VVS y de los vehiculos del catalogo son recursos aparte que tu servidor debe tener.

Instalacion

El recurso viene protegido con Asset Escrow de Cfx.re: se descarga desde el Portal de Cfx.re con la cuenta Cfx.re del comprador y solo funciona en servidores de esa cuenta. Segun su fxmanifest.lua, quedan sin cifrar shared/config.lua, shared/locale.lua y la carpeta web/ (la interfaz). Nota: shared/armas.lua (el catalogo de armas) si esta cifrado, por lo que el catalogo no se edita a mano.

Descarga el recurso desde el Portal de Cfx.re y copia la carpeta ov_vip en resources/.
Base de datos: las tablas ov_vip, ov_vip_armas, ov_vip_auditoria, ov_vip_vehicle_claims, ov_vip_vehicle_catalog y ov_vip_cooldowns se crean solas al arrancar (CREATE TABLE IF NOT EXISTS). Tambien se incluye sql/ov_vip.sql por si prefieres crearlas a mano. La carpeta sql/ incluye ademas un archivo de migracion opcional y manual desde otro sistema VIP; no se ejecuta sola y solo tiene sentido si ya usabas ese sistema con los mismos citizenid.
Agrega en server.cfg (despues de sus dependencias): `` ensure oxmysql ensure ox_lib ensure qb-core ensure ox_inventory ensure ov_vip ``
Concede el permiso de administracion a tu grupo de admins (permiso ACE por defecto ov_vip.admin): `` add_ace group.admin ov_vip.admin allow ``
Opcional: define la convar ov_admin_log_webhook en el server.cfg con el webhook de Discord donde quieras recibir los avisos de la auditoria (el recurso la lee con GetConvar). Si no la defines, simplemente no se envian avisos a Discord.
Opcional: si vas a usar Config.AceVip (permisos ACE temporales mientras el jugador tenga VIP), agrega tambien add_ace resource.ov_vip command.add_ace allow y add_ace resource.ov_vip command.remove_ace allow.
Revisa en shared/config.lua los items del kit, el catalogo de vehiculos (Config.CatalogoVehiculos), el garaje por defecto y las coordenadas de la zona de pruebas, y reinicia el servidor.

Configuracion

Todo en shared/config.lua.

Clave	Valor por defecto	Para que sirve
`Config.Comando`	`'vip'`	Comando que abre el menu.
`Config.PermisoAdmin`	`'ov_vip.admin'`	Permiso ACE de los comandos de administracion.
`Config.DiasPorDefecto`	`30`	Dias que otorga `/darvip` si no se indican.
`Config.DiasMaximo`	`3650`	Maximo de dias por otorgamiento.
`Config.SalarioIntervaloMin`	`60`	Cada cuantos minutos se paga el salario (al banco).
`Config.RevisionCaducidadSeg`	`60`	Cada cuantos segundos se revisan los VIP caducados.
`Config.EsperaReclamo`	`3`	Segundos de espera entre dos reclamos del mismo jugador.
`Config.KitCooldown`	`1800`	Segundos entre usos de `/kit`.
`Config.KitItems`	radio, kit de reparacion, 2 botiquines, 3 vendas, 2 aguas, 2 sandwiches	Contenido del kit (`item`, `count`, `noConsumible`).
`Config.VelocidadExtra.activo`	`true`	Activa el bono de velocidad en vehiculos.
`Config.BonoFarmeo.activo`	`false`	Solo expone el export `GetFarmeoBonus`; otro script debe usarlo para tener efecto.
`Config.Rgb`	`activo = true`, `intervaloMs = 450`	Efecto `/rgb` de neones.
`Config.AceVip`	`{}`	Permisos ACE concedidos mientras el jugador tenga VIP.
`Config.EventosCompatCola`	`true`	Emite eventos de prioridad de cola al otorgar o quitar VIP.
`Config.BloquearArmasComunes`	`true`	Bloquea tambien las armas comunes (una sola copia por serie, siempre en el inventario de su dueno).
`Config.Antidupe.auditoriaMin`	`20`	Minutos entre auditorias automaticas (`0` las apaga).
`Config.Antidupe.accionFuera`	`'borrar'`	Que hacer con un arma bloqueada fuera del inventario de su dueno (`'borrar'` o `'reportar'`).
`Config.Antidupe.accionHuerfana`	`'borrar'`	Que hacer con un item con marcas VIP que no esta en el libro contable.
`Config.Antidupe.mismaLicencia`	`'avisar'`	Varios personajes de una licencia: `'avisar'` o `'bloquear'`.
`Config.Antidupe.maxReposiciones`	`20`	Tope de reposiciones de una misma arma por periodo VIP.
`Config.ZonaPruebas.duracionArma`	`60`	Segundos de la prueba de arma.
`Config.ZonaPruebas.duracionVehiculo`	`120`	Segundos de la prueba de vehiculo.
`Config.ZonaPruebas.municionPrueba`	`250`	Municion durante la prueba.
`Config.ZonaPruebas.arma` / `.vehiculo`	coordenadas `x, y, z, w`	Donde aparece el jugador y el vehiculo de prueba.
`Config.GarajePorDefecto`	`nombre = 'GARAGE CENTRAL'`, `tipo = 'car'`	Garaje de entrega si el jugador no tiene vehiculos guardados.
`Config.CatalogoVehiculos`	4 modelos de ejemplo	Catalogo base de vehiculos VIP.
`Config.CategoriasVehiculo`	START, ELITE, COLECCIONABLE, BLINDADO_32, FULL_BLINDADO, ABUSER, LANZAMIENTO, BRONCE	Categorias validas para el catalogo.
`Config.Crafteo`	`cooldown = 1800`, `maxMunicion = 2000`	Fabricacion de municion para armas VVS.
`Config.Reparacion.cooldown`	`1800`	Segundos entre reparaciones de armas.
`Config.Niveles`	7 niveles	Por nivel: `dineroInicial`, `velocidad`, `salario`, `comandos`, `armas`, `vehiculos`, `crafteoMunicion`.

Valores por nivel (leidos de Config.Niveles):

Nivel	Dinero inicial	Armas (cupo)	Vehiculos (cupo)	Velocidad	Salario
pvp	100000	1	0	0	0
elitepvp	100000	1	0	0	0
bronce	1000000	4	1	3	5000
silver	500000	7	1	3	0
gold	1000000	1	2	5	15000
diamond	2000000	1	3	7	25000
lanzamiento	1000000	1	1	0	0

Comandos y permisos

Jugadores

Comando	Efecto
`/vip`	Abre el menu (sin VIP muestra los niveles).
`/kit`	Entrega el kit (con espera).
`/ropa`, `/peluqueria`, `/armario`	Abren la tienda de ropa, la peluqueria y el armario (via `illenium-appearance`), segun lo que incluya el nivel.
`/rgb`	Neones del vehiculo en ciclo de color (niveles que lo incluyen, por defecto gold y diamond).

Administracion (permiso ACE ov_vip.admin; desde la consola del servidor siempre se puede)

Comando	Efecto
`/darvip [id] [nivel] [dias]`	Otorga el VIP. Acepta alias de nivel (`bronze`, `plata`, `oro`, `diamante`, `elite`, `elite-pvp`).
`/quitarvip [id]` o `/quitarvip cid:[citizenid]`	Quita el VIP y retira lo concedido; con `cid:` funciona con personajes desconectados.
`/vipcatalogo`	Con `listar`, `agregar <modelo> <categoria> <nombre>` y `quitar <modelo>` administra el catalogo de vehiculos.
`/vipzona`	Imprime tu posicion para configurar la zona de pruebas.
`/vipauditar [simular]` o `/vipauditar jugador [id]`	Ejecuta la auditoria antiduplicacion; `simular` solo informa.

Exports del servidor: IsVIP(citizenid), GetVIPLevel(citizenid), GetVIPInfo(source), HasVIPCommand(source, comando), GetSpeedBoost(source), GetFarmeoBonus(source), GrantVIP(source, nivel, dias, quien) y RevokeVIP(source, quien).

Eventos del servidor al otorgar o quitar: ov_vip:granted y ov_vip:revoked (reciben citizenid, source, nivel). Con Config.EventosCompatCola activo tambien se emiten con un nombre de compatibilidad que escucha ov_cola para la prioridad en la cola de conexion.

Como se usa

Un administrador otorga el VIP con /darvip. El jugador recibe el dinero inicial y un aviso.
El jugador escribe /vip para ver su nivel, la fecha de caducidad y sus beneficios.
Armas: elige un arma del catalogo de su nivel y la reclama. Puede probarla antes en la zona de pruebas. Si la pierde, la recupera desde el menu.
Vehiculos: elige un modelo de su cupo y lo reclama; aparece en su garaje. Tambien puede hacer un test drive.
Kit: /kit entrega los items del kit si no esta en espera.
Municion y reparacion: para armas VVS, el menu permite fabricar municion (minijuego) y reparar el arma, con esperas entre usos.
El salario llega al banco cada Config.SalarioIntervaloMin minutos mientras el jugador esta conectado y su VIP esta vigente.
Cuando el VIP caduca, el jugador recibe un aviso y se retira lo concedido que no sea permanente.

Para administradores

Otorgar o quitar VIP: /darvip [id] [nivel] [dias] y /quitarvip. Cada otorgamiento queda anotado con quien lo hizo.
Vehiculos VIP: agrega modelos con /vipcatalogo agregar <modelo> <categoria> <nombre>. El modelo debe existir en tu servidor (el recurso lo verifica con un jugador conectado). Los niveles solo ven las categorias que tienen asignadas en Config.Niveles[...].vehiculos.categorias.
Zona de pruebas: ponte en la posicion deseada y usa /vipzona; copia las coordenadas a Config.ZonaPruebas.arma y .vehiculo.
Antiduplicacion: el auditor revisa inventarios, maleteros, guanteras, stashes y suelo cada Config.Antidupe.auditoriaMin minutos. Usa /vipauditar simular para ver hallazgos sin retirar nada. Los hallazgos se guardan en la tabla ov_vip_auditoria y, si definiste ov_admin_log_webhook, se avisan por Discord.
Cambiar un cupo o beneficio: edita el nivel en Config.Niveles y reinicia el recurso. Los textos del menu se generan desde esa misma configuracion.
Ver errores: la consola del servidor muestra avisos con el prefijo [ov_vip], por ejemplo items del kit o armas que no existen en ox_inventory.

Preguntas frecuentes

Necesito crear las tablas a mano? No. El recurso las crea al arrancar. sql/ov_vip.sql es opcional.

Funciona sin illenium-appearance? Si, pero /ropa, /peluqueria y /armario mostraran un aviso de no disponible.

Un arma del catalogo no aparece en el menu. Solo aparecen las armas cuyo item existe en ox_inventory. Revisa la consola al iniciar: se avisa de las que faltan.

No puedo reclamar un vehiculo. Revisa que el nivel tenga cupo (pvp y elitepvp tienen 0), que la categoria tenga modelos en el catalogo y que exista un garaje valido en garage_locations (por defecto GARAGE CENTRAL, tipo car).

Como cambio los dias maximos o el kit? Config.DiasMaximo y Config.KitItems en shared/config.lua.

Pierde el jugador el dinero o los vehiculos cuando acaba el VIP? No. Se retiran las armas, la municion del reclamo y los objetos no consumibles del kit; el dinero cobrado y los vehiculos ya entregados se conservan.

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re y en la tienda. Antes de actualizar, guarda una copia de tu shared/config.lua. Para soporte, abre un ticket en el Discord de la tienda: [enlace de soporte]. Indica la version del recurso (1.1.0 en el manifest actual), el error de la consola y la version de ox_inventory y qb-core.