# <img src='/images/hotwire.webp' class="icon-light" /><img src='/images/hotwire-dark.webp' class="icon-dark" /> Hotwire
Documentation of jo_hotwire, the free and open source **FiveM hotwire script** with a **GTA 6 (GTA VI) style** two-stick minigame: players steal parked cars by turning both sticks to the right spots to start the engine without a key. It runs on FiveM (GTA V) and is inspired by GTA VI, not an official Rockstar Games product.

Free FiveM hotwire script with a GTA 6 style two-stick minigame to steal parked cars. Standalone for ESX, QBCore and QBox, gamepad and keyboard.

[Buy Hotwire on the Jump On Studios store](https://jumpon-studios.com/fivem/hotwire)

## 1. Installation
Hotwire is a standalone script. So you don't need a specific framework to use it. It also means **it works with all frameworks** (ESX, QBCore, QBox, VRP, …). It only requires **OneSync**.

- [Get it for free on the store](https://jumpon-studios.com/fivem/hotwire?utm_source=docs&utm_medium=referral&utm_campaign=installation&utm_content=hotwire), then download it from the Cfx.re portal
- Drag and drop the resource in your resources folder
  - jo_hotwire
- Add it to your server.cfg
  - `ensure jo_hotwire`

Congratulation, the **Hotwire** script is ready to be used!

## 2. Usage
When a player sits in the driver seat of a parked vehicle with its engine off, the minigame starts by itself:
1. Two half-circles appear above the vehicle. Their orientation changes at every attempt.
2. Each stick must point at the middle of its half-circle: the half-circle fills as the stick gets closer.
3. Both sticks must stay in their zone for a moment to start the engine.
4. If the time runs out, the attempt fails and the alarm may go off. Press `H` (D-pad right on a gamepad) to try again.

| Input | Left half-circle | Right half-circle |
| --- | --- | --- |
| Gamepad | Left stick | Right stick |
| Keyboard & mouse | Movement keys (8 directions) | Mouse |

Cancel the attempt with `F`, `Escape` or `Backspace` (`B` on a gamepad).

By default, only the parked ambient vehicles need to be hotwired:
- Vehicles spawned by scripts (garages, admin menus) are ignored: `Config.hotwireScriptVehicles`
- Vehicles taken from a driver with the engine running are ignored: `Config.hotwireRunningVehicles`
- Bicycles, boats, helicopters, planes and trains never need it: `Config.excludedClasses`

Once hotwired, a vehicle stays hotwired for every player.

## 3. Configuration

The configuration files are located in the `config` folder within the resource. This folder contains two subfolders:

- **`_default.lock/`** - Contains the default configuration files. **Do not edit these files directly** as they may be overwritten during updates.
- **`custom/`** - This is where you place your custom configuration files to override the defaults.

### How to customize the configuration

1. Navigate to `jo_hotwire/config/_default.lock/`
2. Copy the file you want to modify (e.g., `prices.lua`)
3. Paste it into `jo_hotwire/config/custom/`
4. Edit the copied file in the `custom` folder

The script automatically loads files from `custom/` first, and only uses `_default.lock/` as a fallback. This system ensures your customizations are preserved when updating the script.

### Default configuration files

`jo_hotwire/config/_default.lock/global.lua`

```lua
Config.debugMode = false              -- Debug prints, commands (/hotwire, /hotwireMinigame, /resetHotwire), visible targets

Config.autoStart = true               -- Start the minigame when the player sits in the driver seat
Config.autoStartDelay = 700           -- Delay (ms) before the automatic start
Config.retryCooldown = 1500           -- Delay (ms) before retrying after a failure or cancel

Config.hotwireScriptVehicles = false  -- Also target vehicles spawned by scripts (garages, admin...)
Config.hotwireRunningVehicles = false -- Also target vehicles with the engine running (jacked from a NPC)

-- Vehicle classes never hotwired (https://docs.fivem.net/natives/?_0x29439776AAA00A62)
Config.excludedClasses = {
  13, -- Cycles
  14, -- Boats
  15, -- Helicopters
  16, -- Planes
  21, -- Trains
}

Config.playAnimation = true -- Hotwire animation during the minigame (not on motorcycles)
Config.animation = { dict = "veh@std@ds@base", name = "hotwire" }

Config.gamepadVibration = true -- Vibration growing as the sticks get closer to their targets

Config.alarmChanceOnFail = 60  -- Chance (0-100) of alarm on failure
Config.alarmDuration = 30000   -- Duration (ms) of the alarm

-- Frontend sounds, false to disable one
Config.sounds = {
  zone = { name = "NAV_UP_DOWN", set = "HUD_FRONTEND_DEFAULT_SOUNDSET" },
  success = { name = "Hack_Success", set = "DLC_HEIST_BIOLAB_PREP_HACKING_SOUNDS" },
  failed = { name = "Hack_Failed", set = "DLC_HEIST_BIOLAB_PREP_HACKING_SOUNDS" },
}
```

`jo_hotwire/config/_default.lock/minigame.lua`

```lua
Config.minigame = {
  maxDuration = 15000,     -- Time (ms) before failing, 0 = unlimited
  holdDuration = 1000,     -- Time (ms) both sticks must stay in their zone
  holdDecay = 1.5,         -- Hold progress drain speed out of the zone (multiplier)
  tolerance = 12,          -- Angle (degrees) around the target counted as "in zone"
  detectionRange = 80,     -- Angle (degrees) around the target where filling starts
  minStickMagnitude = 0.55, -- Min stick deflection (0-1) to react
  angleSteps = 8,          -- Possible orientations (8 = keyboard directions), 0 = any angle
  targetDrift = 0,       -- Rotation speed (degrees/s) of the half-circles, 0 = static

  -- Color of both half-circles: "vehicle" (paint), a CSS color, or false = random from `colors`
  color = "vehicle",
  -- Random colors, when `color` is false or without vehicle
  colors = { "#ff5fa2", "#4fd1ff", "#ffb43b", "#7cff6b", "#b98cff", "#ff7a4f" },

  -- Border of the half-circles, badges and keycaps
  border = {
    color = "rgba(0, 0, 0, 0.85)", -- CSS color, false = no border
    width = 1.2,                   -- Width in pixels
  },
}

-- Keyboard & mouse: movement keys for the left stick, mouse for the right one
Config.keyboard = {
  mouseSensitivity = 1.0, -- Mouse sensitivity multiplier
}
```

`jo_hotwire/config/_default.lock/keys.lua`

```lua
-- Controls list: https://docs.fivem.net/docs/game-references/controls/
-- `label` is the help text token, it must match the control
Config.keys = {
  hotwire = { control = 74, label = "~INPUT_VEH_HEADLIGHT~" }, -- H / D-pad right: start manually
  cancel = { 75, 200, 202 },                                   -- F / Y, Escape, Backspace / B: cancel
}
```

`jo_hotwire/config/_default.lock/lang.lua`

```lua
-- {L} and {R} become the left and right control icons
Lang.instructions    = "Move {L} and {R} to the right spots to fill the half-circles and start the vehicle without a key."
Lang.helpHotwire     = "Press %s to hotwire the vehicle"
Lang.hotwireSuccess  = "Vehicle started"
Lang.hotwireFailed   = "You failed to hotwire the vehicle"
Lang.alarmTriggered  = "The alarm went off!"
Lang.cannotHotwire   = "You cannot hotwire this vehicle"
```

`jo_hotwire/config/_default.lock/functions.lua`

```lua
-- Integration with your scripts (keys, items, dispatch...). Loaded on both sides.

-- * ====================
-- *  CLIENT SIDE
-- * ====================

-- ° Return false to skip the minigame (e.g. the player has the keys)
-- @param vehicle The vehicle entity
Config.needsHotwire = function(vehicle)
  -- Example with qb-vehiclekeys: return not exports["qb-vehiclekeys"]:HasKeys(GetVehicleNumberPlateText(vehicle))
  return true
end

-- ° Return false to block an attempt (e.g. missing item)
-- @param vehicle The vehicle entity
Config.canStartHotwire = function(vehicle)
  return true
end

-- ° Show a notification
-- @param message The text to display
-- @param type "success" | "error" | "info"
Config.notify = function(message, type)
  BeginTextCommandThefeedPost("STRING")
  AddTextComponentSubstringPlayerName(message)
  EndTextCommandThefeedPostTicker(false, false)
end

-- ° Hotwire succeeded
-- @param vehicle The vehicle entity
Config.onHotwireSuccess = function(vehicle)
  -- Example: give the keys with your key script
end

-- ° Hotwire failed
-- @param vehicle The vehicle entity
-- @param alarmTriggered true if the alarm went off
Config.onHotwireFailed = function(vehicle, alarmTriggered)
  -- Example: police alert with your dispatch script when alarmTriggered
end

-- * ====================
-- *  SERVER SIDE
-- * ====================

-- ° Hotwire validated by the server
-- @param source The player server id
-- @param vehicle The vehicle entity
Config.onVehicleHotwiredServer = function(source, vehicle)
end

-- ° Hotwire failed (server)
-- @param source The player server id
-- @param vehicle The vehicle entity (nil if deleted)
-- @param alarmTriggered true if the alarm went off
Config.onHotwireFailedServer = function(source, vehicle, alarmTriggered)
end
```

## 4. Integration with your scripts
All the integration points are functions of `config/_default.lock/functions.lua`. Copy the file into `config/custom` to edit them.

| Function | Side | Use |
| --- | --- | --- |
| `Config.needsHotwire(vehicle)` | Client | Return `false` to skip the minigame (e.g. the player has the keys) |
| `Config.canStartHotwire(vehicle)` | Client | Return `false` to block an attempt (e.g. missing item) |
| `Config.notify(message, type)` | Client | Use your own notification system |
| `Config.onHotwireSuccess(vehicle)` | Client | Give the keys with your key script |
| `Config.onHotwireFailed(vehicle, alarmTriggered)` | Client | Send a police alert with your dispatch script |
| `Config.onVehicleHotwiredServer(source, vehicle)` | Server | The server validated a hotwire |
| `Config.onHotwireFailedServer(source, vehicle, alarmTriggered)` | Server | A player failed a hotwire |

### `[QBcore]` Skip the minigame with the vehicle keys
```lua
Config.needsHotwire = function(vehicle)
  return not exports["qb-vehiclekeys"]:HasKeys(GetVehicleNumberPlateText(vehicle))
end
```

## 5. For developers
### Exports
```lua
-- @side : Client side
exports.jo_hotwire:StartHotwire(vehicle)        -- Run an attempt on the vehicle driven by the player, returns true on success
exports.jo_hotwire:IsVehicleHotwired(vehicle)
exports.jo_hotwire:SetVehicleHotwired(vehicle)  -- e.g. when the player gets the keys
exports.jo_hotwire:StartMinigame()              -- Use the minigame alone, returns true on success
exports.jo_hotwire:IsMinigameRunning()
```
```lua
-- @side : Server side
exports.jo_hotwire:SetVehicleHotwired(vehicle)  -- or (netId, true)
exports.jo_hotwire:IsVehicleHotwired(vehicle)
```

### Events
```lua
-- @side : Client side
AddEventHandler("jo_hotwire:client:hotwireStarted", function(vehicle) end)
AddEventHandler("jo_hotwire:client:hotwireSucceeded", function(vehicle) end)
AddEventHandler("jo_hotwire:client:hotwireFailed", function(vehicle, alarmTriggered) end)
AddEventHandler("jo_hotwire:client:hotwireCancelled", function(vehicle) end)
```
```lua
-- @side : Server side
AddEventHandler("jo_hotwire:server:vehicleHotwired", function(source, vehicle) end)
AddEventHandler("jo_hotwire:server:hotwireFailed", function(source, vehicle, alarmTriggered) end)
```

### Debug commands
With `Config.debugMode = true`:
- `/hotwire`: force an attempt on the current vehicle
- `/hotwireMinigame`: run the minigame alone
- `/resetHotwire`: forget the hotwired state of the current vehicle, or of the closest one within 6 m when on foot
