Uso

Cómo funcionan las llaves#

Una llave es un ítem vehiclekeys que lleva una matrícula. Siempre que el script tiene que decidir si un jugador puede usar un coche (cerrarlo, arrancar el motor, cambiar su matrícula, instalarle un rastreador), responde el servidor, y basta con cualquiera de estas condiciones:

Las matrículas y los modelos se comparan sin espacios sobrantes y en mayúsculas, así que abc 123 y ABC 123 son la misma llave.

Config.VehicleKeysItem          = 'vehiclekeys'     -- the key item
Config.AdminKeyItem             = 'adminvehiclekey' -- the master key
Config.OnlyAdminsCanUseAdminKey = true              -- master-key access for admins only
Config.OwnerAccessWithoutKey    = true              -- database owners need no key item

Las llaves y la propiedad están separadas a propósito. Un jugador puede tener la llave de un coche que no es suyo (el de un amigo, uno robado) y, con OwnerAccessWithoutKey desactivado, un propietario que pierde todas sus llaves se queda fuera de su propio coche hasta que recupere una.

Cerrar y abrir#

Pulsa U (/usekey) junto a un coche que puedas usar, o usa un ítem de llave. A pie, el personaje pulsa el mando con la llave en la mano; las puertas se cierran o se abren para todos, las luces parpadean dos veces y una notificación indica qué ocurrió. La tecla funciona con el coche más cercano; un ítem de llave funciona con el coche al que pertenece.

Config.LockDistance          = 20.0
Config.UseCommandKeyDistance = 5.0

Config.KeySettings = {
    Animation = {
        Dict = 'anim@mp_player_intmenu@key_fob@',
        Clip = 'fob_click_fp',
        Duration = 900,
        Flag = 48
    },
    Prop = {
        Model = 'p_car_keys_01'
    }
}

Config.Sounds               = true
Config.SoundsDisableDefault = false
Config.SoundsVolume         = 0.3
Config.SoundsFileName       = 'carkeys'
Config.SoundsDistance       = 4.0

El servidor recuerda el estado de cierre de cada coche por matrícula, así que un garaje puede sacar un coche exactamente como se dejó (consulta Comandos y exports).

El motor#

M (/engine) enciende y apaga el motor del coche que conduces. Con RequireKey, solo un jugador que puede usar el coche puede arrancarlo; cualquier otro ve You are not allowed to control this engine.

Config.Engine = {
    RequireKey = true,
    KeepEngineOn = true,
    AutoStartOnEnter = false,
    MaintainSteeringAngle = true,
    DisableAutoStartWithAccelerate = true
}

Tráfico NPC cerrado#

Cada pocos segundos, el script revisa los coches alrededor de cada jugador. Cualquier coche con un NPC al volante queda cerrado y marcado como que necesita un puente, así que llevarse uno implica una ganzúa o la llave del conductor a punta de pistola.

Config.NpcVehicleLock = {
    Enabled = true,
    ScanDistance = 40.0, -- metres around the player
    ScanInterval = 2500, -- ms between scans
    LockedState = 2      -- native lock state applied (2 = locked)
}

Coches que nunca necesitan llave#

Los modelos de Config.NoLockVehicles nunca los cierra el escaneo, se abren en cuanto un jugador intenta subir y se conducen sin llave ni puente: útil para flotas de emergencia que viven fuera del sistema de llaves. Usa nombres de spawn en mayúsculas o minúsculas, o hashes de modelo:

Config.NoLockVehicles = {
    'police',
    'ambulance',
}

Los modelos de la lista de puente o de ganzúa Whitelist (bicicletas por defecto) tampoco necesitan llave para conducirlos.

Hacer un puente#

Siéntate al volante de un coche al que no tienes acceso y el motor se corta, los pedales dejan de responder y aparece un aviso sobre el coche: Press H to hotwire the vehicle. Pulsa H (/hotwire): se muestra un círculo de progreso con la animación de puente y después un skill check de ox_lib. Si lo superas, el motor arranca y, con GiveKeyOnSuccess, una llave de esa matrícula llega al inventario. Si fallas, puedes volver a intentarlo.

Config.Hotwire = {
    Enabled = true,
    Duration = 10000,
    SkillCheck = { 'easy', 'easy', 'medium' },
    GiveKeyOnSuccess = true,
    RequirePolice = false,
    MinimumPolice = 0,
    DispatchChance = 35,
    Whitelist = { 'bmx', 'cruiser', 'enduro', 'fixter', 'scorcher', 'tribike', 'tribike2', 'tribike3' }
}

