# qb-truckrobbery

`qb-truckrobbery` is a single-player-at-a-time armored truck mission. A player pays an activation
fee to an NPC dealer, a truck with an armed driver and navigator spawns at a random location, and the
player plants a bomb on it for a `markedbills` payout.

It is the only robbery in this set that charges a bank fee to start, and the only one with a global
"one mission at a time" lock.

The manifest at the commit linked above declares version `1.5.0`.

## Legacy event names

This resource was adapted from a non-QBCore script and kept the original Polish event names. They
are not typos and renaming them means editing both sides.

| Event | Side | Purpose |
| --- | --- | --- |
| `AttackTransport:akceptujto` | server | Player accepts the mission |
| `AttackTransport:Pozwolwykonac` | client | Server grants permission to start |
| `AttackTransport:zawiadompsy` | server | Relay an alert position |
| `AttackTransport:InfoForLspd` | client | Broadcast of that position |
| `AttackTransport:graczZrobilnapad` | server | Player completed the robbery, request payout |
| `AttackTransport:CleanUp` | client | Broadcast mission reset |
| `qb-armoredtruckheist:server:callCops` | server | Alarm relay |
| `qb-armoredtruckheist:client:robberyCall` | client | Alarm broadcast |

Because `AttackTransport:*` is not namespaced to this resource, check for collisions if you also run
another armored truck script.

## Dependencies and start order

The manifest declares no dependencies and loads a shared config, one client script, and one server
script. The implementation requires:

- `qb-core` for `GetCoreObject`, `GetPlayer`, `GetShared('Items')`, and `QBCore:Notify`
- [qb-inventory](/docs/resources/qb-inventory) for `AddItem` and the item box

Start `qb-core` and `qb-inventory` first.

## Configuration

`config.lua` is a shared script.

| Key | Default | Meaning |
| --- | --- | --- |
| `Config.MissionMarker` | `vector3(960.71, -215.52, 76.26)` | Where the mission marker is drawn |
| `Config.DealerCoords` | `vector3(960.78, -216.25, 76.25)` | Where the NPC dealer stands |
| `Config.VehicleSpawn` | five vector3 entries | Truck spawn points, one picked at random |
| `Config.DriverWeap` | `` `WEAPON_MICROSMG` `` | Weapon the driver spawns with |
| `Config.NavWeap` | `` `WEAPON_MICROSMG` `` | Weapon the navigator spawns with |
| `Config.TimeToBlow` | `30` | Seconds between planting and detonation |
| `Config.ActivePolice` | `2` | On-duty law enforcement required to accept |
| `Config.Payout` | `{ Min = 250, Max = 450 }` | `worth` range per `markedbills` bag |
| `Config.ActivationCost` | `500` | Bank charge to accept the mission |
| `Config.Currency` | `'$'` | Symbol used in notifications only |
| `Config.ResetTimer` | `600` | Seconds until the mission slot frees up again |

The payout is one to three `markedbills` bags, each with a `worth` rolled inside `Config.Payout`.
There is a one-in-twenty chance of an additional `security_card_01`. Both item names must exist in
your shared items list.

Duty counting accepts `job.name == 'police'` or `job.type == 'leo'`.

## Mission acceptance

`AttackTransport:akceptujto` is the entry point. On the server it:

1. Refuses if `ActiveMission` is already 1.
2. Refuses if the player's bank balance is below `Config.ActivationCost`.
3. Counts on-duty law enforcement and refuses below `Config.ActivePolice`.
4. Removes `Config.ActivationCost` from the bank with the reason `armored-truck`.
5. Records the accepting player in `MissionPlayer` and starts the reset timer.

The activation fee is charged before the truck exists. If the player disconnects or the truck fails
to spawn, the money is not refunded at this commit.

## Payout guards

`AttackTransport:graczZrobilnapad` accepts a `lootTime` argument from the client. At this commit it
checks, in order:

1. `ActiveMission` must be 1.
2. `MissionPlayer` must equal the event `source`, so only the accepting player is paid.
3. `lootTime` must be a number greater than zero.
4. A per-source cooldown of `Config.ResetTimer` seconds must have elapsed since the last payout.

Each rejection prints a line to the server console naming the source and the reason, which makes it
usable as a low-effort exploit signal. Grep for `[qb-truckrobbery] Reward rejected`.

`lootTime` is validated for type and sign but not used for anything else. It does not scale the
payout, so a forged value cannot inflate the reward. The payout comes entirely from `Config.Payout`
on the server.

What is not checked is distance. The event does not verify the player is anywhere near the truck, so
the mission-owner and cooldown checks are the only things standing between a modified client and one
payout per `Config.ResetTimer`. Compare with
[qb-storerobbery](/docs/resources/qb-storerobbery), which does re-check server-side distance before
granting.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| "Someone is already carrying out this mission" that never clears | `ActiveMission` is stuck at 1. It resets after `Config.ResetTimer` seconds or on resource restart |
| Player charged but no truck | The activation fee is removed before the client spawns anything. Check the client console for a model load failure |
| No payout after a successful robbery | Check the server console for a `Reward rejected` line naming the reason |
| Mission never accepted | Not enough law enforcement on duty, or bank balance below `Config.ActivationCost` |
| Payout items missing | `markedbills` or `security_card_01` is absent from your shared items |
| Event name collisions | Another resource also registers `AttackTransport:*` |

## Proposed manual smoke test

Not yet executed. On staging:

1. Accept with fewer than `Config.ActivePolice` on duty and confirm the refusal.
2. Accept with an insufficient bank balance and confirm the refusal.
3. Complete one mission and confirm the bags arrive with a `worth` inside `Config.Payout`.
4. Trigger the payout event a second time and confirm the cooldown rejection appears in the console.
5. Wait out `Config.ResetTimer` and confirm a second player can accept.

## Sources

- [fxmanifest.lua](https://github.com/qbcore-fivem/qb-truckrobbery/blob/e7840b624a42c665b229ba5dfbfa959c4acd9906/fxmanifest.lua)
- [config.lua](https://github.com/qbcore-fivem/qb-truckrobbery/blob/e7840b624a42c665b229ba5dfbfa959c4acd9906/config.lua)
- [server.lua](https://github.com/qbcore-fivem/qb-truckrobbery/blob/e7840b624a42c665b229ba5dfbfa959c4acd9906/server.lua)
