# Api #### 🛠️ The `options` Table Whenever you add a target (to an entity, model, zone, or globally), you must pass an `options` table. This defines what the player sees and what happens when they click the option. **Option Parameters** | **Parameter** | **Type** | **Description** | | ------------- | ------------------ | ----------------------------------------------------------------------------------------- | | `name` | `string` | A unique identifier for the option. | | `label` | `string` | The text displayed in the target menu. | | `icon` | `string` | The FontAwesome icon class (e.g., `'fas fa-car'`). | | `description` | `string` | (Optional) Extra description text below the label. | | `distance` | `number` | The maximum distance the player can interact from. | | `bones` | `string` / `table` | (Optional) Specific entity bones the player must look at. | | `offset` | `vector3` | (Optional) Offset from the entity's center. | | `groups` | `string` / `table` | (Optional) Restrict to specific jobs, gangs, or citizen IDs. | | `items` | `string` / `table` | (Optional) Restrict to players carrying specific item(s). | | `anyItem` | `boolean` | (Optional) If `true`, the player only needs *one* of the specified items. | | `canInteract` | `function` | (Optional) A custom check function returning `true` or `false`. | | `submenu` | `table` | (NEW) (Optional) A nested table of target options to create a multi-level drop-down menu. | **Action Handlers (Pick One)** You must define one of the following to execute an action when the player clicks the option (unless the option is just a parent for a `submenu`): * `onSelect` or `action`: A direct Lua callback function. Receives a `data` table `(entity, coords, distance, zone)`. * `event`: Triggers a Client Event. * `serverEvent`: Triggers a Server Event (automatically converts entity to `netId`). * `command`: Executes a console command. * `export`: Calls an export formatted as `'resourceName.exportName'`. *** #### 📂 Submenus (Nested Options) You can now nest target options inside one another to create clean, organized submenus. Options containing a `submenu` table will act as a folder and do not need an action handler (like `onSelect`). You can nest submenus as deeply as you want! **Example Submenu Table** ```lua local myOptions = { { name = "vehicle_options", icon = "fas fa-car", label = "Vehicle Options", distance = 2.5, -- Level 1 Submenu submenu = { { name = "inspect_vehicle", icon = "fas fa-magnifying-glass", label = "Inspect Vehicle", distance = 2.5, onSelect = function(data) print("Inspecting vehicle entity ID: " .. tostring(data.entity)) end }, { name = "door_controls", icon = "fas fa-door-open", label = "Door Controls", distance = 2.5, -- Level 2 Submenu (Nested inside Level 1) submenu = { { name = "toggle_hood", icon = "fas fa-angle-up", label = "Toggle Hood", distance = 2.5, onSelect = function(data) print("Toggling hood for vehicle: " .. tostring(data.entity)) end }, { name = "toggle_trunk", icon = "fas fa-angle-down", label = "Toggle Trunk", distance = 2.5, onSelect = function(data) print("Toggling trunk for vehicle: " .. tostring(data.entity)) end } } } } } } -- Adding the submenu to all vehicles exports.ak47_target:addGlobalVehicle(myOptions) ``` *** #### 🌍 Global Targets Global targets apply to *every* entity of a specific type across the entire map. **`addGlobalPed`** Adds options to all Peds. ```lua exports.ak47_target:addGlobalPed(options) ``` **`addGlobalVehicle`** Adds options to all Vehicles. ```lua exports.ak47_target:addGlobalVehicle(options) ``` **`addGlobalObject`** Adds options to all Objects. ```lua exports.ak47_target:addGlobalObject(options) ``` **`addGlobalPlayer`** Adds options to all other Players. ```lua exports.ak47_target:addGlobalPlayer(options) ``` **`addGlobalOption`** Adds an option anywhere in the world (catches world coordinates if no entity is hit). ```lua exports.ak47_target:addGlobalOption(options) ``` *** #### 📦 Model & Entity Targets **`addModel`** Adds options to specific entity models (props, vehicle models, ped models). ```lua -- Models can be a single string/hash or a table of strings/hashes local models = { 'prop_atm_01', 'prop_atm_02', `prop_atm_03` } exports.ak47_target:addModel(models, { { name = 'use_atm', icon = 'fas fa-credit-card', label = 'Use ATM', distance = 1.5, event = 'myBank:client:openMenu' } }) ``` **`addEntity` (Networked)** Adds options to specific networked entities using their `netId`. ```lua exports.ak47_target:addEntity(netId, options) -- Accepts single netId or table of netIds ``` **`addLocalEntity` (Non-Networked)** Adds options to specific local entities using their local entity ID. ```lua exports.ak47_target:addLocalEntity(entityId, options) -- Accepts single ID or table of IDs ``` *** #### 📍 Zone Targets Zones allow you to define 3D areas in the world that act as targets without needing a physical prop. **`addSphereZone`** Creates a spherical interaction zone. Returns a unique Zone ID. ```lua local zoneId = exports.ak47_target:addSphereZone({ coords = vector3(100.0, -100.0, 30.0), radius = 2.5, debug = false, -- Set to true to see the zone outline options = { { name = 'sphere_interact', icon = 'fas fa-hand', label = 'Interact Sphere', distance = 2.5, action = function(data) print("Sphere clicked!") end } } }) ``` **`addBoxZone`** Creates a rectangular interaction box. Returns a unique Zone ID. ```lua local zoneId = exports.ak47_target:addBoxZone({ coords = vector3(120.0, -120.0, 30.0), size = vector3(3.0, 2.0, 2.0), -- Width, Length, Height rotation = 45.0, -- Heading debug = false, options = { ... } }) ``` **`addPolyZone`** Creates a custom polygon interaction zone. Returns a unique Zone ID. ```lua local zoneId = exports.ak47_target:addPolyZone({ points = { vector3(10.0, 10.0, 0.0), vector3(15.0, 10.0, 0.0), vector3(15.0, 15.0, 0.0), vector3(10.0, 15.0, 0.0) }, thickness = 2.0, minZ = 28.0, maxZ = 32.0, debug = true, options = { ... } }) ``` *** #### 🗑️ Removing Targets Use these exports to clean up targets, especially inside `onResourceStop` handlers. * `removeGlobalPed(labels)` * `removeGlobalVehicle(labels)` * `removeGlobalObject(labels)` * `removeGlobalPlayer(labels)` * `removeGlobalOption(labels)` *Note: `labels` can be a single string (the option name or label) or a table of strings.* Removing Models & Entities: ```lua exports.ak47_target:removeModel({'prop_atm_01'}, {'Use ATM'}) exports.ak47_target:removeEntity(netId, {'Rob Ped'}) exports.ak47_target:removeLocalEntity(entityId, {'Rob Ped'}) ``` Removing Zones (Pass the Zone ID returned when you created it): ```lua exports.ak47_target:removeZone(zoneId) ``` *** #### ⚙️ Utility Exports **`disableTargeting`** Temporarily disable or re-enable the targeting eye. ```lua exports.ak47_target:disableTargeting(true) -- Disables targeting and closes UI exports.ak47_target:disableTargeting(false) -- Re-enables targeting ``` **`isDisabled`** Check if targeting is currently disabled. ```lua local disabled = exports.ak47_target:isDisabled() ``` **`zoneExists`** Check if a specific zone ID is currently active. ```lua local exists = exports.ak47_target:zoneExists(zoneId) ```