> 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/es/bandas/cuxial-gang/developers.md).

# Exports y eventos

API pública de Cuxial Gang: exports, eventos y state bags para consultar organizaciones y premiarlas.

Consulta organizaciones, miembros y territorio desde tus propios recursos, premia a una organización desde un trabajo o un atraco, y conecta tus propios NPC a los menús de interacción y de rehenes.

En toda la página, `orgId` es el id numérico de una organización y `citizenid` es el identificador del personaje que da el bridge.

## Exports de servidor

### getOrganisation

Devuelve la ficha completa de una organización.

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

**Devuelve:** `table | false`. Entre sus campos: `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

Lista todas las organizaciones.

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

**Devuelve:** `table[]`. Cada entrada es `{ identifier = orgId, label = string }`.

### getPlayerOrganisation

Devuelve la organización de un personaje con su entrada de miembro.

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

**Devuelve:** `table | false`.

| Campo      | Tipo   | Descripción                                  |
| ---------- | ------ | -------------------------------------------- |
| `orgIndex` | number | Id de la organización.                       |
| `player`   | table  | `identifier`, `rank`, `status`, `totalTime`. |
| `orgData`  | table  | La misma ficha que `getOrganisation`.        |

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

### getMemberGang

Forma corta de lo anterior.

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

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

### checkPermissions

Indica si el rango de un personaje tiene un permiso.

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

| Parámetro    | Tipo   | Descripción                                                                                                       |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `citizenid`  | string | Identificador del personaje.                                                                                      |
| `permission` | string | `bossmenu_access`, `garage_access`, `storage_access`, `blackmedic_access`, `moneylaundry_access` o `port_access`. |

**Devuelve:** `boolean`.

### getOnlineSource

Devuelve el id de servidor de un miembro que está conectado.

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

**Devuelve:** `number | nil`.

### getOrgsIntelList

Lista las organizaciones con su color, nivel y número de miembros, ordenadas por nombre.

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

**Devuelve:** `table[]`. Cada entrada es `{ gangId = string, label = string, color = string, lvl = number, members = number }`.

### getOrgIntelData

Devuelve una ficha detallada de una organización.

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

**Devuelve:** `table | nil`.

| Campo                                                   | Tipo     | Descripción                                                                                                                  |
| ------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `gangId`, `label`, `color`, `lvl`, `exp`, `graffitiUrl` |          | Datos básicos.                                                                                                               |
| `members`                                               | table\[] | `citizenid`, `name`, `rank`, `rankIndex`, `isBoss`, `online`, `since`.                                                       |
| `ranks`                                                 | table\[] | `{ index, name }`, ordenados.                                                                                                |
| `locations`                                             | table    | `hideout`, `stash`, `cloakroom`, `mulaStash`, `garage`, `helipad`. Cada uno es `{ x, y, z, w }` o `nil` si no está colocado. |
| `territories`                                           | table\[] | `{ index, label, owner, points }` de los territorios donde tiene lealtad o propiedad.                                        |

### getTurfZonesIntel

Lista los territorios con su polígono y su dueño actual.

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

**Devuelve:** `table[]`. Cada entrada es `{ index, label, polygon = { { x, y }, ... }, ownerId, ownerLabel }`. `ownerId` es `nil` cuando la zona no es de nadie.

### Territorio

| Export                           | Devuelve       | Descripción                                               |
| -------------------------------- | -------------- | --------------------------------------------------------- |
| `getTurfOwnership(turfId)`       | `table \| nil` | `{ ownerId, ownerLabel, expiresAt }` de un territorio.    |
| `isTurfOwner(turfId, orgId)`     | `boolean`      | Si esa organización es la dueña de la zona.               |
| `isPlayerTurfOwner(src, turfId)` | `boolean`      | Si la organización de ese jugador es la dueña de la zona. |
| `getPlayerTurfZone(src)`         | `any \| nil`   | Índice del territorio en el que está el jugador.          |
| `isTurfZoneInRivalry(turfId)`    | `boolean`      | Si hay una guerra en curso en la zona.                    |

```lua
local turfId = exports.cuxial_gang:getPlayerTurfZone(source)
if turfId and exports.cuxial_gang:isPlayerTurfOwner(source, turfId) then
    -- el jugador está en su propio territorio
