> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/gangs/cuxial-gang/developers.md).

# Exports & events

Public API of Cuxial Gang: exports, events and state bags to read organizations and reward them.

Read organizations, members and territory from your own resources, reward an organization from a job or a heist, and plug your own NPCs into the interaction and hostage menus.

Throughout this page, `orgId` is the numeric id of an organization and `citizenid` is the character identifier given by the bridge.

## Server exports

### getOrganisation

Returns the full record of an organization.

```lua
local org = exports.cuxial_gang:getOrganisation(orgId)
```

**Returns:** `table | false`. Among its fields: `id`, `label`, `color`, `orgType`, `lvl`, `exp`, `balance`, `dirtymoney`, `ranks`, `upgrades`.

```lua
local org = exports.cuxial_gang:getOrganisation(3)
if org then print(org.label, org.lvl) end
```

### getOrganisationsList

Lists every organization.

```lua
local list = exports.cuxial_gang:getOrganisationsList()
```

**Returns:** `table[]`. Each entry is `{ identifier = orgId, label = string }`.

### getPlayerOrganisation

Returns the organization of a character with its member entry.

```lua
local data = exports.cuxial_gang:getPlayerOrganisation(citizenid)
```

**Returns:** `table | false`.

| Field      | Type   | Description                                  |
| ---------- | ------ | -------------------------------------------- |
| `orgIndex` | number | Id of the organization.                      |
| `player`   | table  | `identifier`, `rank`, `status`, `totalTime`. |
| `orgData`  | table  | Same record as `getOrganisation`.            |

```lua
local data = exports.cuxial_gang:getPlayerOrganisation(citizenid)
if data then print(data.orgData.label, data.player.rank) end
```

### getMemberGang

Short form of the above.

```lua
local gang = exports.cuxial_gang:getMemberGang(citizenid)
```

**Returns:** `table | nil`. `{ gangId = string, label = string, rank = string, name = string }`.

### checkPermissions

Tells whether the rank of a character has a permission.

```lua
local allowed = exports.cuxial_gang:checkPermissions(citizenid, permission)
```

| Parameter    | Type   | Description                                                                                                        |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `citizenid`  | string | Character identifier.                                                                                              |
| `permission` | string | `bossmenu_access`, `garage_access`, `storage_access`, `blackmedic_access`, `moneylaundry_access` or `port_access`. |

**Returns:** `boolean`.

### getOnlineSource

Returns the server id of a member who is online.

```lua
local src = exports.cuxial_gang:getOnlineSource(citizenid)
```

**Returns:** `number | nil`.

### getOrgsIntelList

Lists organizations with their colour, level and member count, sorted by name.

```lua
local list = exports.cuxial_gang:getOrgsIntelList()
```

**Returns:** `table[]`. Each entry is `{ gangId = string, label = string, color = string, lvl = number, members = number }`.

### getOrgIntelData

Returns a detailed card of an organization.

```lua
local card = exports.cuxial_gang:getOrgIntelData(orgId)
```

**Returns:** `table | nil`.

| Field                                                   | Type     | Description                                                                                                           |
| ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `gangId`, `label`, `color`, `lvl`, `exp`, `graffitiUrl` |          | Basic data.                                                                                                           |
| `members`                                               | table\[] | `citizenid`, `name`, `rank`, `rankIndex`, `isBoss`, `online`, `since`.                                                |
| `ranks`                                                 | table\[] | `{ index, name }`, sorted.                                                                                            |
| `locations`                                             | table    | `hideout`, `stash`, `cloakroom`, `mulaStash`, `garage`, `helipad`. Each is `{ x, y, z, w }` or `nil` when not placed. |
| `territories`                                           | table\[] | `{ index, label, owner, points }` for the turf zones where it has loyalty or ownership.                               |

### getTurfZonesIntel

Lists the turf zones with their polygon and current owner.

```lua
local zones = exports.cuxial_gang:getTurfZonesIntel()
```

**Returns:** `table[]`. Each entry is `{ index, label, polygon = { { x, y }, ... }, ownerId, ownerLabel }`. `ownerId` is `nil` when nobody owns the zone.

