FiveM hostage script

Hostage documentation

Hostages for FiveM. Aim a gun or a knife at an NPC or a player. When they give up, press [E] to control them:

• kneel;
• tie;
• bag;
• take along;
• put in your car;
• human shield;
• search;
• release.

Police get an alert. Everything is synced for every player, and the server checks every action.

• Version 1.1.1
• Requirements: FXServer build 35245+, OneSync (the manifest declares /onesync) and ox_lib. No database.
• Frameworks: QBCore · Qbox Legacy · standalone · 'custom' (see Integrations / Custom)
• Languages: es · en
• No lock-in: rolo_notify and every other ROLO SCRIPT resource are optional. Without rolo_notify the script uses ox_lib, your framework's notifications or the base game.
• No tickets needed: everything you may want to adapt is in open files (see Escrow: what is open).

Features

• 🔫 Guns and knives scare people (configurable list; tasers and other tools never do). Guns work from a distance, blades up close.
• 🧍 NPCs react like people:
  • most raise their hands;
  • some run;
  • gang members may pull a pistol;
  • police, security and military never surrender.
  • Drivers of a stopped car get out with their hands up, and hand you the keys of their car (Config.NPC.carKeys: 'auto' as they get out, 'menu' = Ask for the keys in the hostage menu, or false; carKeysChance = % that they agree, with one more try from the menu). It works with your vehicle keys script.
• 🙋 Players decide: they get a warning when someone aims at them and raise their hands with [X] (rebindable). Once they have given up, the captor can take them hostage.
• 🧎 Kneel / stand up (hands up), tie hands (no item needed by default), bag over the head (a real prop; the player sees almost nothing).
• 🚶 Take along: the hostage walks behind you, and speeds up if they fall behind.
• 🚗 Put in / take out of a vehicle: rear seats first. The hostage stays seated while you drive.
• 🛡️ Human shield with one-handed weapons (pistols, SMG pistols, knives). You can't sprint, jump or get in a car while holding someone.
• 🔍 Search:
  • NPCs: one random thing from a weighted list (aluminium, water, food, $1-2 of dirty money by default), sometimes nothing; no clean cash unless you set it; once per person;
  • players: opens their inventory (ox_inventory, origen_inventory, qs-inventory, qb-inventory; custom branch for others).
• 🏃 Untied hostages can run away if you stop threatening them for a while. Tied players can try to break free with a skill check every X seconds.
• 👮 Police alerts for a hostage taken and for an armed carjacking (an NPC driver getting out at gunpoint, with the car model, plate and street; Config.Police.carjack, it reaches the police after carjackDelaySeconds, 5 s by default, while the hostage call uses delaySeconds, 20 s). Each has its own cooldown. Always, only when an NPC witness sees it, or never. Supported systems:
  • origen_police, ps-dispatch, cd_dispatch, qs-dispatch, core_dispatch, rcore_dispatch;
  • with no dispatch, officers on duty get a notification and a blip.
• 🔒 Safe:
  • the server keeps who holds whom;
  • hostages are released when anyone dies, disconnects or gets handcuffed by the police;
  • a maximum number of hostages per player;
  • protected jobs.
• 📊 Discord logs: hostage taken, released, escaped, police alert.
• ⚡ Light: loops sleep while you have no weapon out and no hostage.
• 🌍 Spanish and English (locales/). QBCore, Qbox, ESX, standalone or 'custom'. Notifications, "[E]" texts and progress bars go through rolo_notify automatically, with ox_lib, qb-core or okok as alternatives.

Dependencies

• ox_lib (menu, skill check, callbacks)
• Optional: rolo_notify (notifications, "[E]" bubbles, progress bars)
• Optional: your inventory (to search players and give or take items), vehicle keys script and police dispatch: see Compatibility.

Installation

1. Put rolo_hostage in your resources folder.
2. In server.cfg, after ox_lib (and your framework / inventory):

   ensure rolo_hostage
   

3. Restart. That's all: there is no database and no item is needed.
4. Optional:
   • require items (Config.Tie.item, Config.Bag.item);
   • set your police jobs (Config.Police.jobs) and dispatch (Config.Police.system).

How to use

Keys can be changed by every player in Settings > Key Bindings > FiveM.

Configuration (config.lua)

Exports

-- server
exports.rolo_hostage:IsHostage(src)          -- true while that player is a hostage
exports.rolo_hostage:GetCaptor(src)          -- server id of their captor or nil
exports.rolo_hostage:GetHostages(captor)     -- { { kind, target, netId, state, tied }, ... }
exports.rolo_hostage:ReleaseHostages(captor) -- frees everybody that player holds
exports.rolo_hostage:FreePlayer(src)         -- frees one player hostage (e.g. from your police script)

