Installation

Download

Download the latest release from the FiveM Portal.

Extract wlabs_handcuff into your resources folder.

Inventory Items

Add items to your inventory system:

Add to ox_inventory/data/items.lua:

['handcuffs'] = {
    label = 'Handcuffs',
    weight = 250,
    stack = true,
    close = true,
},
['handcuff_key'] = {
    label = 'Handcuff Key',
    weight = 50,
    stack = true,
    close = true,
},
['cable_ties'] = {
    label = 'Cable Ties',
    weight = 100,
    stack = true,
    close = true,
},
['lockpick'] = {
    label = 'Lockpick',
    weight = 50,
    stack = true,
    close = true,
},

Configuration

Configure the script by editing shared/config.lua.

Start Order

Add to your server.cfg (adjust to your setup):

ensure ox_lib
ensure xsound
ensure qb-core         # or es_extended
ensure ox_inventory    # or qb-inventory
ensure ox_target       # optional
ensure wlabs_handcuff

Install xsound for restraint sounds:

Download the latest non-experimental release from Xogy/xsound releases
Drag it into your server resources folder
Rename the folder to xsound
Do not leave it as xsound-1.5.1
Drag and drop the html folder from wlabs_handcuff over the xsound folder and allow it to merge/overwrite when prompted
Your sound files must end up here:
- xsound/html/sounds/handcuff_cuff.ogg
- xsound/html/sounds/handcuff_uncuff.ogg
- xsound/html/sounds/ziptie_cuff.ogg

Configuration

Auto-Detection

By default, the script automatically detects:

Framework (qbx_core, qb-core, es_extended)
Inventory (ox_inventory, qb-inventory)
Target System (ox_target, qb-target)

Force a Specific System

To force a specific system, edit shared/config.lua:

Config.Framework = 'qb'     -- 'auto', 'esx', 'qb', 'qbox', 'none', 'custom'
Config.Inventory = 'ox'     -- 'auto', 'ox', 'qb', 'none', 'custom'
Config.Target = 'ox'        -- 'auto', 'ox', 'qb', 'none', 'custom'

Disable Integrations

You can disable specific integrations if you do not use them:

Config.Framework = 'none'   -- disables framework job checks
Config.Inventory = 'none'   -- disables inventory checks (items always pass)
Config.Target = 'none'      -- disables target registration

Restraint Sounds

Restraint sounds are configured in shared/config.lua under Config.Sounds.

Default mapping:

Config.Sounds = {
    enabled = true,
    cooldownMs = 1000,
    effects = {
        handcuff_cuff = { file = 'handcuff_cuff.ogg', volume = 0.35, range = 8.0 },
        handcuff_uncuff = { file = 'handcuff_uncuff.ogg', volume = 0.35, range = 8.0 },
        ziptie_cuff = { file = 'ziptie_cuff.ogg', volume = 0.35, range = 8.0 },
    },
    mappings = {
        cuffs = { cuff = 'handcuff_cuff', uncuff = 'handcuff_uncuff' },
        cable_ties = { cuff = 'ziptie_cuff', uncuff = 'handcuff_uncuff' },
    },
}

Notes:

volume is 0.0 to 1.0
range controls the 3D hearing distance in xsound
Sounds are server-triggered only after a validated cuff or uncuff action
A server cooldown is applied so the sound event cannot be spammed separately from the restraint logic
Sound files are expected directly inside xsound/html/sounds/

Allowed Jobs

Configure which jobs can use the handcuff system:

Config.AllowedJobs = {
    ['police'] = 0,     -- police job, grade 0+
    ['sheriff'] = 0,    -- sheriff job, grade 0+
    ['ambulance'] = 2,  -- ambulance job, grade 2+
}

ACE Permissions

The script supports config-driven ACE permissions in addition to job checks.

Default config:

Config.Permissions = {
    enabled = false,
    mode = 'either', -- 'jobs', 'ace', 'either', 'both'
    hideUiWhenNoPermission = true,
    adminNode = 'wlabs_handcuff.admin',
    nodes = {
        cuff = 'wlabs_handcuff.cuff',
        uncuff = 'wlabs_handcuff.uncuff',
        drag = 'wlabs_handcuff.drag',
        vehiclePut = 'wlabs_handcuff.vehicle.put',
        vehicleRemove = 'wlabs_handcuff.vehicle.remove',
        breakLockpick = 'wlabs_handcuff.break.lockpick',
        breakKnife = 'wlabs_handcuff.break.knife',
    },
}

Example server.cfg ACE setup:

add_ace group.police wlabs_handcuff.cuff allow
add_ace group.police wlabs_handcuff.uncuff allow
add_ace group.police wlabs_handcuff.drag allow
add_ace group.police wlabs_handcuff.vehicle.put allow
add_ace group.police wlabs_handcuff.vehicle.remove allow
add_ace group.police wlabs_handcuff.break.lockpick allow
add_ace group.police wlabs_handcuff.break.knife allow
add_ace group.admin wlabs_handcuff.admin allow

add_principal identifier.license:YOUR_LICENSE_HERE group.police
add_principal identifier.license:YOUR_LICENSE_HERE group.admin

Breakout Mechanics

Players can attempt to break out of restraints using items defined in Config.BreakCuffs.

Lockpicking: Used for metal handcuffs (cuffs). Requires a lockpick item and involves a skill check.
Cutting: Used for plastic restraints (cable_ties). Requires a weapon_knife (or any item defined in Config.BreakCuffs.knife.item) and involves a progress bar.

Locale

The script supports multiple languages via locales/*.json. To change the language:

setr ox:locale en   # English (default)
setr ox:locale de   # German

Installation

On this page