### Turf

| Export                           | Returns        | Description                                            |
| -------------------------------- | -------------- | ------------------------------------------------------ |
| `getTurfOwnership(turfId)`       | `table \| nil` | `{ ownerId, ownerLabel, expiresAt }` of a turf zone.   |
| `isTurfOwner(turfId, orgId)`     | `boolean`      | Whether that organization owns the zone.               |
| `isPlayerTurfOwner(src, turfId)` | `boolean`      | Whether the organization of that player owns the zone. |
| `getPlayerTurfZone(src)`         | `any \| nil`   | Index of the turf zone the player is in.               |
| `isTurfZoneInRivalry(turfId)`    | `boolean`      | Whether a war is running in the zone.                  |

```lua
local turfId = exports.cuxial_gang:getPlayerTurfZone(source)
if turfId and exports.cuxial_gang:isPlayerTurfOwner(source, turfId) then
    -- the player is on home ground
end
```

### Favelas

| Export                      | Returns        | Description                                                                                                          |
| --------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `getFavelas(orgId?)`        | `table[]`      | Card of every favela, sorted by name. With `orgId`, each card says whether it is yours in `isMine`.                  |
| `getFavelaCard(id, orgId?)` | `table \| nil` | Card of one favela: `id`, `label`, `state`, `ownerId`, `ownerLabel`, `ownerColor`, `expiresAt`, `progress` and more. |
| `getFavelaOwner(id)`        | `any \| nil`   | Id of the organization that owns it.                                                                                 |

### Mules

| Export                                                       | Returns        | Description                                                                                                    |
| ------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------- |
| `isPlayerMula(citizenid)`                                    | `boolean`      | Whether the character is an active mule.                                                                       |
| `getMulaData(citizenid)`                                     | `table \| nil` | `identificator`, `name`, `orgId`, `trustLevel`, `status`, `completedContracts`, `failedContracts`, `joinDate`. |
| `getMulaOrg(citizenid)`                                      | `any \| nil`   | Organization the mule works for.                                                                               |
| `getOrgMulas(orgId)`                                         | `table[]`      | Mules of an organization.                                                                                      |
| `getMulaActiveContract(citizenid)`                           | `table \| nil` | The contract the mule is running.                                                                              |
| `completeMulaContractStep(citizenid, contractId, stepIndex)` |                | Marks a step of a contract as done from your own resource.                                                     |
| `failMulaContract(citizenid, contractId)`                    | `boolean`      | Fails a contract assigned to that mule.                                                                        |

### Arsenal

| Export                   | Returns          | Description                                                                         |
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------- |
| `getArsenalLevel(orgId)` | `number, number` | Arsenal level and units sold by the organization. `0, 0` with the arsenal disabled. |
| `getArsenalParts()`      | `table[]`        | Parts catalogue: `{ item, label, price }`.                                          |

### Effects on an organization

Meant for a police or staff resource. They change the state of the organization.

| Export                                      | Returns                     | Description                                                                                      |
| ------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| `applyPoliceStrike(orgId, { loyalty = n })` | `{ turfs, loyalty } \| nil` | Removes `n` loyalty from the organization in every turf zone where it has any.                   |
| `seizeOrgMoney(orgId, account)`             | `number`                    | Empties an account and returns the amount. `account` is `'balance'` or `'dirtymoney'` (default). |
| `seizeOrgStash(orgId)`                      | `table[]`                   | Empties the main stash and returns `{ name, label, count }` per item.                            |

{% hint style="danger" %}
These three have no undo. Call them only from server code you trust.
{% endhint %}

### RegisterExtortionVictim

Adds a civilian who can be extorted by phone, besides the ones in `data/extortion.lua`.

```lua
local ok = exports.cuxial_gang:RegisterExtortionVictim(victim)
```

