> 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/architecture.md).

# Architecture

### Principle: server-authoritative

The **server decides, the client applies**. Sensitive facts (job/gang, bypass rights, passwords, trigger conditions, cooldowns) never leave the server. Each client receives only a **safe runtime subset** of every active zone — enough to apply the effect, nothing more.

```
Panel (NUI)  ──save──►  server/zones.lua  ──toRuntime()──►  every client
   ▲                         │                                   │
   └────── open payload ◄─────┘                     client/*.lua applies effects
```

`toRuntime(zone)` in `server/zones.lua` builds that subset — shape, blip, weather, visual, npc, traffic, animals, harvest, priority, and **boolean** flags for state triggers. The webhook, password, full conditions and event names are stripped out.

### File map

#### Shared

| File                                        | Role                                        |
| ------------------------------------------- | ------------------------------------------- |
| `config.lua`                                | All configuration.                          |
| `shared/locale.lua`                         | `L()` localized notifications.              |
| `shared/geometry.lua`                       | Point-in-shape math (client + server).      |
| `shared/weather.lua`, `shared/triggers.lua` | Weather validity + `ZTrig` event whitelist. |

#### Server

| File                   | Role                                                                    |
| ---------------------- | ----------------------------------------------------------------------- |
| `server/zones.lua`     | `ZoneStore`, persistence, validation, `toRuntime`, broadcasts.          |
| `server/tracking.lua`  | Enter/exit detection, fires `zoneEntered`/`zoneExited`.                 |
| `server/combat.lua`    | PvP `weaponDamageEvent` handling.                                       |
| `server/weather.lua`   | "Everyone" weather mode.                                                |
| `server/triggers.lua`  | Trigger decisions: conditions, cooldown, once, chain, **state events**. |
| `server/groups.lua`    | Group rules, territory, capture, income.                                |
| `server/access.lua`    | Entry gates: ban/access/password/capacity/toll/rent/schedule.           |
| `server/economy.lua`   | Harvest + robbery flag.                                                 |
| `server/spawns.lua`    | Custom NPC spawns (OneSync + statebag).                                 |
| `server/admin.lua`     | Command, player actions, audit, broadcasts.                             |
| `server/framework.lua` | The `Bridge` global (aty\_lib wrapper).                                 |

#### Client

| File                                                                         | Role                                                            |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `client/zones.lua`                                                           | Zone detection loop + `ZC` state.                               |
| `client/restrictions.lua`                                                    | Applies Allow + PvP + Gameplay (incl. **DOT visual feedback**). |
| `client/weather.lua`, `client/visual.lua`                                    | Weather/time + timecycle/postFX/particles/fog/sound.            |
| `client/triggers.lua`                                                        | Applies trigger directives + **state watcher**.                 |
| `client/ambient.lua`                                                         | NPC/traffic densities, dispatch, animals.                       |
| `client/access.lua`                                                          | Barrier, eject countdown, password dialog.                      |
| `client/blips.lua`, `client/hud.lua`, `client/nui.lua`, `client/effects.lua` | Blips, HUD, NUI bridge, admin effects.                          |

#### Web (NUI)

Vue 3 (`<script setup>`) + Vite + Pinia. Built to `web/dist`; source in `web/src`. Rebuild with `npm run build` after editing UI or locales.

### Overlap resolution

* **Single-value** settings (weather, visuals, ped aggression, driving style, animals) → the **highest-priority** zone wins.
* **Restrictions** (weapons, speed, DOT, etc.) → **union / most-restrictive** — the strictest zone wins, always, for safety.

### DOT visual feedback

The periodic damage is **felt**, not just shown on the HP bar. From the same 1s tick, `client/restrictions.lua` layers per-type effects:

| DOT type  | Effect                                                  |
| --------- | ------------------------------------------------------- |
| Fire      | The ped genuinely burns (`StartEntityFire`).            |
| Radiation | Looped sickly-green screen warp (postFX).               |
| Gas       | Green smoke on the ped + coughing + occasional stumble. |
| Electric  | Shock ragdoll + camera jolt every few seconds.          |
| Cold      | Persistent shiver (hand-shake cam).                     |

The layer is torn down on exit, on death, and on safe-zone override, and rebuilt on respawn.

### Persistence

`Config.Storage`:

* `'json'` → `zones.json` in the resource folder.
* `'oxmysql'` → the `aty_zones` table (created automatically).

Saves are rate-limited per source (`Config.SaveCooldown`).