Configuration for the npc-robbery addon is defined in shared/npc-robbery/default.lua.
The addon lets players rob ambient NPCs at gunpoint using voice commands. Point a weapon at an NPC for 500ms to trigger the robbery. The NPC reacts based on personality traits (brave, cowardly, wealthy, etc.), voice commands progress through demand/threaten phases, and witnesses nearby may react or call the police.
Controls how aim detection works.
| Type | number (ms) |
| Default | 200 |
How often the aim detection raycast runs. Lower values are more responsive but slightly more CPU-intensive.
| Type | number (metres) |
| Default | 30.0 |
Maximum distance the camera raycast checks for a valid NPC target.
| Type | number (ms) |
| Default | 500 |
How long the player must continuously aim at the same NPC before the robbery triggers.
| Type | number (metres) |
| Default | 15.0 |
Maximum distance between player and NPC for a robbery to be valid. The raycast range is intentionally wider to allow detection; this clamps the actual trigger range.
| Type | string[] |
Array of weapon hash names that are considered valid robbery weapons. Only weapons in this list can trigger a robbery. Includes pistols, SMGs, and shotguns by default. Rifles and explosives are intentionally excluded.
Default weapon categories:
| Type | string[] |
NPC model hashes that cannot be robbed. Police, military, security, FIB/IAA, and prison guard models are excluded by default (19 models total). Add any model hash string to prevent it from being targeted.
Core NPC behavior settings during a robbery.
| Type | number (ms) |
| Default | 30000 |
How long an NPC stays in the hands-up state before the robbery auto-times out (30 seconds).
| Type | number (ms) |
| Default | 0 |
Delay before the NPC plays their initial fear TTS phrase after being threatened. 0 plays it immediately.
| Type | boolean |
| Default | true |
Whether the NPC continuously looks at the player while held at gunpoint.
| Type | number (ms) |
| Default | 8000 / 15000 |
Random range for how long the NPC waits after the player lowers their gun before attempting to flee. The actual per-behavior timers in behaviors override these when applicable.
| Type | number (metres) |
| Default | 100.0 |
Distance the NPC flees when escaping.
| Type | number (metres) |
| Default | 10.0 |
If the player moves further than this distance from the NPC while the robbery is active, the NPC immediately flees.
| Type | number (ms) |
| Default | 300000 (5 minutes) |
Per-NPC cooldown. The same NPC cannot be robbed again for 5 minutes after a completed robbery.
| Type | number (ms) |
| Default | 30000 (30 seconds) |
Global cooldown between any two robberies by the same player.
NPC behavior types are determined by personality traits. Each type has its own config block.
When an NPC has no relevant traits, a random behavior is assigned using these weights:
Default behavior for most NPCs with no special traits. Complies after enough pressure; may attempt to flee after gunpoint is lost.
Triggered by traits: brave, hostile, criminal_mindset. Will warn the player, potentially fight back, and escalates as the player re-aims.
Triggered by traits: coward, paranoid. May faint, freeze, or panic instead of complying normally.
Triggered by the economic trait tag. Carries more money and higher-value items; may offer a bribe or negotiate instead of complying.
| Type | boolean |
| Default | true |
Use gender-aware animation variants for hands-up and fear poses.
| Type | boolean / number (%) |
| Default | true / 30 |
Whether kneeling animations are eligible, and the percentage chance one is chosen over a standing pose.
| Type | boolean |
| Default | true |
Cycles through the animation pool instead of repeating the same pose.
| Type | boolean |
| Default | true |
Enables mid-robbery animation shifts (flinch, cower, beg) at random intervals while the player holds the NPC at gunpoint.
| Type | number (ms) / number (%) |
| Default | 4000 / 30 |
How often a dynamic reaction is checked for and the chance it triggers.
Fidget animations are disabled (fidgetEnabled = false). Upper-body fidget loops caused animation conflicts. Do not enable without testing.
Controls NPC speech responses during the robbery.
| Type | boolean |
| Default | true |
Master toggle for NPC TTS speech during robberies.
| Type | number (metres) |
| Default | 15.0 |
3D audio hearing range for robbery TTS speech.
Individual toggles for each response category:
Server-side reward calculation. Framework and inventory are auto-detected.
Wealthy NPCs have an additional exclusive item pool:
Item names must match your inventory system. For ox_inventory, use the item names defined in your items.lua. For QBCore/ESX, use the item names registered in your shared items table.
| Type | boolean |
| Default | true |
Enable voice commands during robberies. When disabled, the player cannot use voice to demand money, threaten, or give permission.
| Type | string / number |
| Default | "npc_robbery" / 70 |
Voice layer identifier and priority. At priority 70 this overrides npc_interact (55), ambient_npc (40), and shops (60).
The robbery progresses through demand and threaten phases based on voice commands:
Five command slots are registered. The default trigger phrases:
| Command | Example phrases |
|---|---|
robbery_demand | "give me what you have", "empty your pockets", "hand over the money" |
robbery_threaten | "I will shoot you", "last chance", "don't make me do this" |
robbery_hurry | "hurry up", "faster", "come on" |
robbery_permission_yes | "yes go", "you can leave", "get out of here" |
robbery_permission_wait | "wait", "stay there", "don't move" |
| Type | Flee | Freeze | Call Police | Scream | Notes |
|---|---|---|---|---|---|
cowardly | 70% | 25% | 30% | 80% | Default for most NPCs |
paranoid | 40% | 50% | 60% | 40% | Nervous types |
brave | 20% | — | 80% | 10% | May confront player (25%) |
criminal | 10% | — | 10% | 0% | Mostly ignores robbery (70%) |
neutral | 50% | 20% | 40% | 50% | Mixed reaction |
Set onPoliceCall.enabled = true and provide an event name to integrate with custom police dispatch systems (e.g. ps-dispatch, cd_dispatch). The event receives the witness ped's position.
The server script (addons/npc-robbery/server.lua) auto-detects the active framework and inventory system. No manual configuration is required.
Supported frameworks: QBCore, QBx, ESX
Supported inventories: ox_inventory (preferred), QBCore inventory, ESX inventory
Server events:
| Event | Direction | Description |
|---|---|---|
npc-robbery:giveReward | Client → Server | Request reward after successful robbery |
npc-robbery:rewardResult | Server → Client | Delivers reward summary (money amount, items, empty flag) |
Server-side cooldown: 60 seconds per player (independent of client cooldowns) to prevent exploit via resource restart.
Two client-side exports are available for other resources:
Last updated 14 days ago
