Documentación de Transporte de vehículos

OV Transporte de Vehículos

Sistema universal para cargar motos y vehículos en pickups, grúas, plataformas (flatbed) y rollbacks, con ajuste de posición en pantalla y offsets que se guardan por combinación de vehículos.

Que hace

OV Transporte de Vehículos permite a un jugador subir un vehículo (carga) sobre otro vehículo transportador y bajarlo después.

Tipos de transportador configurables: pickup / batea, flatbed / plataforma, grúa y rollback. Cada tipo define qué modelos lo componen, qué clases de vehículo admite, el punto de enganche, la posición inicial de la carga y el lugar donde se deja al descargar.
Clasificación automática de la carga por la clase del vehículo del juego (moto, bicicleta, carro, furgoneta, utilitario, camión, emergencia, militar) más una lista de modelos "quad".
Ajuste en pantalla: antes de confirmar, el jugador mueve y rota el vehículo cargado con el teclado hasta dejarlo bien colocado.
Offsets guardados: el jugador puede guardar la posición ajustada para esa combinación transportador + carga; se reutiliza automáticamente a partir de entonces para todos los jugadores.
Validación en el servidor: el servidor comprueba que el transportador sea válido, que no esté ocupado, que la carga no esté ya en uso y que su clase sea compatible; incluye un control anti-spam de 2 segundos por jugador.
Descarga del vehículo conduciendo el transportador o apuntando a él.
Permisos opcionales por trabajo o por ítem.
Exports para consultar el estado desde otros scripts.

El producto se basa en un sistema de un vehículo por transportador (maxAttached = 1).

Requisitos

Dependencias declaradas en el fxmanifest.lua:

qb-core
ox_lib

Otros datos:

Lua 5.4 (lua54 'yes').
No usa base de datos. Los offsets guardados van a un archivo (data/offsets.json).
Para la opción de exigir un ítem (Config.Permissions.requireItem), el código comprueba el ítem con el export Search de origen_inventory. Si usas otro inventario, utiliza el permiso por trabajo (allowedJobs) o deja Config.Permissions.enabled = false.

Instalacion

Descarga el recurso desde el Portal de Cfx.re con la cuenta Cfx con la que lo compraste. Viene protegido con Asset Escrow de Cfx.re y funciona solo en servidores de tu cuenta.
Copia la carpeta ov_vehicletransport en resources.
Añade en server.cfg, después de qb-core y ox_lib:

   ensure ox_lib
   ensure qb-core
   ensure ov_vehicletransport

Si algún transportador de tu servidor es un vehículo personalizado, añade su modelo en config.lua (ver "Configuración").
Reinicia el servidor. En la consola verás cuántos offsets personalizados se han cargado.

Protección y edición: según el fxmanifest.lua, solo config.lua queda sin cifrar (escrow_ignore). El resto del código está cifrado, por lo que toda la personalización se hace desde config.lua. El archivo data/offsets.json lo escribe el propio recurso al guardar offsets. No hay interfaz web, no requiere base de datos, no lee convars de server.cfg y no usa permisos ACE.

Configuracion

Se edita en config.lua.

Clave	Valor por defecto	Para qué sirve
`Config.Debug`	`false`	Muestra información de depuración en consola.
`Config.CarrierSearchRadius`	`15.0`	Radio para encontrar el transportador desde el jugador.
`Config.CargoSearchRadius`	`18.0`	Radio para encontrar la carga desde el transportador.
`Config.NetworkControlTimeout`	`8000`	Milisegundos máximos para obtener el control de red de un vehículo.
`Config.Keys`	`confirm = 'e'`, `cancel = 'x'` (también `gizmoDone = 'e'`, `saveOffset = 'g'`)	Teclas registradas como "key mapping" que el jugador puede reasignar en los ajustes de FiveM.
`Config.NotifyDriver`	`"qb"`	`"qb"` usa las notificaciones de QBCore; `"chat"` usa el chat.
`Config.Permissions.enabled`	`false`	Si es `true`, se exige trabajo o ítem para usar el sistema.
`Config.Permissions.allowedJobs`	`{ "mechanic", "police" }`	Trabajos que pueden usarlo.
`Config.Permissions.requireItem` / `item`	`false` / `"tow_strap"`	Permite el uso a quien tenga el ítem indicado.
`Config.CarrierTypes`	`pickup`, `flatbed`, `towtruck`, `rollback`	Tipos de transportador: `label`, `models`, `allowedCargoClasses`, `allowedCargoModels`, `maxAttached`, `defaultOffset`, `boneToAttach` y `dropOffset`.
`Config.CarrierTypes.pickup.allowedCargoClasses`	`motorcycle`, `bicycle`, `quad`	Qué admite una pickup.
`Config.CarrierTypes.flatbed.allowedCargoClasses`	`car`, `motorcycle`, `van`, `utility`, `emergency`	Qué admite una plataforma.
`Config.CarrierTypes.towtruck.allowedCargoClasses`	`car`, `motorcycle`, `van`, `utility`	Qué admite una grúa.
`Config.CarrierTypes.rollback.models`	vacío	Lista de modelos de rollback; añade los de tu servidor.
`Config.ClassMapping`	tabla clase del juego a categoría	Cómo se clasifica cada clase de vehículo.
`Config.QuadModels`	`blazer`, `sanchez`, `manchez` y variantes	Modelos tratados como quad.
`Config.CargoModelOverrides`	vacío	Fuerza la categoría de un modelo concreto (`["modelo"] = "motorcycle"`).
`Config.DefaultOffsets`	vacío	Posiciones predefinidas por combinación. La clave es `modeloTransportador_modeloCarga` en minúsculas.
`Config.UseCustomOffsets`	`true`	Usa los offsets guardados en `data/offsets.json` (tienen prioridad sobre `DefaultOffsets`).

