> For the complete documentation index, see [llms.txt](https://atiysus-organization.gitbook.io/aty-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atiysus-organization.gitbook.io/aty-scripts/zone-creator/developer/triggers-and-hooks.md).

# Triggers & Hooks

The **Triggers & Events** section lets an admin fire *your* event when something happens in a zone. You type the event name in the panel; your script listens for it. This is the main integration surface.

### Security: the event whitelist

Only event names starting with a `Config.TriggerPrefixes` entry can be fired:

```lua
Config.TriggerPrefixes = {
    'aty_zonecreator:',
    'aty_zones:',      -- free space for your own zone integrations
}
```

Add your own prefix (e.g. `'my-script:'`) to use `my-script:whatever`. The filter runs on **both** server and client — even a tampered `zones.json` can't fire an arbitrary money/item/admin event.

### Activity triggers

Configured per zone with a **type** (client/server) and an event name.

| Field               | Server signature | Client signature | Fires when                      |
| ------------------- | ---------------- | ---------------- | ------------------------------- |
| On Enter            | `(src, zoneId)`  | `(zoneId)`       | player enters                   |
| On Exit             | `(src, zoneId)`  | `(zoneId)`       | player leaves                   |
| While Inside (tick) | `(src, zoneId)`  | `(zoneId)`       | every *interval* seconds inside |

```lua
-- On Enter (type=client) event 'aty_zones:enterLab'
AddEventHandler('aty_zones:enterLab', function(zoneId)
    exports['my-drugs']:StartLab()
end)

-- While Inside (type=server, 10s) event 'aty_zones:labGasTick'
AddEventHandler('aty_zones:labGasTick', function(src, zoneId)
    local ped = GetPlayerPed(src)
    SetEntityHealth(ped, GetEntityHealth(ped) - 8)
end)
```

### State triggers

Fire on a **player state change** while inside a zone. Detection is client-side but the **decision is server-side**: the server confirms real membership, that the trigger is configured, that conditions pass, and applies an anti-spam window (death 2s, vehicle 1s, weapon 5s). For `onDeath` it also verifies the ped is really dead.

| Field            | Server signature | Fires when                       | Classic use                     |
| ---------------- | ---------------- | -------------------------------- | ------------------------------- |
| On Death         | `(src, zoneId)`  | player dies inside               | **auto-revive at the hospital** |
| On Vehicle Enter | `(src, zoneId)`  | gets into a vehicle inside       | getaway detection, valet        |
| On Vehicle Exit  | `(src, zoneId)`  | gets out of a vehicle inside     | parking checks                  |
| On Weapon Fire   | `(src, zoneId)`  | shots fired inside (5s throttle) | gunshot alert for police        |

#### Auto-revive example

```lua
-- On Death (type=server) event 'aty_zones:zoneDeath'  (Pillbox / arena zones)
AddEventHandler('aty_zones:zoneDeath', function(src, zoneId)
    -- qb-ambulancejob
    TriggerClientEvent('hospital:client:Revive', src)
    -- esx_ambulancejob
    -- TriggerClientEvent('esx_ambulancejob:revive', src)
end)
```

### Conditions, cooldown, once, chain

Configured alongside the events and **enforced on the server**:

* **Required item / job** — the trigger (and its On-Inside tick) only runs if the player has the item / holds the job.
* **Cooldown** — minimum seconds between fires per player+zone.
* **One-Time** — fires once per player per session (reset on disconnect/restart).
* **Chain Zone** — activates another (inactive) zone by label on enter.

### Config callback hooks

Two integration callbacks live in `config.lua` (`Config.Integrations`):

```lua
onPhoneLock       = function(locked) exports['my-phone']:SetDisabled(locked) end,
onWeatherOverride = function(taking) exports['my-weather']:PauseSync(taking) end,
```

### Ready-made examples

The `examples/` folder ships working reference handlers for **every** hook above, wired to the demo zones and gated behind `Config.ExampleHooks`. See `examples/README.md`. Turn `Config.ExampleHooks = false` (or remove the two files from `fxmanifest.lua`) once you've wired your own scripts.