> For the complete documentation index, see [llms.txt](https://crystal-studios.gitbook.io/crystal-studios-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://crystal-studios.gitbook.io/crystal-studios-docs/vehicle-keys/configuration.md).

# Configuration

Configuration for Vehicle Keys

***

## Default Config File:

```lua
Config = {}

---------------------------------------------------------------------
-- GENERAL SETTINGS
---------------------------------------------------------------------

-- Selected language for the script (matches your locales)
Config.Language = "en"

-- Notification system: "auto" (detects qb/qbox/esx), "ox" (Ox Lib), or "custom"
Config.NotifySystem = "ox"

-- Progress bar system: "auto" (detects qb, qbox, esx), "ox" (Ox Lib), or "custom"
Config.ProgressbarSystem = "ox"

-- Police alert system: "qb" (based on qb-policejob) or "custom"
Config.PoliceAlertSystem = "custom"

-- Maximum distance to lock/unlock vehicle using key
Config.LockDistance = 8.0

-- Maximum distance for the KeyFob (Remote) UI to work
Config.KeyFobDistance = 8.0

-- Maximum distance from which a police officer can confiscate keys
Config.PoliceConfiscationDistance = 10.0

-- Maximum distance to start lockpicking vehicle
Config.LockpickDistance = 5.0

-- Maximum distance to start carjacking
Config.CarJackDistance = 5.0

-- Time (ms) between open/close actions to prevent spamming
Config.CloseOpenDelay = 1500

-- Time (ms) between start/stop engine actions to prevent spamming
Config.StartStopEngineDelay = 1500

-- Keybinds (RegisterKeyMapping compatible)
Config.Keybinds = {
    CloseOpenSearchKey = "U",         -- Open / Close / Search vehicle
    EngineToggle = "Y",               -- Start / Stop engine manually
    HotwireKey = "G",
}

-- Enable or disable the on-screen KeyFob (Remote) UI
Config.UseKeyFob = true

-- Enable vehicle alarm when the car is lockpicked or hotwired
Config.VehicleAlarm = true

-- If true, the 'lockpick' item will be consumed upon use
Config.RemoveLockpick = true 

-- If false, players cannot lockpick vehicles that are currently being driven by an NPC
Config.DrivingCarCanBeLockpicked = false

-- Temporary Keys: If true, keys obtained via carjacking/searching will expire after a session (reconnect) if vehicle no longer exists
Config.TemporaryKeys = true 

-- Inventory item names
Config.LockPickItemName = "lockpick" -- Item used for breaking in
Config.VehKeyItemName = "vehkey"     -- Item used as a physical key

---------------------------------------------------------------------
-- ANIMATIONS
---------------------------------------------------------------------

Config.Animations = {
    -- Animation for clicking the remote (Lock/Unlock)
    LockToggle = {
        AnimDict = 'anim@mp_player_intmenu@key_fob@',
        AnimName = 'fob_click',
        Prop = {
            Name = 'p_car_keys_01',
            Bone = 57005,
            Pos = {
                x = 0.1,
                y = 0.0,
                z = 0.0,
            },
            Rot = {
                x = 0.0,
                y = 0.0,
                z = 0.0,
            }
        }
    },

    -- Animation for using a lockpick
    LockPick = {
        AnimDict = 'missheist_agency2aig_4',
        AnimName = 'look_plan_b_worker2',
        Prop = {
            Name = 'prop_cuff_keys_01',
            Bone = 57005,
            Pos = {
                x = 0.1,
                y = 0.0,
                z = 0.0,
            },
            Rot = {
                x = 0.0,
                y = 0.0,
                z = 0.0,
            }
        }
    },

    -- Animation for hotwiring (messing with wires)
    Hotwire = {
        AnimDict = 'anim@veh@car@toreador@ds@base',
        AnimName = 'hotwire',
        Prop = {
            Name = '',
            Bone = nil,
            Pos = {
                x = 0.1,
                y = 0.0,
                z = 0.0,
            },
            Rot = {
                x = 0.0,
                y = 0.0,
                z = 0.0,
            }
        }
    },

    -- Animation for searching for keys inside the vehicle
    SearchKeys = {
        AnimDict = 'anim@veh@car@toreador@ds@base',
        AnimName = 'hotwire',
        Prop = {
            Name = '',
            Bone = nil,
            Pos = {
                x = 0.1,
                y = 0.0,
                z = 0.0,
            },
            Rot = {
                x = 0.0,
                y = 0.0,
                z = 0.0,
            }
        }
    },

    -- Animation for holding the key in hand
    HoldKey = {
        AnimDict = 'amb@world_human_stand_mobile@male@text@base',
        AnimName = 'base',
        Prop = {
            Name = 'p_car_keys_01',
            Bone = 57005,
            Pos = {
                x = 0.1,
                y = 0.0,
                z = 0.0,
            },
            Rot = {
                x = 0.0,
                y = 0.0,
                z = 0.0,
            }
        }
    },

    -- Surrender animation for the NPC victim during a carjack
    VictimCarjackAnim = {
        AnimDict = 'mp_am_hold_up',
        AnimName = 'holdup_victim_20s',
        Prop = {
            Name = '',
            Bone = nil,
            Pos = {
                x = 0.1,
                y = 0.0,
                z = 0.0,
            },
            Rot = {
                x = 0.0,
                y = 0.0,
                z = 0.0,
            }
        }
    },

    -- Animation for police confiscation (showing badge)
    PoliceConfiscation = {
        AnimDict = 'paper_1_rcm_alt1-9',
        AnimName = 'player_one_dual-9',
        Prop = {
            Name = 'prop_fib_badge',
            Bone = 57005,
            Pos = {
                x = 0.065,
                y = 0.029,
                z = -0.035,
            },
            Rot = {
                x = 80.0,
                y = -1.90,
                z = 75.0,
            }
        }
    },
}

---------------------------------------------------------------------
-- VEHICLE BLACKLIST
---------------------------------------------------------------------

-- Vehicle classes that CANNOT be locked/unlocked (e.g., bicycles)
Config.NoLockVehicleClasses = {
    [0] = false, -- Compacts
    [1] = false, -- Sedans
    [2] = false, -- SUVs
    [3] = false, -- Coupes
    [4] = false, -- Muscle
    [5] = false, -- Sports Classics
    [6] = false, -- Sports
    [7] = false, -- Super
    [8] = false, -- Motorcycles
    [9] = false, -- Off-road
    [10] = false, -- Industrial
    [11] = false, -- Utility
    [12] = false, -- Vans
    [13] = true, -- Cycles
    [14] = false, -- Boats
    [15] = false, -- Helicopters
    [16] = false, -- Planes
    [17] = false, -- Service
    [18] = false, -- Emergency
    [19] = false, -- Military
    [20] = false, -- Commercial
    [21] = false, -- Trains
    [22] = false, -- Open Wheel
}

-- Specific vehicle models that cannot be locked
Config.NoLockVehicles = {
    -- examples:
    -- "adder",
    -- "issi2",
    -- "sabregt"
}

---------------------------------------------------------------------
-- HOTWIRE SETTINGS
---------------------------------------------------------------------

Config.Hotwire = {
    Enabled = true,               -- Enable / Disable the hotwire system
    EnabledForBlacklisted = false, -- Enable hotwire for blacklisted vehicles (bikes, boats, etc.)
}

---------------------------------------------------------------------
-- SEARCHKEYS SETTINGS
---------------------------------------------------------------------

Config.SearchKeys = {
    SearchTime = 3500,    -- Time (ms) it takes to search for keys in the vehicle
    SearchKeyChance = 50, -- Chance (0-100) to find keys in the glovebox/sun visor
}

---------------------------------------------------------------------
-- SKILLCHECKS SETTINGS
---------------------------------------------------------------------

Config.SkillChecks = {
    -- Minigame settings for hotwiring
    Hotwire = {
        difficulty = {'medium', 'hard', {areaSize = 70, speedMultiplier = 1.8}, 'medium'},
        keys = {'w', 'a', 's', 'd'},
    },

    -- Minigame settings for lockpicking
    Lockpick = {
        difficulty = {'medium', 'easy', {areaSize = 75, speedMultiplier = 1.3}, 'medium'},
        keys = {'w', 'a', 's', 'd'},
    },
}

---------------------------------------------------------------------
-- CARJACK SETTINGS
---------------------------------------------------------------------

Config.Carjack = {
    Enabled = true,   -- Enable / Disable carjacking (stealing car from NPC)
    Duration = 7500,  -- Progress bar duration (ms)
    Cooldown = 5000,  -- Delay between carjack attempts (ms)

    -- Success chance (0.0 = 0%, 1.0 = 100%)
    ChanceDefault = 0.5, -- Default chance if the weapon group is not listed below
    
    -- Chance based on Weapon Group ID (https://docs.fivem.net/natives/?_0xC3287EE3050FB74C)
    ChanceByWeaponGroup = {
        ['2685387236'] = 0.0,  -- Melee
        ['416676503'] = 0.85,   -- Handguns
        ['-957766203'] = 0.75, -- SMG
        ['860033945'] = 0.90,  -- Shotgun
        ['970310034'] = 0.90,  -- Assault Rifles
        ['1159398588'] = 0.99, -- LMG
        ['3082541095'] = 0.99, -- Snipers
        ['2725924767'] = 0.99, -- Heavy Weapons
        ['1548507267'] = 0.0,  -- Throwable
        ['4257178988'] = 0.0,  -- Misc
    },

    -- Weapons that CANNOT be used for carjacking (https://docs.fivem.net/docs/game-references/weapon-models/)
    BlacklistedWeapons = {
        "WEAPON_UNARMED",
        "WEAPON_KNIFE",
        "WEAPON_NIGHTSTICK",
        "WEAPON_HAMMER",
        "WEAPON_BAT",
        "WEAPON_CROWBAR",
        "WEAPON_GOLFCLUB",
        "WEAPON_BOTTLE",
        "WEAPON_DAGGER",
        "WEAPON_HATCHET",
        "WEAPON_KNUCKLE",
        "WEAPON_MACHETE",
        "WEAPON_FLASHLIGHT",
        "WEAPON_SWITCHBLADE",
        "WEAPON_POOLCUE",
        "WEAPON_WRENCH",
        "WEAPON_BATTLEAXE",
        "WEAPON_GRENADE",
        "WEAPON_STICKYBOMB",
        "WEAPON_PROXMINE",
        "WEAPON_BZGAS",
        "WEAPON_MOLOTOV",
        "WEAPON_FIREEXTINGUISHER",
        "WEAPON_PETROLCAN",
        "WEAPON_FLARE",
        "WEAPON_BALL",
        "WEAPON_SNOWBALL",
        "WEAPON_SMOKEGRENADE",
    }
}

---------------------------------------------------------------------
-- NPC VEHICLE LOCK SETTINGS
---------------------------------------------------------------------

Config.NPC = {
    -- If true, vehicles currently being driven by NPCs will be locked
    LockDrivingCars = true,

    -- If true, vehicles parked by NPCs will be spawned locked
    LockParkedCars = true,
}

---------------------------------------------------------------------
-- NOTIFICATIONS SETTINGS
---------------------------------------------------------------------

-- Toggle specific notifications and set their types
Config.Notify = {
    no_keys = {
        Enabled = true,
        Type = "error", -- success, error, info
    },
    startStop_no_keys = {
        Enabled = true,
        Type = "error", -- success, error, info
    },
    vehicle_locked = {
        Enabled = true,
        Type = "success", -- success, error, info
    },
    vehicle_unlocked = {
        Enabled = true,
        Type = "success", -- success, error, info  
    },
    searching_keys = {
        Enabled = true,
        Type = "info", -- success, error, info  
    },
    no_keys_found = {
        Enabled = true,
        Type = "error", -- success, error, info  
    },
    correct_keys_found = {
        Enabled = true,
        Type = "success", -- success, error, info  
    },
    search_cancelled = {
        Enabled = true,
        Type = "error", -- success, error, info  
    },
    carjack_success = {
        Enabled = true,
        Type = "success", -- success, error, info  
    },
    carjack_fail = {
        Enabled = true,
        Type = "error", -- success, error, info  
    },
    hotwire_success = {
        Enabled = true,
        Type = "success", -- success, error, info 
    },
    hotwire_fail = {
        Enabled = true,
        Type = "error", -- success, error, info 
    },
    lockpick_start = {
        Enabled = true,
        Type = "info", -- success, error, info 
    },
    lockpick_success = {
        Enabled = true,
        Type = "success", -- success, error, info 
    },
    lockpick_fail = {
        Enabled = true,
        Type = "error", -- success, error, info 
    },
    cant_lockpick_driving = {
        Enabled = true,
        Type = "error", -- success, error, info 
    },
    keys_confiscated = {
        Enabled = true,
        Type = "success", -- success, error, info 
    },
    keys_confiscated_cancelled = {
        Enabled = true,
        Type = "error", -- success, error, info 
    }
}

---------------------------------------------------------------------
-- SOUNDS SETTINGS
---------------------------------------------------------------------

Config.Sounds = {
    Enabled = false, -- 'InteractSound' resource must be installed and working
    Lock = {
        Name = "lock", -- Filename (without .ogg) in InteractSound/client/html/sounds
        Distance = 5,
        Volume = 0.3,
    },

    UnLock = {
        Name = "unlock", -- Filename (without .ogg) in InteractSound/client/html/sounds
        Distance = 5,
        Volume = 0.4,
    },
}

---------------------------------------------------------------------
-- Police Alert SETTINGS
---------------------------------------------------------------------
Config.PoliceAlert = {
    Enabled = true, -- Send alerts to police for vehicle crimes
    Cooldown = 300, -- Cooldown (s) between alerts to prevent spam
    Chance = 50, -- Chance (0-100) for an alert during the day
    NightChance = 75, -- Chance (0-100) for an alert at night (22:00 - 06:00)
    HotwireAlert = true, -- Alert police when hotwiring
    LockpickAlert = true, -- Alert police when lockpicking
    CarjackAlert = true, -- Alert police when carjacking
}

---------------------------------------------------------------------
-- Police Confiscation SETTINGS
---------------------------------------------------------------------
Config.PoliceConfiscation = {
    Enabled = true, -- Allow police to confiscate keys from players
    CommandName = "confiscatekeys", -- Command to use (e.g., /confiscatekeys)
    CommandDesc = "Confiscate keys from the nearest player", -- Description for the confiscation command
    jobs = {"police", "sheriff"}, -- Multiple jobs allowed to use the command
}

---------------------------------------------------------------------
-- Webhooks SETTINGS
---------------------------------------------------------------------
Config.Webhooks = {
    Enabled = true,
    URL = "YOUR_DISCORD_WEBHOOK_URL", -- Your Discord Webhook URL
    Color = 3447003, -- Blue color (Decimal)
    ServerName = "CR-Carkeys Logs",
    AuthorName = "VehicleKeys System",
    Logs = {
        KeyGiven = {
            Enabled = true,
            Title = "🔑 Keys Granted",
            Color = 65280, -- Green (Decimal)
            Message = "**Citizen:** {name}\n**Identifier:** ({identifier})\n**Action:** Keys received\n**Plate:** {plate}\n**Temporary:** {isTemp}"
        },
        KeyRemoved = {
            Enabled = true,
            Title = "🗑️ Keys Removed",
            Color = 16711680, -- Red (Decimal)
            Message = "**Citizen:** {name}\n**Identifier:** ({identifier})\n**Action:** Keys removed\n**Plate:** {plate}"
        },
        Carjack_Success = {
            Enabled = true,
            Title = "🔫 Carjacking Success",
            Color = 65280, -- Green (Decimal)
            Message = "**Citizen:** {name}\n**Identifier:** ({identifier})\n**Action:** Carjacking success\n**Plate:** {plate}"
        },
        Carjack_Fail = {
            Enabled = true,
            Title = "🔫 Carjacking Fail",
            Color = 16711680, -- Red (Decimal)
            Message = "**Citizen:** {name}\n**Identifier:** ({identifier})\n**Action:** Carjacking fail\n**Plate:** {plate}"
        },
        Lockpick_Success = {
            Enabled = true,
            Title = "🔨 Lockpicking Success",
            Color = 65280, -- Green (Decimal)
            Message = "**Citizen:** {name}\n**Identifier:** ({identifier})\n**Action:** Lockpicking Success\n**Plate:** {plate}"
        },
        Lockpick_Fail = {
            Enabled = true,
            Title = "🔨 Lockpicking Fail",
            Color = 16711680, -- Red (Decimal)
            Message = "**Citizen:** {name}\n**Identifier:** ({identifier})\n**Action:** Lockpicking Fail\n**Plate:** {plate}"
        }
    }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://crystal-studios.gitbook.io/crystal-studios-docs/vehicle-keys/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.