Cada offset tiene seis valores: x, y, z (posición) y rx, ry, rz (rotación).

Ejemplo para añadir un modelo propio:

Config.CarrierTypes.flatbed.models = {
    "flatbed", "flatbed2", "flatbed5",
    "mi_plataforma",
}

Comandos y permisos

Comando	Qué hace
`/transportarveh`	Detecta transportador y carga. Si el jugador conduce un transportador con carga, la descarga.
`/cargarmoto`	Alias de `/transportarveh`.
`/cargarcarro`	Alias de `/transportarveh`.
`/descargarveh`	Descarga el vehículo del transportador que conduce o al que apunta.
`/transportdiag`	Escribe en la consola del cliente (F8) un diagnóstico: vehículo al que apuntas, si es transportador y los vehículos cercanos.

Teclas durante el flujo de carga (el ajuste de posición usa estas teclas fijas):

Acción	Tecla
Mover adelante / atrás del transportador	Flechas izquierda y derecha
Subir / bajar	Flechas arriba y abajo
Mover a los lados	Q (izquierda) y el control 82 del juego, la coma por defecto (derecha)
Rotar	Rueda del ratón
Movimiento fino	Mantener Shift
Confirmar	E
Cancelar	X o Esc
Guardar el offset para esta combinación	G

Las teclas de confirmar y cancelar de la pantalla final son reasignables por el jugador en los ajustes de FiveM.

Permisos: no usa ACE. Con Config.Permissions.enabled = true se exige tener uno de los trabajos de allowedJobs o, si requireItem = true, poseer el ítem (ver "Requisitos").

Exports:

Cliente: GetTransportState(), GetCustomOffsets(), IsCarrierWithCargo(veh).
Servidor: GetActiveTransports(), GetCustomOffsets().

Como se usa

Cargar un vehículo

Ponte cerca de un transportador (pickup, plataforma, grúa o rollback) y del vehículo a cargar.
Ejecuta /transportarveh.
Apunta con la mira al transportador: se resalta y se muestra su tipo. Pulsa E para elegirlo (Retroceso o Esc cancelan).
Apunta al vehículo que quieres cargar: se resalta y se muestra su categoría. Pulsa E para elegirlo.
Ajusta la posición con el teclado (ver tabla de teclas). Pulsa E para continuar.
En la pantalla de confirmación, pulsa E para confirmar o X para cancelar.
Opcional: pulsa G durante el ajuste para guardar la posición para esa combinación de vehículos.

Descargar

Si conduces el transportador con carga, ejecuta /transportarveh o /descargarveh.
Si no, ejecuta /descargarveh y apunta al transportador.
La carga se deja detrás del transportador, según el dropOffset de su tipo.

Para administradores

Añadir transportadores: pon el nombre del modelo en la lista models del tipo correspondiente. También puedes crear un tipo nuevo en Config.CarrierTypes.
Corregir una posición mal colocada: carga el vehículo, ajústalo y pulsa G. Se guarda en data/offsets.json y se aplica a todos desde entonces. Para fijarla a mano, añade la combinación a Config.DefaultOffsets.
Clasificar un vehículo especial: usa Config.CargoModelOverrides.
Si la carga se coloca mal al descargar: ajusta dropOffset del tipo de transportador.
Restringir el uso: activa Config.Permissions.enabled.
Para ver errores, activa Config.Debug y revisa la consola del servidor y F8. /transportdiag ayuda a saber por qué un vehículo no se reconoce.
Los mensajes que ve el jugador están dentro del código cifrado y no son editables.

Preguntas frecuentes

¿Puedo cargar más de un vehículo por transportador? No: maxAttached es 1 por defecto y el recurso está pensado para un vehículo por transportador.

¿Funciona con vehículos personalizados? Sí. Añade el modelo del transportador a Config.CarrierTypes; la carga se clasifica por su clase del juego (o con Config.CargoModelOverrides).

¿Los offsets se guardan por vehículo o en general? Por combinación de modelo de transportador y modelo de carga, y se comparten con todos los jugadores.

¿Necesito ox_inventory o una base de datos? No. Solo qb-core y ox_lib. Solo la opción de exigir un ítem depende del inventario (ver "Requisitos").

"Transportador no válido" al cargar. El modelo no está en Config.CarrierTypes. Añádelo al tipo adecuado.

"No se pudo obtener control de red". Otro script tiene control del vehículo. Aleja el vehículo de la zona o reinícialo.

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re y en la tienda. Conserva tu config.lua y data/offsets.json al actualizar. Para soporte, usa el Discord de la tienda: [enlace de soporte].