prp-atmrobbery

Server-authoritative ATM robbery for FiveM with Qbox-first support, multi-method gameplay, heat/fatigue anti-farm, and PvE no-cops mode.

1) Overview

prp-atmrobbery is a server-authoritative ATM robbery resource with adapter-based compatibility.

Design goals:

• secure reward flow
• low support burden
• works with cops and no-cops servers
• Qbox-first without locking out QB/ESX/standalone

2) Requirements

Required

• ox_lib

Framework

• qbx_core, qb-core, es_extended, or standalone

Inventory

• ox_inventory, qb-inventory, or ESX inventory bridge

Target

• ox_target or qb-target
• fallback: Config.ATM.AimFallback.Enabled = true

Optional Integrations

• dispatch: ps-dispatch, cd_dispatch, qs-dispatch, core_dispatch
• minigame: bl_ui

3) Installation

1. Place resource in your server resources folder.
2. Ensure startup order:

   ensure ox_lib
   ensure <framework>
   ensure <inventory>
   ensure <target>
   ensure prp-atmrobbery

3. Configure provider modes in config.lua.
4. Add required items to your inventory system.
5. Restart the resource.
6. Run /atmrobbery:doctor and verify detected providers.

4) Provider Modes

Set in config.lua:

Config.Framework = 'auto' | 'qbox' | 'qbcore' | 'esx' | 'standalone'
Config.Target = 'auto' | 'ox' | 'qb'
Config.Inventory = 'auto' | 'ox' | 'qb' | 'esx'
Config.Notify = 'auto' | 'ox' | 'qb' | 'esx' | 'standalone'
Config.Integrations.Dispatch = 'auto' | 'ps-dispatch' | 'cd_dispatch' | 'qs-dispatch' | 'core_dispatch' | 'none'
Config.Integrations.Minigame = 'auto' | 'bl_ui' | 'none'

5) Gameplay Methods

Default enabled methods:

• carding
• hacking
• drilling

Each method supports:

• label and duration
• reward range
• loudness and alert chance
• per-method min police override
• per-method success/fail cooldown override
• risk profile (break chance, heat gain, fatigue gain)

Configured at Config.Methods.Enabled and Config.Methods.Definitions[methodName].

6) Security Model

Server validations include:

• player distance
• ATM ID integrity (coords hash check)
• token/session ownership
• completion gate timing
• cooldown and rate limiting
• item requirements and item consumption
• police job restrictions and count checks

Security profile system:

• Config.SecurityProfile = 'rp' | 'mixed' | 'pve'
• profile values merge first
• Config.Security overlays profile values

7) Heat/Fatigue Economy Controls

Module: server/heat.lua

Behavior:

• tracks per-ATM heat and per-player fatigue
• decays every Config.Heat.TickSeconds
• applies payout nerf
• can block payout at hard limits
• extends cooldown after successful robberies

8) PvE No-Cops Mode

Config block: Config.PvE

When enabled and policeCount == 0:

• applies no-cops method multiplier
• optionally rolls bonus loot
• loot can be blocked at high ATM heat

9) Reward Modes

Config:

• Config.Rewards.Mode = 'item' | 'cash'
• Config.Rewards.CashAccount = 'cash'

11) Commands and Permissions

ACE permission: atmrobbery.admin

Default commands:

• atmrobbery:resetatm <atmId>
• atmrobbery:resetplayer <source>
• atmrobbery:setcooldown <atmId> <seconds>
• atmrobbery:snapshot
• atmrobbery:doctor

15) Troubleshooting

"No ATM found nearby"

• Increase Config.ItemUse.MaxDistance
• confirm model exists in Config.ATM.Models

"Action failed"

• run /atmrobbery:doctor
• verify provider auto-detection
• check item names in inventory definitions

Cooldown confusion

• check per-method cooldown override
• check heat-based cooldown extension
• run /atmrobbery:snapshot