# ZoneCues

### 🚀 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
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rp-works-modding.gitbook.io/rp-works-modding-docs/zonecues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.