Installation guide

Cipher Drone

A deployable police drone with smooth flight, live camera, thermal, spotlight, tracker darts and counterplay.

Requirements

Framework: QBox (qbx_core) or QBCore (qb-core) — auto-detected by bridge/framework.lua, so you do not configure which one you run.
Inventory: ox_inventory or qb-inventory.
ox_lib: optional. Without it, keybinds and the [E] interaction prompts fall back to native FiveM equivalents.
Database: none. Cipher Drone ships no SQL and stores nothing.

Current release is v2.0.

Installation

Drop the cipher-drone folder into your resources directory.
Add the start line to server.cfg.
Add the two inventory items described in the next section.
Work through config.lua — at minimum set the allowed jobs.
Restart the resource.

ensure cipher-drone

Inventory items

Two items: pd_drone (the drone itself) and cipher_jammer (the criminal-side counterplay consumable). The drone keeps its original name so existing inventory configs from the first release still work; the jammer is new and has to be added.

QBox + ox_inventory needs one extra step. qbx_core has no server-side useable-item registration API, so out of the box both items will do nothing when used. In your ox_inventory item definitions, set:

['pd_drone'] = {
    label = 'Police Drone',
    weight = 2000,
    stack = false,
    client = { event = 'cipher-drone:client:useItem' }
},

['cipher_jammer'] = {
    label = 'Signal Jammer',
    weight = 500,
    client = { event = 'cipher-drone:client:useJammerItem' }
}

On qb-core this is automatic through Framework.CreateUseableItem — no item config changes needed.

Configuration

Everything lives in config.lua.

Who can use it

Config.General.allowAll = false
Config.General.allowedJobs = {
    police = true,
    sheriff = true,
}

With allowAll = false, only the listed jobs can deploy or connect to a drone.

Flight and HUD

Config.UI.showCompass = true
Config.UI.showRadar   = true
Config.UI.radarRange  = 300.0   -- metres; further pings clamp to the radar edge

Turn either off for a cleaner camera view. The HUD's monospace font loads from Google Fonts and degrades to a local monospace font with no internet access, so it is safe on offline and LAN setups.

Thermal

Config.Camera.thermalSeeThrough
Config.Camera.thermalSeeThroughFadeStart
Config.Camera.thermalSeeThroughFadeEnd
Config.Camera.thermalSeeThroughHighlightIntensity

The fade values are what stop thermal turning into a full-building x-ray. Raise the fade distances carefully.

Counterplay

Three systems exist so the drone is not a free win for PD. All three are on by default.

Shoot-down

Config.Drone.canBeShotDown      = true
Config.Drone.baseHealth         = 200
Config.Drone.damageMultiplier   = 3.0   -- effective HP = baseHealth / damageMultiplier
Config.Drone.destroyedFallSeconds = 2.5

Set canBeShotDown = false to make the drone immune to gunfire; invincibleIfDisabled controls that case. Damage is client-reported, the same trust model already used for battery and range.

Jamming

Config.Jamming.enabled         = true
Config.Jamming.item            = 'cipher_jammer'
Config.Jamming.maxDistance     = 60.0   -- metres from jammer to drone
Config.Jamming.durationSeconds = 20
Config.Jamming.cooldownSeconds = 90

Fire-and-forget: used at the player's current position, no aiming. It degrades the operator's control with jitter and drift rather than killing the feed. The operator sees only a JAMMED indicator and never a blip for the jammer — the stealth is deliberate.

Tracker darts

Config.Tracker.maxDistance      = 1200.0  -- metres from the dart's ORIGIN
Config.Tracker.durationSeconds  = 45
Config.Tracker.counterplay.removerItem
Config.Tracker.counterplay.removeCommand
Config.Tracker.counterplay.vehicleRemoval.zones

maxDistance is measured from where the dart was fired, not from whoever is looking at their map. An officer across the city still sees the ping as long as the target has not left the dart's range. Darts also decay in rain and water.

Before going live

Config.Drone.model is a placeholder prop (ch_prop_casino_drone_02a). Verify it spawns on your server build or swap in your own.
Config.Tracker.counterplay.vehicleRemoval.zones ships empty. Until you add bay coordinates, players have nowhere to remove a vehicle tracker.
QBox + ox_inventory servers must set the client.event values above or neither item will work.
Without ox_lib, keybinds use native RegisterKeyMapping — players rebind them from the FiveM pause menu.

Troubleshooting

Using the item does nothing

Almost always QBox + ox_inventory without the client.event mapping. See Inventory items.

The drone will not deploy

Check your job is in Config.General.allowedJobs, or set allowAll = true to rule the job gate out.

The drone prop is invisible

Config.Drone.model does not exist on your build. Replace it with a prop you have confirmed loads.

Tracker pings vanish early

The target moved beyond Config.Tracker.maxDistance from the dart's origin, the dart decayed in rain or water, or durationSeconds elapsed.

Nothing happens when a jammer is used

The drone has to be within Config.Jamming.maxDistance (60m by default), and the jammer has a 90 second cooldown between uses.

Updating

Keep a copy of your edited config.lua — updates overwrite it.
Check the recent commits for config changes before replacing files.
Replace the resource folder, merge your settings back in.
Restart the resource.

There is no database to migrate for this script.

Support

Include your framework (QBox or QBCore), your inventory resource, whether ox_lib is running, the full console error and the steps that caused it.

Join Discord View repository README