Ganzúas#

Usa una carlockpick (o escribe /lockpick) a pie junto a un coche cerrado, y empieza un skill check de ox_lib. Si lo superas, las puertas se abren; si fallas, siguen cerradas. En ambos casos puede saltar la alarma y alertarse a la policía. Forzar la cerradura solo abre las puertas: el motor sigue necesitando una llave o un puente.

La caradvancedlockpick funciona igual, solo desde el ítem, y con AdvancedBypassPolice ignora el requisito de policía.

Config.Lockpick = {
    Enabled = true,
    Item = 'carlockpick',
    AdvancedItem = 'caradvancedlockpick',
    Distance = 4.0,
    Duration = 12000,
    SkillCheck = { 'easy', 'easy', 'medium' },
    RequirePolice = true,
    MinimumPolice = 0,
    AdvancedBypassPolice = true,
    DispatchChance = 45,
    AlarmChance = 35,
    KeepChance = 50,
    RemoveOnFail = true,
    RemoveAdvancedOnFail = true,
    GiveKeyOnSuccess = false,
    Whitelist = { 'bmx', 'cruiser', 'enduro', 'fixter', 'scorcher', 'tribike', 'tribike2', 'tribike3' }
}

Robar llaves a conductores NPC#

Saca un arma, apunta a un NPC que conduce un coche y pulsa G (/stealnpckey). Un conductor que se rinde se baja con las manos en alto, se muestra un círculo de progreso mientras coges la llave y huye. Algunos conductores (un ShootChance por ciento) sacan una pistola y se defienden.

Solo empieza cuando se cumple todo esto:

• El jugador está armado y apuntando a un NPC (no a un jugador) en el asiento del conductor, a menos de MaxDistance.

• El jugador aún no tiene acceso a ese coche, y su conductor no ha sido robado ya.

• Ha pasado el Cooldown desde el último intento y hay suficientes policías en línea.

Config.NpcDriverKeySteal = {
    Enabled = true,
    Duration = 5000,
    Cooldown = 6000,
    MaxDistance = 12.0,
    ShootChance = 25,
    ProgressCanCancel = true,
    NpcFleeDistance = 300.0,
    RequirePolice = true,
    MinimumPolice = 2,
    DispatchChance = 60,
    ForceNpcExit = true,
    GiveKeysOnSuccess = true,
    LeaveUnlocked = true
}

Compartir llaves#

El menú de transferencia de llaves#

F7 (/keytransfer) abre una ventana con los jugadores a tu alrededor (a menos de 10 m, el más cercano primero) y las llaves que tienes. Elige uno de cada y pulsa Transfer Key: tu personaje la entrega y al otro jugador se le indica quién le dio qué llave.

Quien da la llave conserva la suya: una transferencia entrega una copia. Se rechaza si el otro jugador se ha alejado más de 8 m o ya tiene esa llave.

Config.KeyTransfer = {
    Enabled = true,              -- false removes the menu, its command and its key
    CommandName = 'keytransfer',
    EnableKeyMapping = true,     -- false: no key bound, the command still works
    Key = 'F7'
}

/givekeys#

Los admins pueden dar la llave del coche en el que están sentados con /givekeys [id] a ese id de servidor, o al jugador más cercano a menos de 8 m si no se da id. El receptor recibe una llave aunque ya tenga una.

El menú de interacción#

F4 (/vehiclekeys_interaction), dentro de un vehículo, abre un menú rápido: usar la llave, el menú de transferencia de llaves, limpiar llaves y, al volante de un barco, el ancla. Cada entrada desaparece cuando su función está desactivada.

Limpiar llaves#

Las furgonetas de trabajo y los coches prestados dejan llaves atrás. /cleankeys elimina de una vez todas las llaves cuya matrícula no corresponde a un coche que el jugador tenga en la base de datos, e indica cuántas se quitaron. /openkeys abre un pequeño menú con la misma acción.

Config.CleanKeys = {
    Enabled = true,
    CommandName = 'cleankeys',
    MenuCommandName = 'openkeys'   -- false or nil: no menu command
}

Recuperar una llave perdida#

Un empleado de banco está en el punto definido en el config. Acércate y pulsa E: un menú lista todos tus coches como MODEL [PLATE]. Elige uno y una llave nueva llega a tu inventario, gratis y solo si aún no tienes una llave de esa matrícula.

