# qb-busjob

`qb-busjob` is a small, self-contained job. A player with the `bus` job takes a bus, drives to
scripted stops, and NPCs board and pay. There is no shift state, no deposit, and no database table.

Compare with [qb-taxijob](/docs/resources/qb-taxijob), which has a meter and per-fare pricing, and
[qb-truckerjob](/docs/resources/qb-truckerjob), which runs delivery missions.

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

## Dependencies and start order

From the manifest: `@qb-core/shared/locale.lua` plus locales as shared scripts, and the PolyZone
client files `client.lua`, `BoxZone.lua`, `EntityZone.lua`, `CircleZone.lua`, `ComboZone.lua`.

Start order: `qb-core`, `PolyZone`, then `qb-busjob`. The server script uses
`exports['qb-core']:GetPlayer` and `Player.AddMoney`, so `qb-core` is required even though the
manifest does not declare it.

## Configuration

`config.lua` is loaded as a shared script.

| Key | Meaning |
| --- | --- |
| `Config.AllowedVehicles` | Bus models the job accepts |
| `Config.Location` | `vector4(462.22, -641.15, 28.45, 175.0)`, the depot |
| `Config.NPCLocations` | The route stops, under a `Locations` sub-table |
| `Config.NpcSkins` | Ped models used for passengers |

There is no configurable pay value. The payout is hardcoded in `server/main.lua`.

## Payout

One server event does all the work.

```lua
RegisterNetEvent('qb-busjob:server:NpcPay', function()
```

It takes no arguments, which is the point: nothing about the payment is supplied by the client. On
the server it:

1. Resolves the player from `source`.
2. Requires `Player.PlayerData.job.name == 'bus'`, otherwise `DropPlayer`.
3. Enforces a 10 second per-source cooldown, otherwise `DropPlayer`.
4. Requires the player's server-side coordinates to be within 20 units of a configured stop,
   otherwise `DropPlayer`.
5. Pays `math.random(15, 25)` cash, with a bonus of `math.random(10, 20)` on a random roll.

A `playerDropped` handler clears the cooldown entry so the table does not grow.

This is a good template for a job payout event. The amount is decided on the server, the position is
read on the server, and there is a rate limit. Contrast with
[qb-hotdogjob](/docs/resources/qb-hotdogjob), where the price arrives from the client.

The bonus roll is `math.random(1, 5)` compared against two other `math.random(1, 5)` draws, so the
bonus fires more often than a single one-in-five chance. Adjust in `server/main.lua` if you want a
predictable rate.

## Setup

1. Add a `bus` job to your shared jobs list.
2. Make sure every model in `Config.AllowedVehicles` and `Config.NpcSkins` is streamable.
3. Set the depot and route coordinates for your map.
4. Start `qb-core` and `PolyZone` before this resource.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| Player is dropped on every pickup | The job name is not exactly `bus`, or the stop coordinates in `Config.NPCLocations.Locations` are more than 20 units from where the player actually stops |
| Passengers never spawn | A ped model in `Config.NpcSkins` failed to load |
| No payment, no drop | The 10 second cooldown is still active from the previous stop |
| Zones never trigger | PolyZone is not started before this resource |

## Proposed manual smoke test

Not yet executed. On staging:

1. Take the job, confirm payment on a normal stop.
2. Trigger two stops inside 10 seconds and confirm the drop.
3. Take a bus without the `bus` job and confirm the drop.
4. Disconnect mid route and reconnect, confirm the cooldown table cleared.

## Sources

- [fxmanifest.lua](https://github.com/qbcore-fivem/qb-busjob/blob/ad7492746d5bde7fae5c96ca62c7b74474478e2e/fxmanifest.lua)
- [config.lua](https://github.com/qbcore-fivem/qb-busjob/blob/ad7492746d5bde7fae5c96ca62c7b74474478e2e/config.lua)
- [server/main.lua](https://github.com/qbcore-fivem/qb-busjob/blob/ad7492746d5bde7fae5c96ca62c7b74474478e2e/server/main.lua)
