Instalación

Antes de empezar#

Antes de instalar Vehicle Keys, asegúrate de que tu servidor cumple los requisitos mínimos. Cuatro son obligatorios; todo lo demás es opcional y se detecta solo.

Todo lo específico del framework o del inventario está tras un pequeño archivo bridge, y el recurso elige el correcto mirando lo que ya está en ejecución:

Usa un solo inventario: la detección no los prioriza, así que con dos iniciados la elección no está garantizada. Integraciones cubre cada uno y lo que cambia.

Descargar Vehicle Keys#

Tras comprar Vehicle Keys, el recurso se vincula automáticamente a tu cuenta de CFX Portal.

Inicia sesión en CFX Portal con la misma cuenta que usaste al finalizar la compra, abre Granted Assets y descarga Vehicle Keys.

Tras extraer la descarga, deberías tener la siguiente carpeta:

qs-vehiclekeys/
├── config/main.lua    -- every setting, in one file
├── custom/            -- framework bridges, notifications and text UI (editable)
├── client/custom/     -- dispatch, inventory and target bridges (editable)
├── server/custom/     -- the dispatch bridge (editable)
├── locales/           -- 41 languages
├── sql/database.sql   -- optional: the GPS tracker table
├── docs/              -- offline notes: commands, exports and items
└── web/               -- the interface, already built

La carpeta debe llamarse qs-vehiclekeys. La interfaz se carga desde nui://qs-vehiclekeys/web/, el script llama a sus propios exports con ese nombre, y todo garaje, concesionario o trabajo que entrega llaves busca exports['qs-vehiclekeys']. Una copia renombrada rompe las tres cosas.

Instalar el recurso#

Mueve la carpeta qs-vehiclekeys al directorio de recursos de tu servidor. Puede estar en cualquier lugar dentro de él, incluida una carpeta de categoría:

resources/
└── [qs]/
    └── qs-vehiclekeys/

Después abre tu server.cfg y asegúrate de que todas las dependencias (y todo lo que deba detectar) se inicien antes que Vehicle Keys:

ensure oxmysql
ensure ox_lib

# Framework
ensure es_extended
# ensure qb-core
# ensure qbx_core

# Inventory, target, sounds, dispatch
ensure ox_inventory
ensure ox_target
ensure interact-sound
# ensure qs-dispatch

ensure qs-vehiclekeys

# Garages, dealerships and jobs that hand out keys
ensure qs-advancedgarages

El orden de carga importa. La detección solo ve los recursos que ya se han iniciado, así que un framework o inventario que se inicie después de Vehicle Keys no se encuentra y el script pasa a standalone. Los scripts que llaman a sus exports (garajes, concesionarios, scripts de trabajos) van después.

Añadir los ítems#

Las llaves, ganzúas, matrículas y rastreadores son ítems de inventario, así que deben existir en tu inventario antes de que nada funcione. El script usa ocho, y cada uno se puede renombrar en config/main.lua:

Ítems de inventario tiene todas las definiciones listas para pegar en ox_inventory, qb-inventory y qs-inventory.

La base de datos#

No hay tabla de llaves: una llave vive en el inventario del jugador y en ningún otro sitio. La propiedad de los vehículos se lee de la tabla propia de tu framework (owned_vehicles en ESX, player_vehicles en QBCore y Qbox) para el acceso del propietario, la recuperación de llaves, la limpieza de llaves, los cambios de matrícula y el panel de admin.

La única tabla propia es vehiclekeys_trackers, y se crea sola al iniciar mientras los rastreadores GPS estén activados. sql/database.sql contiene la misma sentencia para quien prefiera importarla a mano:

CREATE TABLE IF NOT EXISTS `vehiclekeys_trackers` (
  `plate` VARCHAR(16) NOT NULL,
  `model` VARCHAR(64) NOT NULL,
  `installed_by` VARCHAR(80) NOT NULL,
  `installed_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`plate`),
  KEY `idx_vehiclekeys_trackers_installed_by` (`installed_by`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

Una fila por matrícula, así que un coche lleva como máximo un rastreador. installed_by es el identificador de framework de quien lo instaló: ese jugador siempre puede encontrar el coche, tenga llave o no.

Acceso de admin#

El panel de admin (/vkadmin), /givekeys y el acceso total de la llave maestra comprueban si un jugador es admin. La respuesta viene de tu framework; no hay una lista aparte que mantener:

setgroup <server id> admin

add_ace group.admin command allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.admin

add_ace group.admin command allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.admin

La regla de cada framework está en custom/<framework>/server.lua como playerIsAdmin; edítala ahí si tu staff usa otro grupo.

Configurar el recurso#

Toda la configuración está en un solo archivo, config/main.lua, agrupada por función. Uso recorre cada bloque junto a la función que define. Los valores que conviene revisar primero:

Config.Locale                = 'en'        -- 41 languages, see locales/
Config.TextUI                = 'ox_lib'    -- 'ox_lib' · 'qs-textui' · 'native'
Config.OwnerAccessWithoutKey = true        -- database owners need no key item
Config.UseTarget             = false       -- true = ox_target / qb-target
Config.Dispatch              = 'default'   -- 'default' · 'qs-dispatch' · 'qs-smartphone' · 'origen'
Config.PoliceJobs            = { police = true }

Config.KeyMappings = {
    UseVehicleKey     = 'U',   -- lock / unlock
    HotwireVehicle    = 'H',
    StealNpcDriverKey = 'G',
    ToggleEngine      = 'M'
}

Config.Debug                 = true        -- set false on a live server

Config.Debug viene activado e imprime líneas adicionales en la consola: desactívalo cuando el servidor esté en producción. Las teclas del config son solo valores predeterminados: una vez que un jugador se ha unido, su propia asignación en Settings → Key Bindings → FiveM tiene prioridad. Los cambios en el archivo se aplican después de restart qs-vehiclekeys.

Verificar la instalación#

Reinicia el servidor y busca la línea que indica el bridge que ha cargado, en la consola del servidor y en la consola F8 al unirte:

VEHICLEKEYS INFO: Framework server loaded:  esx
VEHICLEKEYS INFO: Framework client loaded:  esx

standalone significa que no encontró ningún framework en ejecución; si tienes uno, muévelo por encima de ensure qs-vehiclekeys. Después únete a tu servidor y sigue el primer recorrido:

1. Siéntate en un coche que no sea tuyo

   Súbete al asiento del conductor de cualquier coche aparcado. El motor sigue apagado, los pedales no hacen nada y un aviso dice Press H to hotwire the vehicle.

2. Haz un puente

   Pulsa H, espera a que termine el círculo de progreso y supera el skill check. El motor arranca y un ítem vehiclekeys de esa matrícula llega a tu inventario.

3. Ciérralo

   Bájate y pulsa U. El mando hace clic, las luces parpadean dos veces y las puertas se bloquean. Vuelve a pulsarla para desbloquear.

4. Abre el panel de admin

   /vkadmin lista todos los vehículos con propietario del servidor. A partir de ahí, Uso cubre todo lo demás.