> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/cas-safezone/cas-safezone.md).

# CAS Safezone

An advanced safezone management system for **RedM** servers on the **VORP** framework. Permanent and temporary zones, three protection modes, anti-abuse and combat tagging, a modern NUI admin panel with live map preview, and richly formatted Discord logging.

## Highlights

* **Three zone types** — `hard`, `soft`, `rp`, each fully configurable.
* **Permanent & temporary zones** — fixed zones in config, or timed zones spawned in-game.
* **Anti-abuse system** — shooting-from-inside/outside detection, explosive-abuse thresholds, combat tagging.
* **NUI admin panel** — list, create, edit and delete zones, with live map preview via RDR2CollectorsMap.
* **Discord logging** — formatted embeds with identifiers, position, zone and abuse counters.
* **Developer API** — exports to add/remove/list temporary zones at runtime.

## At a glance

|               |                                                  |
| ------------- | ------------------------------------------------ |
| Framework     | VORP Core (required)                             |
| Optional      | RDR2CollectorsMap (live map preview)             |
| Recommended   | `vorp_core`, `vorp_character`, RDR2CollectorsMap |
| Resource name | `cas-safezone`                                   |

## Requirements

* Latest **RedM** build
* **VORP Core** (required)
* Optional webmap for the admin live preview: [RDR2CollectorsMap](https://github.com/codeaftersex/RDR2CollectorsMap/tree/main)

## Installation

1. Place the resource in your resources directory as `cas-safezone`.
2. In `server.cfg`, ensure it **after** VORP:

```
ensure vorp_core
ensure cas-safezone
```

3. Edit `cas-safezone/config.lua` for your server (see below).
4. **(Optional) WebMap** — install [RDR2CollectorsMap](https://github.com/codeaftersex/RDR2CollectorsMap/tree/main), then set:

```lua
Config.MapResourceName = "RDR2CollectorsMap"
Config.MapHtmlFile = "index.html"
```

## Configuration

### Locale

```lua
Config.Locale = "en"   -- en, de, fr (extend via locale files)
```

### Zone types

| Type   | Description                                           |
| ------ | ----------------------------------------------------- |
| `hard` | Full protection — no damage, weapons, melee or lasso. |
| `soft` | Weapons allowed but damage prevented.                 |
| `rp`   | Flexible protection for RP areas.                     |

```lua
Config.TypeSettings.hard.preventWeapons = true
Config.TypeSettings.soft.preventExplosives = true
```

### Permanent safezones

```lua
Config.Safezones = {
    { name = "Valentine", type = "hard", coords = vector3(-277.0, 806.0, 119.0), radius = 150.0 },
}
```

| Field  | Type    | Description      |
| ------ | ------- | ---------------- |
| name   | string  | Display name     |
| type   | string  | hard, soft or rp |
| coords | vector3 | Center position  |
| radius | float   | Zone size        |

### Temporary safezones

Admins create runtime zones via command or the UI, with a duration in seconds:

```
/addsafezone hard 120 EventArea
```

Temporary zones live in memory and sync to all players.

### Anti-abuse

```lua
Config.AntiAbuse = {
    logShootingFromInside = true,
    logShootingFromOutside = false,
    logExplosiveAbuse = true,
    explosiveAbuseThreshold = 5,
    combatTagEnabled = true,
    combatTagDuration = 30
}

Config.ExplosiveWeapons = { "WEAPON_DYNAMITE", "WEAPON_DYNAMITE_VOLATILE", "WEAPON_THROWN_DYNAMITE" }
```

### Exempt jobs

```lua
Config.ExemptJobs = { "marshal", "sheriff", "police" }
```

### UI

```lua
Config.UI = {
    showBanner = true,
    showEnterLeave = true,
    blurEffect = true,
    blurIntensity = 1.0,
    blurTimecycle = "MP_Camp@ambient"
}
```

### Admin & ACE

```lua
Config.Admin = {
    UseAce = true,
    AceGroup = "group.admin",
    AceObject = "safezone.admin",
    Commands = {
        panel = "managesafezone",
        add = "addsafezone",
        remove = "removesafezone",
        list = "listsafezones",
        tp = "tpsafezone"
    }
}
```

```
add_ace group.admin safezone.admin allow
```

### Discord logging

```lua
Config.DiscordConfig = {
    webhook = "",
    username = "CAS Safezone Logs",
    avatar_url = "",
    color = 16711680
}
```

Embeds include player name, identifiers (steam/license/discord/ip), position, zone name, abuse counters and raw JSON. With no webhook set, logs fall back to the server console.

## Commands

| Command                                 | Description                         |
| --------------------------------------- | ----------------------------------- |
| `/managesafezone`                       | Opens the NUI admin panel           |
| `/addsafezone [type] [duration] [name]` | Creates a temporary safezone        |
| `/removesafezone [id]`                  | Removes a temporary safezone        |
| `/listsafezones`                        | Lists permanent and temporary zones |
| `/tpsafezone [name]`                    | Teleports to a zone center          |
| `/cas_safezone_testlogs`                | Sends mock log data to Discord      |

## Admin panel (NUI)

List all zones (permanent + temporary), create/edit/delete, live map preview (with RDR2CollectorsMap), radius and position display, and type/expiration info. Map integration needs `Config.MapResourceName` and `Config.MapHtmlFile` set.

## Developer API

```lua
exports['cas-safezone']:AddTempSafezone({ name = "Event", coords = vector3(0,0,0), radius = 50, duration = 120 })
exports['cas-safezone']:RemoveTempSafezone("temp_1")
exports['cas-safezone']:GetTempSafezones()
```

### Logged events

| Event                                 | Trigger                                  |
| ------------------------------------- | ---------------------------------------- |
| `cas-safezone:logCombatTag`           | Player enters a zone while combat tagged |
| `cas-safezone:logShootingFromInside`  | Player shoots inside a zone              |
| `cas-safezone:logShootingFromOutside` | Player shoots into a zone                |
| `cas-safezone:logExplosiveAbuse`      | Explosive usage inside a zone            |

## Troubleshooting

* **Banners not showing** — ensure NUI is not blocked by another resource.
* **Safezone not activating** — check radius, type settings, combat-tag and the exempt-jobs list.
* **Discord logs not working** — valid HTTPS webhook, no outbound firewall block.
* **Map missing in panel** — RDR2CollectorsMap installed, `Config.MapResourceName` matches the folder, `Config.MapHtmlFile` matches the map HTML.

## Support

Join the [CAS Discord](https://discord.gg/X8bTK9Stwk) or use the support channel on your product page.