> For the complete documentation index, see [llms.txt](https://rp-works-modding.gitbook.io/rp-works-modding-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rp-works-modding.gitbook.io/rp-works-modding-docs/zonecues.md).

# ZoneCues

ZoneCues is a FiveM script designed for immersive roleplay. It allows players to place ambient notifications in the game world that trigger when another player enters a defined radius around a player.

### 🚀 Features

* 📍 Create roleplay-based cues (e.g. "You smell cannabis")
* 🔘 Attach cues to:
  * Yourself
  * Vehicles
  * Objects
  * Static world positions
* 🎯 ox\_target integration for intuitive third-eye target selection
* 👀 Preview radius with live marker during cue placement
* 📋 Manage active cues via a modern, stylish NUI menu
* 🕒 Automatic timeout if no selection is made
* 🛑 Cues attached to players are removed if they leave the server

***

### 🧱 Installation

Follow instructions in [Getting Started](/rp-works-modding-docs/readme.md)

{% hint style="warning" %}
Ensure that the dependancies are started BEFORE this resource in server.cfg
{% endhint %}

***

### 📦 Dependancies

* [ox\_target](https://github.com/overextended/ox_target)

### 🕹️ Usage

#### Open the Menu

Use the command:

```
/zonecues
```

#### Creating a Cue

1. Enter your message (e.g. "You smell cannabis").
2. Set the radius (1-50 meters).
3. Choose an attachment type:
   * **Self** — attaches to you
   * **Vehicle/Object** — requires selection with third eye
   * **Static** — places it where you stand
4. If Vehicle/Object is chosen, click **Select Target** and use the third eye to select your target.
5. A radius marker will preview the area before finalizing.
6. Click **Create** to place the cue.

#### Managing Cues

* Your active zones appear in the bottom panel
* Edit or remove cues at any time

***

### 💡Tips & Notes

* Only the creator sees their own cues in the management panel
* Notifications display using a clean, modern UI overlay
* The menu auto-closes when selecting a target, and auto-reopens once selected
* If no target is selected within 30 seconds, the process is cancelled with a notification
* Cues follow vehicles and objects if they move (via network ID tracking)

***

### 📤 Exports

ZoneCues provides several server-side exports for interacting with zones programmatically from other resources:

#### `addZone(data: table) → number`

Adds a new zone and returns its unique ID.

**Example:**

```lua
local zoneId = exports.zonecues:addZone({
    message = "Heavy smell of fuel",
    radius = 10.0,
    attach = "static",
    coords = vector3(123.4, 456.7, 78.9)
})
```

**Data Parameters:**

| Field     | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `message` | string  | The message shown when entering the zone      |
| `radius`  | number  | Radius (in meters) of the zone                |
| `attach`  | string  | `"static"`, `"vehicle"`, `"object"`, `"self"` |
| `coords`  | vector3 | Required if using `"static"`                  |
| `netId`   | number  | Required if using `"vehicle"` or `"object"`   |

***

#### `removeZone(id: number) → boolean`

Removes a zone by its ID.

**Example:**

```lua
exports.zonecues:removeZone(zoneId)
```

***

#### `getAllZones() → table`

Returns a table of all currently active zones.

**Example:**

```lua
local zones = exports.zonecues:getAllZones()
for id, zone in pairs(zones) do
    print(zone.message, zone.radius)
end
```

***

### ⚙️ Configuration

Located in `config.lua`:

```lua
Config = {}

-- How often (in milliseconds) to check if a player is inside any zone
Config.CheckInterval = 1000

-- Distance used for ray-based entity selection (deprecated in favor of ox_target)
Config.EntitySelectDistance = 8.0

-- Key used to confirm entity selection (when using raycast mode)
Config.ConfirmKey = 38 -- E (no longer used with ox_target)

-- Time in milliseconds before selection via ox_target times out
Config.SelectionTimeout = 30000
```

***