# Smoke Bunker events

> The 11 server events Smoke Bunker triggers, with their arguments and when each fires.

Listen for the 11 server events with `AddEventHandler`, or in `bridge/listeners/server.lua` (below). No client events are documented: [`getInsideSite`](/bunker/exports#getinsidesite) returns the bunker the local player is in.

## Server events

| Event | Arguments | Fires when |
| --- | --- | --- |
| `smoke_bunker:Server:Listeners:OnBunkerPurchased` | `source, bunkerId, siteKey, mode` | Org buys a bunker. |
| `smoke_bunker:Server:Listeners:OnSupplyRunStarted` | `bunkerId, mission` | Supply run starts. |
| `smoke_bunker:Server:Listeners:OnSupplyRunFinished` | `bunkerId, mission, units` | Supply run or supply order is delivered. |
| `smoke_bunker:Server:Listeners:OnDeliveryStarted` | `bunkerId, kind, units, payout` | Stock sale is dispatched. |
| `smoke_bunker:Server:Listeners:OnDeliveryFinished` | `bunkerId, kind, success, payout` | Stock sale ends. |
| `smoke_bunker:Server:Listeners:OnResearchComplete` | `bunkerId, projectId` | Research project completes. |
| `smoke_bunker:Server:Listeners:OnMissionStarted` | `bunkerId, kind, risk` | World mission starts. |
| `smoke_bunker:Server:Listeners:OnMissionFinished` | `bunkerId, kind, success, reason` | World mission ends. |
| `smoke_bunker:Server:Listeners:OnRaidStarted` | `raidId, attackerId, defenderId` | Org launches a raid. |
| `smoke_bunker:Server:Listeners:OnRaidBreached` | `raidId, attackerId, defenderId` | Raiders breach the entrance keypad. |
| `smoke_bunker:Server:Listeners:OnRaidResolved` | `raidId, attackerId, defenderId, attackerWon, stolenUnits` | Raid ends. |

## Arguments

| Argument | Type | What it is |
| --- | --- | --- |
| `source` | `number` | Buyer's server id. |
| `bunkerId` | `number` | Bunker id. |
| `siteKey` | `string` | Site `key` in `config.sites`. |
| `mode` | `'org'` or `'gang'` | How the bunker was bought. |
| `mission` | `table` | `OnSupplyRunStarted`: job from `config.missions.list`, with `name`, `location`, `units` and `seconds` (run time in timer mode). `OnSupplyRunFinished`: finished run. |
| `units` | `number` | `OnSupplyRunFinished`: units delivered. `OnDeliveryStarted`: units sold. |
| `kind` | `string` | Sale: `'local'` or `'export'`. Mission: `'order'`, `'source'` or `'sale'`. |
| `payout` | `number` | Sale value; `0` when the sale fails. |
| `success` | `boolean` | `OnDeliveryFinished`: `false` when the sale failed, for example a hijacked export convoy. `OnMissionFinished`: whether the mission succeeded. |
| `projectId` | `string` | Research project `id`, `'r1'` to `'r6'`. |
| `risk` | `string` | `'LOW'`, `'MED'` or `'HIGH'`. |
| `reason` | `string` | Why a mission ended: `abandoned`, `aborted`, `bunker_gone`, `delivered`, `hijacked`, `no_ground`, `spawn_failed`, `timeout` or `vehicle_destroyed`. |
| `raidId` | `number` | Raid id. |
| `attackerId`, `defenderId` | `number` | Raiding and raided bunker ids. `attackerId` is `0` for a raid simulated with the debug tools. |
| `attackerWon` | `boolean` | Whether the raiders took the haul. |
| `stolenUnits` | `number` | Stock units taken from the defender. |

`OnMissionStarted` and `OnMissionFinished` fire only while `missions.mode` is `'world'` (vehicle mode). A restart cancels running missions without firing `OnMissionFinished`. `OnSupplyRunStarted` fires for the jobs on the Supplies page, not for supply orders. `OnSupplyRunFinished` fires for both, on success only.

## Example

```lua server.lua
AddEventHandler('smoke_bunker:Server:Listeners:OnRaidResolved', function(raidId, attackerId, defenderId, attackerWon, stolenUnits)
    if attackerWon then
        print(('Bunker %s took %s units from bunker %s'):format(attackerId, stolenUnits, defenderId))
    end
end)
```

## Edit the listener file

`bridge/listeners/server.lua` has one function per event. Each already logs and triggers the event: keep those lines and add your code below. Do not edit above the line `DO NOT EDIT ABOVE THIS LINE`.

```lua bridge/listeners/server.lua
function listeners.onResearchComplete(bunkerId, projectId)
    Debug.log('listeners', 'onResearchComplete(%s)', { bunkerId, projectId })
    TriggerEvent('smoke_bunker:Server:Listeners:OnResearchComplete', bunkerId, projectId)
    -- your code here
end
```

<Warning>

  Do not use blocking calls, such as `Wait` or awaited callbacks, in the listeners: the simulation loop calls them.

</Warning>
