> 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/developer/data-scheme.md).

# Data Scheme

A zone is a JSON object (in `zones.json` or the `aty_zones` table). This is the shape produced by the panel and consumed by the server. You normally never edit it by hand — but it's documented for backups, migrations and bulk edits.

### Top-level

```jsonc
{
  "id": "zone_ab12cd",        // internal id (unique)
  "zoneId": "aty_x7k9q2",     // stable public id — used by exports
  "label": "Humane Labs",
  "description": "",           // admin-only note
  "category": "Restricted",
  "color": "#7dff8a",         // hex; drives overlay + blip color
  "active": true,              // false = saved but inert
  "visible": true,             // map overlay visibility (editor only)
  "priority": 5,               // 1-10, overlap winner for single-value settings
  "minZ": -50, "maxZ": 200,    // height limits
  "preview": "walls",          // walls | marker | outline | none
  "shape": { ... },            // see below
  "settings": { ... },         // the 15 categories, see below
  "createdAt": 1731000000000
}
```

### Shape

```jsonc
// circle
{ "type": "circle", "center": { "x": 215.0, "y": -920.0 }, "radius": 140.0 }

// box (x,y = a corner; w,h = size)
{ "type": "box", "x": 750.0, "y": -3350.0, "w": 450.0, "h": 350.0 }

// polygon (world-space points, max Config.MaxPolyPoints)
{ "type": "polygon", "points": [ { "x": -2050, "y": 2600 }, { "x": -1400, "y": 2720 } ] }
```

Coordinates are **GTA world space** — no calibration needed.

### Settings (15 categories)

Each key holds one section. Abridged shape (see Zone Settings for meanings):

```jsonc
"settings": {
  "weather":  { "enabled": false, "type": "EXTRASUNNY", "blendTime": 15, "freezeTime": false,
                "hour": 12, "windSpeed": 0, "windDirection": 0, "snowOnGround": false,
                "sync": "everyone", "cycleEnabled": false, "cycle": [] },
  "pvp":      { "enabled": false, "friendlyFire": false, "damageMultiplier": 1,
                "weaponPolicy": "all", "weapons": [], "bypassGroups": [],
                "headshots": true, "holsterOnEnter": false },
  "npc":      { "pedDensity": 100, "scenarioPeds": true, "aggression": "Neutral",
                "policeDispatch": true, "maxWantedLevel": 5, "corpseCleanup": 60,
                "npcWeapons": true, "spawns": [] },
  "animals":  { "enabled": false, "species": [], "density": 50, "behavior": "Neutral",
                "flock": false, "nightVariants": false },
  "traffic":  { "density": 100, "parkedDensity": 100, "blockedClasses": [],
                "bypassGroups": [], "emergencyServices": true, "drivingStyle": "Normal",
                "emptyRoads": false, "maxSpeed": 0 },
  "visual":   { "timecycle": "None", "postFx": "None", "enterEffect": "None",
                "ambientSound": "None", "soundVolume": 50, "particles": "None",
                "particleIntensity": 50, "fogDensity": 0, "fogColor": "#ffffff" },
  "allow":    { "weaponUse": true, "vehicleUse": true, "speedLimitEnabled": false,
                "speedLimit": 80, "sprint": true, "jump": true, "phone": true,
                "inventory": true, "itemUse": true, "itemDrop": true, "voice": true,
                "bypassGroups": [] },
  "groups":   { "accessMode": "everyone", "groups": [], "rules": [],
                "territoryEnabled": false, "territoryOwner": "", "capturable": false,
                "captureTime": 10, "incomePerHour": 0, "notifyOnEnter": false,
                "notifyColor": "#69ffec", "allies": [], "enemies": [] },
  "triggers": { "onEnter":  { "type": "client", "event": "" },
                "onExit":   { "type": "client", "event": "" },
                "onInside": { "type": "client", "event": "", "interval": 5 },
                "onDeath":        { "type": "server", "event": "" },
                "onVehicleEnter": { "type": "client", "event": "" },
                "onVehicleExit":  { "type": "client", "event": "" },
                "onWeaponFire":   { "type": "server", "event": "" },
                "enterMessage": "", "exitMessage": "", "webhook": "",
                "requiredItem": "", "requiredJob": "", "cooldown": 0,
                "once": false, "chainZone": "" },
  "gameplay": { "dotEnabled": false, "dotType": "Radiation", "dotDps": 5,
                "healEnabled": false, "healHps": 5, "safeZone": false,
                "speedMultiplier": 1, "gravity": 1, "staminaDrain": false,
                "oxygenDrain": false, "drunkEffect": false },
  "economy":  { "tollEnabled": false, "tollAmount": 100, "rentEnabled": false,
                "rentAmount": 500, "harvestResource": "None", "harvestRate": 1,
                "robberyEnabled": false },
  "access":   { "scheduleEnabled": false, "days": ["Mon","Tue","Wed","Thu","Fri","Sat","Sun"],
                "from": "00:00", "to": "23:59", "eventOnly": false,
                "keycardEnabled": false, "keycardItem": "", "password": "", "capacity": 0 },
  "blip":     { "enabled": false, "sprite": 1, "label": "", "showArea": true,
                "minimapHighlight": false, "scale": 1 }
}
```

### Enum values

| Field               | Allowed values                                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `shape.type`        | `circle`, `box`, `polygon`                                                                                                          |
| `preview`           | `walls`, `marker`, `outline`, `none`                                                                                                |
| `weather.type`      | `EXTRASUNNY`, `CLEAR`, `CLOUDS`, `OVERCAST`, `RAIN`, `THUNDER`, `FOGGY`, `SMOG`, `XMAS`, `SNOW`, `BLIZZARD`, `HALLOWEEN`, `NEUTRAL` |
| `weather.sync`      | `self`, `everyone`                                                                                                                  |
| `pvp.weaponPolicy`  | `all`, `whitelist`, `blacklist`, `melee`                                                                                            |
| `visual.particles`  | `None`, `Fog`, `Smoke`, `Embers`, `Radiation Dust`, `Fireflies`, `Snowfall`                                                         |
| `gameplay.dotType`  | `Radiation`, `Gas`, `Fire`, `Electric`, `Cold`                                                                                      |
| `*.type` (triggers) | `client`, `server`                                                                                                                  |

{% hint style="warning" %}
The server **validates and sanitizes** every zone on save (shape, ranges, label length, color format, event-name whitelist). Hand-edited files that violate the schema are clamped or rejected. Restart the resource after editing `zones.json` directly, and note that a running server may overwrite the file from memory on the next save — edit while the resource is stopped, or import via the panel.
{% endhint %}