Config.KeyRecovery = {
    Enabled = true,
    NPCs = {   -- add as many clerks as you like
        {
            coords = vec4(214.219788, -817.727478, 30.661499, 249.448822),
            model = 'cs_bankman'
        }
    },
    TextUiDistance = 2.0,      -- where the prompt appears
    InteractionDistance = 2.0, -- where the key works
    OpenControl = 'E'          -- 'E', 'G', 'H' or a control number
}

La tienda de copias de llaves#

Un mecánico con una caja de herramientas (y un blip Copy keys en el mapa) vende llaves de repuesto, matrículas y destornilladores. Pulsa E a su lado, o usa la opción de target si el target está activado.

Se hace una copia aunque ya tengas esa llave; esa es la idea: una para quedártela, otra para darla. El pago sale de la cuenta de Account (money en ESX, cash en QBCore). Con RequireOwnership, solo se hacen copias de coches que el jugador tiene en la base de datos.

Config.CopyShop = {
    Enabled = true,
    TextUiDistance = 2.0,      -- where the prompt appears
    InteractDistance = 2.0,    -- where the key works, and how close the car must be
    PedRenderDistance = 10.0,  -- the mechanic spawns within this range
    UseBlip = true,
    UseTarget = true,          -- also needs Config.UseTarget
    OpenControl = 'E',
    Npc = {
        Model = 's_m_y_xmech_01',
        Coords = vec4(-31.40, -1647.44, 29.28, 68.45),
        -- Animation and Prop: the idle pose and the toolbox in his hand
    },
    Blip = { Name = 'Copy keys', Sprite = 186, Colour = 3, Scale = 0.8 },
    Services = {               -- switch each one off on its own
        CopyNearbyVehicleKey = true,
        CopyFromOwnedKey = true,
        Plate = true,
        Screwdriver = true
    },
    RequireOwnership = false,
    Prices = {
        CopyNearbyVehicleKey = 500,
        CopyFromOwnedKey = 250,
        Plate = 500,
        Screwdriver = 150
    },
    Account = Config.Framework == 'esx' and 'money' or 'cash',
    Items = {
        Plate = Config.Plate.ItemName,
        Screwdriver = Config.Plate.ToolItemName
    }
}

Matrículas#

Un ítem de matrícula lleva un número de matrícula. Ponte junto a un coche con un destornillador en los bolsillos y usa la matrícula: se comprueba el número, se muestra un círculo de progreso mientras trabajas y el coche lleva la nueva matrícula para todos.

Qué cambia un cambio de matrícula#

Por último, se lanza el evento de servidor vehiclekeys:server:plateChanged con la matrícula antigua y la nueva, para cualquier otro script que guarde matrículas.

Las reglas#

• El número de matrícula debe tener la longitud configurada: letras, números y el espacio, si lo hay.

• No puede pertenecer ya a un coche con propietario.

• Con RequireOwnedVehicle, el jugador necesita acceso al coche y el coche debe estar en la base de datos. Desactívalo y una matrícula se puede poner en cualquier coche: si ese coche no está en la base de datos, el cambio vive solo en el coche y no se guarda nada, que es como funcionan las matrículas falsas en coches robados.

• Con RequireScrewdriver, hay que llevar el destornillador. Nunca se gasta.

Config.Plate = {
    Enabled = true,
    Letters = 3,                 -- ABC
    Numbers = 3,                 -- 123
    UseSpace = true,             -- ABC 123
    ChangeDuration = 5000,
    RequireScrewdriver = true,
    RequireOwnedVehicle = true,
    UseBootForTarget = false,    -- not used: the swap starts from the item
    ItemName = 'plate',
    ToolItemName = 'screwdriver'
}

Un concesionario o garaje que genera matrículas puede leer el mismo formato con GetPlateFormat, así que todas las matrículas del servidor se parecen. Las matrículas de GTA admiten ocho caracteres como máximo.

Rastreadores GPS#

Dos ítems funcionan juntos. El GPS (vehiclegps) es el rastreador: úsalo junto a un coche y, tras un breve círculo de progreso, se instala y se gasta; uno por coche. El tracker (vehicletracker) es el receptor: úsalo, o /tracker mientras lo llevas, para abrir la lista de coches rastreados. Elige uno y un blip pulsante y un punto de ruta lo marcan durante LocateDuration.

