Security Modules

Security modules are chips that owners install in their vehicles to protect them against theft. A vehicle with a module can't be lockpicked or hotwired until a thief jams it with a signal jammer, and higher tiers make both the jam and the hotwire harder.

The module is saved on the owned vehicle, so it stays installed through restarts and storing the vehicle.

#Table of Contents

• How Security Modules Work
• Module Tiers
• Installing a Module
• Upgrading a Module
• Mechanic Installs
• Database Setup
• Setting Modules From Other Scripts
• Configuration Reference
• FAQ

#How Security Modules Work

1. The owner installs a module from the driver seat of an owned vehicle.
2. The vehicle becomes protected. It needs a signal jam before it can be lockpicked or hotwired, even if its vehicle class isn't in signalJammer.protectedVehicles.
3. The module raises the difficulty. A thief's jammer minigame uses the module's jamDifficulty, and the hotwire minigame uses its hotwireDifficulty, whenever these are harder than the defaults.
4. The module is saved to the owned vehicle row in your framework's database.

A module only ever raises the difficulty. If the vehicle class already plays at expert, a Basic module doesn't make it easier.

#Module Tiers

For example, a regular sedan normally hotwires at easy and doesn't need a jam at all. With an Elite module, a thief has to complete an expert jam and then an expert hotwire.

See Signal Jammer and Hotwiring for what each difficulty means.

#Installing a Module

#Sit in the driver seat

Get in the driver seat of the vehicle you want to protect. The vehicle must be owned, meaning it has a row in your framework's owned vehicle table.

#Use the module item

Use a security_module_basic, security_module_advanced or security_module_elite. You need access to the vehicle (a key) unless you have one of the configured installer jobs.

#Wait for the installation

An installation animation and progress bar run for installTime seconds (default 15). You can cancel the progress bar, and leaving the driver seat cancels the installation. A cancelled installation keeps the item.

#Done

The item is removed and you see "Security module installed. Thieves now have to jam this vehicle's signal first."

#Why Can't I Install It?

#Upgrading a Module

Installing a higher tier replaces the current module. You can go from Basic to Advanced or Elite, or from Advanced to Elite.

You can't install a module of an equal or lower tier. The old module is not returned when it's replaced.

To remove a module, use the SetVehicleSecurityModule export.

#Mechanic Installs

Players with one of the jobs in securityModules.jobs can install modules in any owned vehicle without having its key. This lets mechanics sell and fit modules for customers.

lua
jobs = {"mechanic", "bennys"},

To require a minimum grade, use table entries instead:

lua
jobs = {
    {name = "mechanic", minGrade = 2},
    {name = "bennys", minGrade = 1},
},

Use either plain job names or {name, minGrade} entries in the list, not both.

Set jobs = {} to only allow players with access to the vehicle.

#Database Setup

Modules are stored in a column on your framework's owned vehicle table, so they stay with the vehicle. On start, Vehicle Keys checks database.tables in order and uses the first framework that is started:

If the security_module column doesn't exist, it is added automatically as VARCHAR(64) DEFAULT NULL. No SQL file needs to be run.

If no framework in the list is started, the console prints No supported framework is started, security modules are disabled, and modules can't be installed.

If your owned vehicles live elsewhere, add your table to the list. Change plateColumn if your table stores the plate under another column name:

lua
database = {
    tables = {
        {resource = "my_framework", table = "my_owned_vehicles"},
    },
    plateColumn = "plate",
    moduleColumn = "security_module",
},

#Setting Modules From Other Scripts

Server exports let shops, admin menus or mechanic scripts manage modules.

lua
-- Install or replace a module, ignoring the tier check
---@param plate string
---@param itemName? string @ A configured module item, nil removes the module
---@return boolean saved
local saved = exports["zyke_vehiclekeys"]:SetVehicleSecurityModule("ABC123", "security_module_elite")

-- Remove the module
exports["zyke_vehiclekeys"]:SetVehicleSecurityModule("ABC123", nil)

-- Read the installed module
---@param plate string
---@return string? itemName
local module = exports["zyke_vehiclekeys"]:GetVehicleSecurityModule("ABC123")

SetVehicleSecurityModule returns false for an unknown item name or a plate without an owned vehicle row.

Installations are logged through LogKeyAction as InstalledSecurityModule.

#Configuration Reference

All settings live in Config.Settings.securityModules:

lua
securityModules = {
    enabled = true,
    installTime = 15,                       -- Seconds
    jobs = {"mechanic"},                    -- Jobs that can install without vehicle access
    anim = {dict = "anim@gangops@facility@servers@", clip = "hotwire"},
    items = {
        -- Higher tiers replace lower ones, a module can't replace an equal or better one
        security_module_basic = {tier = 1, jamDifficulty = "medium", hotwireDifficulty = "medium"},
        security_module_advanced = {tier = 2, jamDifficulty = "hard", hotwireDifficulty = "hard"},
        security_module_elite = {tier = 3, jamDifficulty = "expert", hotwireDifficulty = "expert"},
    },
    database = {
        tables = {
            {resource = "es_extended", table = "owned_vehicles"},
            {resource = "qbx_core", table = "player_vehicles"},
            {resource = "qb-core", table = "player_vehicles"},
        },
        plateColumn = "plate",
        moduleColumn = "security_module",
    },
}

Difficulties must match a key in signalJammer.difficulties and hotwiring.minigame.difficulties.

#FAQ

Q: Do I need to add the modules to my inventory? Yes. Add the three security_module_* items from extras/items/ and copy their images from extras/items/images/256/ into your inventory images.

Q: Does a module stop thieves completely? No. It forces them to bring a signal jammer and pass a harder jam and hotwire. With a jammer and enough skill, any vehicle can still be stolen.

Q: What happens if I disable the signal jammer? With signalJammer.enabled = false, modules no longer require a jam, but they still raise the hotwire difficulty.

Q: Does the module survive a plate change? Yes, when the plate is changed through RenamePlate and your garage or framework updates the plate in the owned vehicle table.

Q: Can I give a module back when it's replaced? Not by default. Replacing a module consumes the new item and discards the old one.