Documentation

Hotwire & Lockpick System

Interactive minigames for breaking into vehicles and doors.

Overview

tc_keys includes two criminal mechanics:

Hotwire - Start a vehicle without keys
Lockpick - Open locked doors and vehicles

Both feature interactive minigames with configurable difficulty and police dispatch integration.

Hotwiring Vehicles

How to Hotwire

Requirements:

hotwire_kit item (configurable)
Must be in driver seat
Must not have vehicle access already

Steps:

Sit in the driver seat of a locked vehicle
Use the hotwire kit item
Complete the hotwire minigame
On success: Engine starts, vehicle unlocked
On failure: Remain locked, possible police alert

Hotwire Minigame

The hotwire minigame requires players to connect wires while avoiding sparks:

Gameplay:

Multiple wires appear on screen
Click and hold each wire to connect it
Sparks randomly travel along wires
Release before a spark reaches you
Connect all wires to succeed

Difficulty Levels:

Easy (C Class) - Fewer wires, slower sparks
Medium (B Class) - Moderate wires and sparks
Hard (A Class) - More wires, faster sparks
Very Hard (S Class) - Many wires, very fast sparks

✅ Tip: Keep your finger ready to release when you see sparks approaching!

Difficulty Configuration

Configure how difficulty is determined:

main.lua

Config.HotWireDifficulty = "auto" -- "auto", "easy", "medium", "hard"

Auto Mode (Recommended):

main.lua

Config.GetVehicleClass = function(speed, vehicleName)
    if speed >= 160.0 then
        return "S"  -- Supercars
    elseif speed >= 140.0 then
        return "A"  -- Sports cars
    elseif speed >= 120.0 then
        return "B"  -- Performance cars
    else
        return "C"  -- Regular cars
    end
end

Custom Logic Examples:

main.lua

-- By vehicle class
Config.GetVehicleClass = function(speed, vehicleName)
    if vehicleName:find("supercar") then
        return "S"
    end
    -- etc.
end

-- By vehicle model hash
Config.GetVehicleClass = function(speed, vehicleName)
    local difficultVehicles = {
        ["adder"] = "S",
        ["zentorno"] = "S",
        -- etc.
    }
    return difficultVehicles[vehicleName] or "C"
end

Lockpicking

Lockpicking Vehicles

Requirements:

lockpick item (configurable)
Must be outside the vehicle
Vehicle must be locked
Must be within 2.5 meters

Steps:

Stand near a locked vehicle
Use the lockpick item
Complete the lockpick minigame
On success: Vehicle unlocked (temporarily)
On failure: Remain locked, possible police alert

Lockpicking Doors

Requirements:

lockpick item (configurable)
Door must be locked
Door must be lockpickable
Must be within 5 meters

Steps:

Stand near a locked door
Use the lockpick item
Complete the lockpick minigame (difficulty based on door config)
On success: Door unlocked (temporarily)
On failure: Remain locked, possible police alert

Lockpick Minigame

The lockpick minigame requires precise timing:

Gameplay:

A slider moves up and down
A target zone is shown
Click when the slider is in the target zone
Complete multiple rounds to succeed

Difficulty Levels:

Easy - Large target zone, slow speed
Medium - Medium target zone, medium speed
Hard - Small target zone, fast speed

✅ Tip: Watch the slider's movement pattern before clicking.

Smart Detection: When you use a lockpick item, the system automatically:

First checks for a nearby locked vehicle (within 2.5m)
- If found: Starts vehicle lockpick minigame
If no vehicle found: Checks for a nearby locked door (within 5m)
- If found: Starts door lockpick minigame
If neither found: Shows an error message

💭 Note: Lockpick items are typically consumed on use (server configurable).

Temporary Access

Both hotwire and lockpick grant temporary access:

Vehicle Access

Hotwire Success - Engine starts, can drive away
Lockpick Success - Doors unlock, can enter

Door Access

Lockpick Success - Door unlocks temporarily
Auto-Lock - Door re-locks after configured delay

Configure auto-lock delay:

main.lua

Config.DoorAutoLockDelayMs = 5000 -- 5 seconds

⚠️ Important: Temporary access does NOT give permanent keys. For doors, they re-lock automatically.

Police Dispatch Integration

Both mechanics can trigger police alerts:

Configuration

main.lua

Config.AlertPolice = true
Config.PoliceAlertsChances = {
    hotwireFail = 0.5,       -- 50% chance on failed hotwire
    lockpickFail = 0.5,      -- 50% chance on failed lockpick
    lockpickSuccess = 0.2,   -- 20% chance on successful lockpick
    hotwireSuccess = 0.2     -- 20% chance on successful hotwire
}

Dispatch Messages

Dispatch alerts include:

Location - Coordinates where the crime occurred
Type - "Vehicle Hotwiring", "Door Break-in", "Vehicle Break-in"
Job - Sent to configured police jobs

💭 Note: Dispatch system is configured in tc_lib. Supports ps-dispatch, codesign-dispatch, and default notification.

Realistic Balancing

Success vs Failure Alerts:

Failed attempts have higher alert chance (caught in the act)
Successful attempts have lower alert chance (quiet professional)
Balances realism with gameplay

Recommended Settings:

High-security servers: Increase all chances
Roleplay servers: Keep defaults
Casual servers: Decrease or disable alerts

Item Consumption

Configure if items are consumed:

In Your Inventory Config

main.lua

-- For ox_inventory
['lockpick'] = {
    label = 'Lockpick',
    weight = 160,
    server = {export = 'tc_lib.useItem'},
    -- Consume on use (handled by inventory)
}

['hotwire_kit'] = {
    label = 'Hotwire Kit',
    weight = 1,
    stack = false,
    server = {export = "tc_lib.useItem"},
    -- Consume on use (handled by inventory)
}

✅ Tip: Make lockpicks consumable and hotwire kits rare to balance the criminal economy.

Special Features

Job-Based Access

Some servers may allow mechanics or other jobs to hotwire vehicles without needing items, or with different difficulty settings.

Skill Systems

Your server may integrate skill progression:

Higher lockpicking skill = easier minigame
More experience = better success rate
Skill levels affect difficulty automatically

Custom Scenarios

Servers can create special scenarios:

Heist missions with specific lockpick requirements
Repo jobs requiring hotwiring
Training courses for learning the mechanics

Tips & Best Practices

For Server Owners

Balance difficulty - Too easy removes risk, too hard frustrates players
Set appropriate alert chances - Higher for high-security areas
Make items valuable - Rare hotwire kits create interesting choices
Consider your police population - More cops = higher alert chances work
Test the minigames - Make sure they're achievable

For Players

Practice makes perfect - Try the minigames on test vehicles/doors
Watch for police - High alert areas are risky
Be quick - Don't linger after successful lockpick
Have backup items - Bring extra lockpicks
Know when to run - Failed attempts might alert police

For Developers

Use exports for custom items - Don't duplicate the minigame code
Respect item consumption - Don't bypass item requirements
Add skill progression - Integrate with your skill systems
Create interesting scenarios - Heists, repo missions, etc.
Balance rewards - Make risk worth the reward

PreviousJob Keys NextExports & Events

Ticker Scripts Documentation