end
```

### Favelas

| Export                      | Devuelve       | Descripción                                                                                                        |
| --------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `getFavelas(orgId?)`        | `table[]`      | Ficha de todas las favelas, ordenadas por nombre. Con `orgId`, cada ficha dice si es tuya en `isMine`.             |
| `getFavelaCard(id, orgId?)` | `table \| nil` | Ficha de una favela: `id`, `label`, `state`, `ownerId`, `ownerLabel`, `ownerColor`, `expiresAt`, `progress` y más. |
| `getFavelaOwner(id)`        | `any \| nil`   | Id de la organización dueña.                                                                                       |

### Mulas

| Export                                                       | Devuelve       | Descripción                                                                                                    |
| ------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------- |
| `isPlayerMula(citizenid)`                                    | `boolean`      | Si el personaje es una mula en activo.                                                                         |
| `getMulaData(citizenid)`                                     | `table \| nil` | `identificator`, `name`, `orgId`, `trustLevel`, `status`, `completedContracts`, `failedContracts`, `joinDate`. |
| `getMulaOrg(citizenid)`                                      | `any \| nil`   | Organización para la que trabaja la mula.                                                                      |
| `getOrgMulas(orgId)`                                         | `table[]`      | Mulas de una organización.                                                                                     |
| `getMulaActiveContract(citizenid)`                           | `table \| nil` | El encargo que la mula tiene en curso.                                                                         |
| `completeMulaContractStep(citizenid, contractId, stepIndex)` |                | Da por hecho un paso de un encargo desde tu propio recurso.                                                    |
| `failMulaContract(citizenid, contractId)`                    | `boolean`      | Falla un encargo asignado a esa mula.                                                                          |

### Arsenal

| Export                   | Devuelve         | Descripción                                                                                   |
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------- |
| `getArsenalLevel(orgId)` | `number, number` | Nivel del arsenal y unidades vendidas por la organización. `0, 0` con el arsenal desactivado. |
| `getArsenalParts()`      | `table[]`        | Catálogo de piezas: `{ item, label, price }`.                                                 |

### Efectos sobre una organización

Pensados para un recurso de policía o de staff. Cambian el estado de la organización.

| Export                                      | Devuelve                    | Descripción                                                                                      |
| ------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| `applyPoliceStrike(orgId, { loyalty = n })` | `{ turfs, loyalty } \| nil` | Quita `n` de lealtad a la organización en todos los territorios donde tenga.                     |
| `seizeOrgMoney(orgId, account)`             | `number`                    | Vacía una cuenta y devuelve el importe. `account` es `'balance'` o `'dirtymoney'` (por defecto). |
| `seizeOrgStash(orgId)`                      | `table[]`                   | Vacía el alijo principal y devuelve `{ name, label, count }` por ítem.                           |

{% hint style="danger" %}
Estos tres no se pueden deshacer. Llámalos solo desde código de servidor en el que confíes.
{% endhint %}

### RegisterExtortionVictim

Añade un civil al que se puede extorsionar por teléfono, además de los de `data/extortion.lua`.

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

| Campo                                            | Tipo   | Descripción                                                     |
| ------------------------------------------------ | ------ | --------------------------------------------------------------- |
| `id`                                             | string | Id único. Obligatorio.                                          |
| `name`                                           | string | Nombre visible. Obligatorio.                                    |
| `personality`                                    | string | `greedy`, `trusting`, `suspicious` o `aggressive`. Obligatorio. |
| `occupation`, `wealthHint`, `pedModel`, `avatar` |        | Opcionales.                                                     |

**Devuelve:** `boolean`. `false` cuando la forma no es válida.

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

### RegisterExtortionFixer

Añade un intermediario, además de los de `data/extortionFixers.lua`.

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

`fixer` necesita `id`, `name` y `personality` (`sharp`, `gruff` o `silky`). Los precios y límites que falten toman los valores por defecto del archivo.

**Devuelve:** `boolean`.

## Eventos de servidor

Estos cinco son solo de servidor. Dispáralos con `TriggerEvent` desde código de servidor. Una llamada que venga de un cliente se registra y se ignora.

| Evento                                | Parámetros               | Qué hace                                                                 |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------------ |
| `cuxial_gang:addOrganisationEXP`      | `orgId, amount`          | Suma experiencia. La organización sube de nivel cuando tiene suficiente. |
| `cuxial_gang:addOrganisationMoney`    | `orgId, amount, account` | Suma dinero. `account` es `'balance'` o `'dirtymoney'`.                  |
| `cuxial_gang:removeOrganisationMoney` | `orgId, amount, account` | Quita dinero. No hace nada si no hay suficiente.                         |
| `cuxial_gang:addOrgMissionsDone`      | `orgId, amount`          | Suma al contador de misiones hechas.                                     |
| `cuxial_gang:addZonesCaptured`        | `orgId, amount`          | Suma al contador de zonas capturadas.                                    |

```lua
-- Premiar a la organización de un jugador después de un atraco
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
```

### Eventos que puedes escuchar

Eventos locales de servidor, lanzados con `TriggerEvent`.

| Evento                                | Parámetros                                                        | Cuándo                                                                                       |
| ------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `cuxial_gang:server:ZoneOwnerChanged` | `{ zoneIndex, oldOwnerId, newOwnerId }`                           | Un territorio cambia de dueño.                                                               |
| `cuxial_gang:server:SaleRecorded`     | `{ orgId, turfIndex, units, amount, citizenid, source, counted }` | Se registra una venta de droga. `counted` son las unidades que puntuaron.                    |
| `cuxial_gang:server:PlayerLeftGang`   | `src, citizenid`                                                  | Un jugador sale o es expulsado de una organización.                                          |
| `cuxial_gang:intel`                   | `kind, payload`                                                   | Una organización hace algo relevante. Solo se lanza mientras `cuxial_police` está en marcha. |

`kind` es uno de `drug_sale`, `laundry`, `graffiti`, `mula`, `turf`, `favela`, `airdrop`, `weapon_crafted`, `supply_robbed`, `supply_seized`, `vehicle_seized` u `officer_kidnap`. `payload` lleva siempre `gangId` y `gangLabel` cuando se conocen, normalmente `coords`, y campos que dependen del tipo.

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

## Exports de cliente

### getPlayerOrganisation

Devuelve la organización del jugador local.

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

**Devuelve:** `table | false`. `{ id = number, label = string, bossmenuCoords = vector4 }`. `false` cuando el jugador no tiene organización o los datos aún no han cargado.

### hasOrgPermission

Indica si el rango del jugador local tiene un permiso. Lee una copia replicada, así que úsalo para pintar interfaz; vuelve a comprobarlo en el servidor antes de actuar.

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

**Devuelve:** `boolean`.

### getOrgPermissions

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

**Devuelve:** `table | nil`. Un mapa de nombre de permiso a `true`.

### Otras consultas

| Export           | Devuelve       | Descripción                                            |
| ---------------- | -------------- | ------------------------------------------------------ |
| `isInTurfZone()` | `any \| nil`   | Índice del territorio en el que está el jugador.       |
| `isPlayerMula()` | `boolean`      | Si el jugador local es una mula. Pregunta al servidor. |
| `getMulaData()`  | `table \| nil` | Ficha de mula del jugador local. Pregunta al servidor. |

### Abrir las interfaces

| Export                | Descripción                                               |
| --------------------- | --------------------------------------------------------- |
| `OpenTablet()`        | Abre la tablet. `openCrimeTablet()` hace lo mismo.        |
| `openHandcuffsMenu()` | Abre el menú de interacción sobre el jugador más cercano. |
| `useSpray()`          | Empieza a pintar un grafiti.                              |
| `useRemover()`        | Empieza a borrar un grafiti.                              |

Son los exports a los que apuntar un ítem del inventario.

### OpenInteractionMenu

Abre el mismo menú en rueda con tus propias entradas.

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

| Parámetro            | Tipo     | Descripción                                                                                                  |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `payload.title`      | string   | Título del menú.                                                                                             |
| `payload.targetName` | string   | Nombre que se muestra como objetivo.                                                                         |
| `payload.targetMeta` | string   | Texto pequeño bajo el nombre. Opcional.                                                                      |
| `payload.icon`       | string   | Clase de Font Awesome, como `fa-solid fa-user`. Opcional.                                                    |
| `payload.items`      | table\[] | Entradas: `value`, `title`, `description`, `icon` y `tone` (`warn`, `success` o `destructive`). Obligatorio. |
| `handlers`           | table    | Mapa de `value` a la función que se ejecuta al elegir esa entrada.                                           |

```lua
exports.cuxial_gang:OpenInteractionMenu({
    title = 'Informante',
    targetName = 'Desconocido',
    items = {
        { value = 'ask', title = 'Preguntar', description = 'Preguntar por la zona.', icon = 'fa-solid fa-comment' },
    },
}, {
    ask = function()
        print('preguntado')
    end,
})
```

`exports.cuxial_gang:CloseInteractionMenu()` lo cierra.

### RegisterHostage

Hace que uno de tus NPC se pueda controlar como rehén: al apuntarle se abre el menú de rehén.

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

| Parámetro               | Tipo     | Descripción                                         |
| ----------------------- | -------- | --------------------------------------------------- |
| `ped`                   | number   | Handle de entidad de un ped que existe.             |
| `meta.name`             | string   | Nombre que se muestra en el menú. Opcional.         |
| `meta.contextKindLabel` | string   | Etiqueta del tipo de rehén. Opcional.               |
| `meta.icon`             | string   | Clase de Font Awesome. Opcional.                    |
| `meta.accentColor`      | string   | Color hexadecimal. Opcional.                        |
| `meta.onKilled`         | function | Se llama con `ped` cuando el rehén muere. Opcional. |

```lua
exports.cuxial_gang:RegisterHostage(ped, {
    name = 'Empleado del banco',
    onKilled = function(entity)
        print('rehén abatido', entity)
    end,
})
```

`UnregisterHostage(ped)` lo suelta e `IsHostageControlled(ped)` devuelve si está registrado.

## State bags

Los pone el servidor en cada jugador y se replican a los clientes.

| State bag        | Tipo            | Descripción                                                 |
| ---------------- | --------------- | ----------------------------------------------------------- |
| `gangName`       | string \| false | Nombre de la organización del jugador. `false` si no tiene. |
| `gangId`         | number \| nil   | Id de la organización.                                      |
| `gangRankName`   | string \| nil   | Etiqueta del rango.                                         |
| `orgPermissions` | table \| nil    | Mapa de nombre de permiso a `true`.                         |

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

{% hint style="info" %}
En el framework, cada organización se registra como una banda llamada `gang_<orgId>`, por ejemplo `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/es/bandas/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.