> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shdevelopment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# sh-zones: Green Zone & Red Zone Script for FiveM

> sh-zones creates safe Green Zones and danger Red Zones using PolyZone. Control speed limits, weapon use, and player invincibility per zone.

sh-zones lets you define circular safe areas and danger areas anywhere on the GTA V map, giving you precise control over how players behave inside each region. Green Zones enforce a vehicle speed cap, disable weapons and combat, grant player invincibility, and remove player-to-player collisions — making them ideal for spawn areas, hospitals, and city centers. Red Zones do the opposite, marking known danger areas on the minimap so players are warned before entering. Each zone renders a translucent circle overlay on the minimap, and players hear an audio cue with an on-screen text prompt whenever they cross a zone boundary.

## Dependencies

<Warning>
  sh-zones requires the **PolyZone** resource to function. Ensure PolyZone is listed in your `server.cfg` **before** sh-zones, or zone detection will not work.

  ```cfg server.cfg theme={null}
  ensure PolyZone
  ensure sh-zones
  ```
</Warning>

## Installation

<Steps>
  <Step title="Install PolyZone">
    Download [PolyZone](https://github.com/mkafrin/PolyZone) and place it in your `resources` directory. Start it before sh-zones in `server.cfg`.
  </Step>

  <Step title="Add sh-zones to your server">
    Place the `sh-zones` folder inside your `resources` directory.

    ```
    resources/
    ├── PolyZone/
    └── sh-zones/
        ├── fxmanifest.lua
        ├── config.lua
        └── client/
    ```
  </Step>

  <Step title="Configure your zones">
    Open `config.lua` and define your Green Zones and Red Zones. See the [Configuration](#configuration) section below for the full options reference.
  </Step>

  <Step title="Start sh-zones in server.cfg">
    ```cfg server.cfg theme={null}
    ensure PolyZone
    ensure sh-zones
    ```
  </Step>
</Steps>

## Configuration

All zone settings live in a single `config.lua` file. The file is divided into global speed settings, a global Red Zone toggle, and the zone coordinate list.

```lua config.lua theme={null}
Config.inGreenZone  = 25.0   -- Max vehicle speed (m/s) inside Green Zones
Config.outGreenZone = 120.0  -- Max vehicle speed outside Green Zones
Config.EnableRedZone = true  -- Toggle Red Zones on/off globally

Config.CircleZones = {
    GreenZones = {
        { coords = vector3(x, y, z), name = 'Zone Name', radius = 50.0 },
    },
    RedZones = {
        { coords = vector3(x, y, z), name = 'Danger Zone', radius = 120.0 },
    },
}
```

### Global Options

<ParamField path="Config.inGreenZone" type="number" default="25.0">
  Maximum vehicle speed in metres per second enforced inside every Green Zone. This is applied via `SetEntityMaxSpeed` and affects all vehicles, including those driven by NPC peds owned by the player.
</ParamField>

<ParamField path="Config.outGreenZone" type="number" default="120.0">
  Maximum vehicle speed in metres per second applied to the player's vehicle when they leave a Green Zone. Set this to a high value to effectively remove the speed cap outside zones.
</ParamField>

<ParamField path="Config.EnableRedZone" type="boolean" default="true">
  Globally enables or disables all Red Zones. Set to `false` to remove all Red Zone blips and effects without deleting the zone definitions from the config.
</ParamField>

### Zone Entry Format

Each entry in `GreenZones` or `RedZones` takes the following fields:

<ParamField path="coords" type="vector3" required>
  The world-space centre point of the circular zone. Use F8 in-game or a coords resource to find the exact position.
</ParamField>

<ParamField path="name" type="string" required>
  A display name shown to players in the on-screen HUD text when they enter the zone. Also used as the blip label on the minimap.
</ParamField>

<ParamField path="radius" type="number" required>
  The radius of the circular zone in metres. The PolyZone CircleZone and the minimap blip overlay both use this value.
</ParamField>

## Default Zones

sh-zones ships with the following pre-configured zones so your server has safe areas from day one.

<Tabs>
  <Tab title="Green Zones (Default)">
    | Zone Name      | Coordinates                | Radius  |
    | -------------- | -------------------------- | ------- |
    | Observatory    | `-418.96, 1147.28, 325.98` | 120.0 m |
    | Casino         | `1039.9, 53.78, 69.06`     | 140.0 m |
    | Sandy Shores   | `1725.72, 3462.73, 38.06`  | 20.0 m  |
    | Sandy Hospital | `1762.38, 3645.93, 34.85`  | 40.0 m  |
    | Hayes Auto     | `-1418.61, -443.86, 35.91` | 40.0 m  |
    | Hospital       | `314.11, -590.09, 43.28`   | 55.0 m  |
  </Tab>

  <Tab title="Red Zones (Default)">
    | Zone Name  | Coordinates               | Radius  |
    | ---------- | ------------------------- | ------- |
    | Humane Lab | `3540.92, 3717.74, 36.45` | 120.0 m |
  </Tab>
</Tabs>

## Adding a New Zone

To add a zone, open `config.lua`, copy an existing entry from the appropriate list, and update the `coords`, `name`, and `radius` fields.

```lua config.lua theme={null}
Config.CircleZones = {
    GreenZones = {
        -- Existing zone
        { coords = vector3(-1418.61, -443.86, 35.91), name = 'HayesAuto', radius = 40.0 },

        -- New zone added below
        { coords = vector3(372.54, 325.73, 103.57), name = 'Police Station', radius = 60.0 },
    },
    RedZones = {
        { coords = vector3(3540.92, 3717.74, 36.45), name = 'HumaneLab', radius = 120.0 },
    },
}
```

<Tip>
  Restart the `sh-zones` resource after saving `config.lua` — changes do not apply to a live server without a restart or a `refresh` + `restart sh-zones` in the server console.
</Tip>

## Green Zone Enforcement Details

<Accordion title="Vehicle speed cap">
  The speed cap is enforced client-side using `SetEntityMaxSpeed`. The value in `Config.inGreenZone` (default `25.0 m/s`, roughly 56 mph) applies to the vehicle the player is currently driving. When the player exits the Green Zone the cap is immediately raised to `Config.outGreenZone`.
</Accordion>

<Accordion title="Combat and weapon lockdown">
  Inside a Green Zone, the following player actions are disabled:

  * Opening the weapon wheel
  * Firing any weapon
  * Reloading
  * Melee attacks

  Players can still carry weapons — they simply cannot use them while inside a Green Zone boundary.
</Accordion>

<Accordion title="Player invincibility and collisions">
  While inside a Green Zone, each player is set to invincible (`SetEntityInvincible`) and player-to-player collisions are disabled. Both states are reverted the moment the player exits the zone.
</Accordion>