| Field                                            | Type   | Description                                                   |
| ------------------------------------------------ | ------ | ------------------------------------------------------------- |
| `id`                                             | string | Unique id. Required.                                          |
| `name`                                           | string | Display name. Required.                                       |
| `personality`                                    | string | `greedy`, `trusting`, `suspicious` or `aggressive`. Required. |
| `occupation`, `wealthHint`, `pedModel`, `avatar` |        | Optional.                                                     |

**Returns:** `boolean`. `false` when the shape is invalid.

```lua
exports.cuxial_gang:RegisterExtortionVictim({
    id = 'victim_baker',
    name = 'Tom Reyes',
    occupation = 'Baker',
    personality = 'trusting',
})
```

### RegisterExtortionFixer

Adds an intermediary, besides the ones in `data/extortionFixers.lua`.

```lua
local ok = exports.cuxial_gang:RegisterExtortionFixer(fixer)
```

`fixer` needs `id`, `name` and `personality` (`sharp`, `gruff` or `silky`). Prices and limits that are missing take the defaults of the file.

**Returns:** `boolean`.

## Server events

These five are server-only. Trigger them with `TriggerEvent` from server code. A call that comes from a client is logged and ignored.

| Event                                 | Parameters               | What it does                                                    |
| ------------------------------------- | ------------------------ | --------------------------------------------------------------- |
| `cuxial_gang:addOrganisationEXP`      | `orgId, amount`          | Adds experience. The organization levels up when it has enough. |
| `cuxial_gang:addOrganisationMoney`    | `orgId, amount, account` | Adds money. `account` is `'balance'` or `'dirtymoney'`.         |
| `cuxial_gang:removeOrganisationMoney` | `orgId, amount, account` | Removes money. Does nothing when there is not enough.           |
| `cuxial_gang:addOrgMissionsDone`      | `orgId, amount`          | Adds to the missions done counter.                              |
| `cuxial_gang:addZonesCaptured`        | `orgId, amount`          | Adds to the captured zones counter.                             |

```lua
-- Reward the organization of a player after a heist
local data = exports.cuxial_gang:getPlayerOrganisation(citizenid)
if data then
    TriggerEvent('cuxial_gang:addOrganisationMoney', data.orgIndex, 15000, 'dirtymoney')
    TriggerEvent('cuxial_gang:addOrganisationEXP', data.orgIndex, 200)
end
```

### Events you can listen to

Local server events, raised with `TriggerEvent`.

| Event                                 | Parameters                                                        | When                                                                                   |
| ------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `cuxial_gang:server:ZoneOwnerChanged` | `{ zoneIndex, oldOwnerId, newOwnerId }`                           | A turf zone changes owner.                                                             |
| `cuxial_gang:server:SaleRecorded`     | `{ orgId, turfIndex, units, amount, citizenid, source, counted }` | A drug sale is recorded. `counted` is the units that scored.                           |
| `cuxial_gang:server:PlayerLeftGang`   | `src, citizenid`                                                  | A player leaves or is removed from an organization.                                    |
| `cuxial_gang:intel`                   | `kind, payload`                                                   | An organization does something relevant. Raised only while `cuxial_police` is running. |

`kind` is one of `drug_sale`, `laundry`, `graffiti`, `mula`, `turf`, `favela`, `airdrop`, `weapon_crafted`, `supply_robbed`, `supply_seized`, `vehicle_seized` or `officer_kidnap`. `payload` always carries `gangId` and `gangLabel` when they are known, usually `coords`, and fields that depend on the kind.

```lua
AddEventHandler('cuxial_gang:server:ZoneOwnerChanged', function(data)
    print(('zone %s: %s -> %s'):format(data.zoneIndex, data.oldOwnerId, data.newOwnerId))
end)
```

## Client exports

### getPlayerOrganisation

Returns the organization of the local player.

```lua
local org = exports.cuxial_gang:getPlayerOrganisation()
```

**Returns:** `table | false`. `{ id = number, label = string, bossmenuCoords = vector4 }`. `false` when the player has no organization or the data has not loaded yet.

### hasOrgPermission

Tells whether the rank of the local player has a permission. It reads a replicated copy, so use it to draw interface; check again on the server before acting.