La lista muestra todos los rastreadores que instaló el jugador y todos los rastreadores de coches de los que tiene llave. Para quitar uno, ox_target añade Remove GPS tracker a esos coches: un skill check opcional, un círculo de progreso, y el ítem GPS vuelve.

Config.Tracker = {
    Enabled = true,
    GPSItemName = 'vehiclegps',         -- fitted to the car, used up
    TrackerItemName = 'vehicletracker', -- the receiver that lists tracked cars
    RequireOwnedVehicle = true,         -- key access needed to fit or remove
    UseTarget = true,                   -- removal through ox_target
    UseBootForTarget = false,           -- put the removal option on the boot
    InstallDistance = 3.0,
    RemoveDistance = 2.5,
    InstallDuration = 2500,
    RemoveDuration = 2500,
    LocateDuration = 20000,             -- how long the blip stays
    EnableMenuKeyMapping = false,       -- true: bind MenuKey to the menu
    MenuCommand = 'tracker',
    MenuKey = 'K',
    RemoveMinigame = {
        Enabled = true,
        SkillCheck = { 'easy', 'easy', 'medium' }
    },
    Blip = { Sprite = 161, Colour = 1, Display = 2, Scale = 1.1, ShortRange = false }
}

Diagnóstico y tintado de lunas#

Los mecánicos y la policía conectan una tablet al coche más cercano (/diagnostic, o la opción de target Run vehicle diagnostic) y, tras un escaneo, leen un informe que se sigue actualizando mientras está abierto:

La opción de target Measure window tint ilumina el cristal con una linterna e indica None, Light, Medium, Dark o Limo: una comprobación en carretera para los controles de tráfico. Sin un recurso de target, lanza el evento de cliente vehiclekeys:client:diagnostic:tint desde un menú radial.

Config.Diagnostic = {
    Enabled = true,
    NeedKey = false,            -- require access to the car to scan it
    AllowedJobs = {             -- an empty table lets everyone scan
        mechanic = true,
        police = true
    },
    AllowedTintJobs = {
        mechanic = true,
        police = true
    },
    UseCommand = true,
    CommandName = 'diagnostic',
    UseTarget = true,           -- also needs Config.UseTarget
    TargetDistance = 2.5,
    FindVehicleDistance = 5.0,
    ScanDuration = 5000,
    TintMeasureDuration = 5000,
    TempUnit = 'c',             -- 'c' or 'f'
    RefreshWhileOpen = 1500     -- ms between live updates
}

Ancla de barco#

Al volante de un barco que se mueve más despacio que SpeedLimitMps, /anchor (o el menú de interacción) baja el ancla tras un breve círculo de progreso y mantiene el barco donde está. Vuelve a ejecutarlo para subirla. Con UseSound, interact-sound reproduce anchordown y anchorup.

Config.Anchor = {
    Enabled = true,
    CommandName = 'anchor',
    SpeedLimitMps = 2.0,     -- metres per second
    ProgressDuration = 1500,
    AllowCancel = true,
    UseSound = true,
    Animation = {
        Dict = 'melee@unarmed@streamed_variations',
        Clip = 'plyr_takedown_front_slap'
    }
}

El panel de admin#

/vkadmin abre el Admin Vehicle Manager para los admins: todos los vehículos con propietario del servidor, leídos de la tabla propia del framework y cargados página a página al hacer scroll.

Config.AdminPanel = {
    Enabled = true,
    CommandName = 'vkadmin',
    EnableKeyMapping = false,  -- true: bind Key to the panel
    Key = 'F6',
    PageSize = 30              -- vehicles loaded per page
}

In garage y Outside vienen del indicador guardado del framework (stored en ESX, state en QBCore), así que solo son tan precisos como los mantenga tu script de garajes.

Alertas a la policía#

Hacer un puente, forzar con ganzúa y robar a conductores NPC tiran cada uno su propia DispatchChance. Cuando sale, se envía una alerta en la posición del ladrón a través de Config.Dispatch. Con default, todos los jugadores cuyo trabajo esté en Config.PoliceJobs reciben una notificación y un blip parpadeante. Integraciones cubre qs-dispatch, qs-smartphone y Origen.

Config.PoliceJobs = {
    police = true,
    sheriff = true
}

La misma lista es la que cuentan los requisitos de policía: todos los jugadores en línea con uno de esos trabajos, estén de servicio o no.

Ajustes globales#

Cada valor se lee al iniciar el recurso. Después de editar config/main.lua, ejecuta restart qs-vehiclekeys.