-- client
exports.rolo_hostage:IsHostage()             -- this player is a hostage
exports.rolo_hostage:HandsUp()               -- this player has the hands up
exports.rolo_hostage:IsCaptor()              -- this player holds somebody
exports.rolo_hostage:GetMyHostages()

Server events for other scripts: rolo_hostage:taken (captor, kind, target / netId) and rolo_hostage:released (captor, kind, target / netId, reason).

Integrations / Custom

Everything you may want to adapt is in open files (config.lua, locales/, bridge/, compat/): you never need the escrowed code.

Events (server) for your scripts (Discord, stats, jail, rewards...):

AddEventHandler('rolo_hostage:taken', function(captor, kind, target) end)
-- kind = 'npc' | 'player'; target = the player's server id, or the NPC's netId

AddEventHandler('rolo_hostage:released', function(captor, kind, target, reason) end)
-- reason: 'release' (let go) | 'escaped' | 'fled' | 'lost' | 'down' (died) | 'left' (disconnected)
--         | 'police' (cuffed by the police) | 'captor_left' | 'captor_down'

Exports: see Exports above (IsHostage, GetCaptor, GetHostages, ReleaseHostages, FreePlayer, and on the client IsHostage, HandsUp, IsCaptor, GetMyHostages). Example, free a player when your police script cuffs them:

exports.rolo_hostage:FreePlayer(source)

Where to plug in your own system ('custom')

Examples:

-- bridge/server.lua  (Config.Framework = 'custom')
function Bridge.AddCash(src, amount) MyFramework.AddMoney(src, 'cash', amount) end

-- bridge/server.lua  (Config.Police.system = 'custom')
function Bridge.PoliceAlert(src, data)
    exports['my_dispatch']:Send({ coords = data.coords, title = data.title, message = data.message })
end

-- compat/client.lua  (Config.VehicleKeys = 'custom')
Compat.CustomKeys = { give = function(vehicle, plate) exports['my_keys']:Give(plate) end, remove = function(vehicle, plate) exports['my_keys']:Remove(plate) end }

Anything you leave empty is skipped and the script keeps working without that part.

Escrow: what is open

These files stay open (editable) when the resource is escrowed, exactly as escrow_ignore in fxmanifest.lua says:

• config.lua and config_server.lua (Discord webhooks, server only);
• locales/*.lua: every text;
• bridge/*.lua: bridge/client.lua (notifications, "[E]" texts, progress bar, skill check, opening a player's inventory, client dispatch) and bridge/server.lua (framework, money, items, inventories, handcuff check, police alerts, Discord logs);
• compat/*.lua: inventories, vehicle keys, fuel.

The rest of the Lua code (client/, server/, shared/) is encrypted. Everything a buyer may need to adapt has a 'custom' hook in the open files above.

Notes

• The script leaves players handcuffed by the police alone. On QBCore / Qbox this is detected from metadata.ishandcuffed; for other police scripts, edit Bridge.IsCuffed.
• Animations and props are from the base game.

---

ROLO SCRIPT · Support and updates on our Discord.

Secrets: config_server.lua

Discord webhooks and API keys go in config_server.lua, not in config.lua. config.lua is sent to every player's game (FiveM shares it), so anything in it can be read by a cheater; config_server.lua is loaded only by the server. Paste your webhooks there and leave config.lua without secrets.

Compatibility

The shared compatibility core (compat/server.lua + compat/client.lua, open files) detects your systems on start and prints them in the server console, e.g. compat: framework qbcore · inventory ox_inventory · garages qb-garages · society qb-banking.

• Frameworks: QBCore, Qbox, ESX Legacy, standalone, 'custom'.
• Inventories: ox_inventory, origen_inventory, qs-inventory, codem-inventory, core_inventory, qb-inventory, ps-inventory / lj-inventory / tgiann-inventory (through the QBCore player functions). Config.Inventory = 'custom' + Compat.CustomInventory. Searching another player's inventory is supported on ox_inventory, origen_inventory, qs-inventory and qb-inventory; other inventories: 'custom'.
• Vehicle keys (NPC carjacking): qb-vehiclekeys, qbx_vehiclekeys, qs-vehiclekeys, wasabi_carlock, MrNewbVehicleKeys, Renewed-Vehiclekeys, mk_vehiclekeys, cd_garage (Config.VehicleKeys, 'custom' + Compat.CustomKeys).
• Police dispatch: origen_police, ps-dispatch, cd_dispatch, qs-dispatch, core_dispatch, rcore_dispatch, 'jobs' (notification + blip to officers on duty), 'custom', 'none'.
• Optional ROLO SCRIPT resources (rolo_notify): used when they run, never required.
• Errors are printed in the console with the system's name, never silent.
• Names and columns follow each script's public documentation. Test once after installing with your own setup.