```lua
local allowed = exports.cuxial_gang:hasOrgPermission('storage_access')
```

**Returns:** `boolean`.

### getOrgPermissions

```lua
local perms = exports.cuxial_gang:getOrgPermissions()
```

**Returns:** `table | nil`. A map of permission name to `true`.

### Other queries

| Export           | Returns        | Description                                          |
| ---------------- | -------------- | ---------------------------------------------------- |
| `isInTurfZone()` | `any \| nil`   | Index of the turf zone the player is in.             |
| `isPlayerMula()` | `boolean`      | Whether the local player is a mule. Asks the server. |
| `getMulaData()`  | `table \| nil` | Mule record of the local player. Asks the server.    |

### Opening the interfaces

| Export                | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `OpenTablet()`        | Opens the tablet. `openCrimeTablet()` does the same. |
| `openHandcuffsMenu()` | Opens the interaction menu on the nearest player.    |
| `useSpray()`          | Starts painting a graffiti.                          |
| `useRemover()`        | Starts removing a graffiti.                          |

These are the exports to point an inventory item at.

### OpenInteractionMenu

Opens the same wheel menu with your own entries.

```lua
exports.cuxial_gang:OpenInteractionMenu(payload, handlers)
```

| Parameter            | Type     | Description                                                                                                  |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `payload.title`      | string   | Title of the menu.                                                                                           |
| `payload.targetName` | string   | Name shown as the target.                                                                                    |
| `payload.targetMeta` | string   | Small text under the name. Optional.                                                                         |
| `payload.icon`       | string   | Font Awesome class, such as `fa-solid fa-user`. Optional.                                                    |
| `payload.items`      | table\[] | Entries: `value`, `title`, `description`, `icon`, and `tone` (`warn`, `success` or `destructive`). Required. |
| `handlers`           | table    | Map of `value` to the function to run when that entry is chosen.                                             |

```lua
exports.cuxial_gang:OpenInteractionMenu({
    title = 'Informant',
    targetName = 'Stranger',
    items = {
        { value = 'ask', title = 'Ask', description = 'Ask about the area.', icon = 'fa-solid fa-comment' },
    },
}, {
    ask = function()
        print('asked')
    end,
})
```

`exports.cuxial_gang:CloseInteractionMenu()` closes it.

### RegisterHostage

Makes one of your NPCs controllable as a hostage: aiming at it opens the hostage menu.

```lua
exports.cuxial_gang:RegisterHostage(ped, meta)
```

| Parameter               | Type     | Description                                        |
| ----------------------- | -------- | -------------------------------------------------- |
| `ped`                   | number   | Entity handle of an existing ped.                  |
| `meta.name`             | string   | Name shown in the menu. Optional.                  |
| `meta.contextKindLabel` | string   | Label of the kind of hostage. Optional.            |
| `meta.icon`             | string   | Font Awesome class. Optional.                      |
| `meta.accentColor`      | string   | Hex colour. Optional.                              |
| `meta.onKilled`         | function | Called with `ped` when the hostage dies. Optional. |

```lua
exports.cuxial_gang:RegisterHostage(ped, {
    name = 'Bank clerk',
    onKilled = function(entity)
        print('hostage down', entity)
    end,
})
```

`UnregisterHostage(ped)` releases it and `IsHostageControlled(ped)` returns whether it is registered.

## State bags

Set by the server on each player and replicated to clients.

| State bag        | Type            | Description                                                  |
| ---------------- | --------------- | ------------------------------------------------------------ |
| `gangName`       | string \| false | Name of the organization of the player. `false` without one. |
| `gangId`         | number \| nil   | Id of the organization.                                      |
| `gangRankName`   | string \| nil   | Label of the rank.                                           |
| `orgPermissions` | table \| nil    | Map of permission name to `true`.                            |

```lua
local orgId = Player(source).state.gangId
```

{% hint style="info" %}
In the framework, each organization is registered as a gang named `gang_<orgId>`, for example `gang_3`.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/gangs/cuxial-gang/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.