> 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/nucleo/cuxial-cmservices/developers.md).

# Exports y eventos

API pública de Cuxial Servicios Comunitarios: exports de servidor para leer, añadir y quitar sanciones.

Lee la sanción de un jugador, o da y quita comunitarias desde tus propios recursos, como un menú de administración o un panel web. La API son tres exports de servidor; el script no expone eventos públicos.

## Exports de servidor

### GetPlayerPunishment

Devuelve la sanción activa de un jugador.

```lua
exports.cuxial_cmservices:GetPlayerPunishment(player, punishmentType)
```

| Parámetro        | Tipo            | Descripción                                                                                                      |
| ---------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `player`         | number \| table | Id de servidor de un jugador conectado, o una tabla de jugador que lleve `citizenid` (o `PlayerData.citizenid`). |
| `punishmentType` | string          | `'comserv'` o `'jail'`.                                                                                          |

**Devuelve:** `table | false`. La sanción, o `false` si el jugador no tiene ninguna de ese tipo.

| Campo    | Tipo   | Descripción                                                 |
| -------- | ------ | ----------------------------------------------------------- |
| `count`  | number | Comunitarias: tareas que faltan. Cárcel: minutos cumplidos. |
| `all`    | number | Comunitarias: tareas asignadas. Cárcel: minutos totales.    |
| `reason` | string | Motivo escrito por el staff.                                |
| `start`  | number | Hora Unix en que se aplicó la sanción.                      |
| `admin`  | table  | Quién la aplicó: `name` e `identifier`.                     |

```lua
local jail = exports.cuxial_cmservices:GetPlayerPunishment(source, 'jail')
if jail then
    print(('Faltan %d minutos'):format(jail.all - jail.count))
end
```

### AddCommunityService

Da tareas comunitarias a un personaje. Funciona con el jugador conectado (se aplica al momento) o desconectado (se aplica en su próxima entrada). Si el personaje ya tiene comunitarias, las tareas se suman y el motivo se añade al anterior.

```lua
exports.cuxial_cmservices:AddCommunityService(citizenid, amount, reason, admin)
```

| Parámetro   | Tipo         | Descripción                                                                                |
| ----------- | ------------ | ------------------------------------------------------------------------------------------ |
| `citizenid` | string       | Identificador del personaje.                                                               |
| `amount`    | number       | Tareas a añadir. De 1 a 10000; los decimales se redondean hacia abajo.                     |
| `reason`    | string       | Motivo. Obligatorio. Se corta a 250 caracteres.                                            |
| `admin`     | table \| nil | Quién las da: `{ name = string, identifier = string }`. Ambos valen `'panel'` por defecto. |

**Devuelve:** `boolean, string`. `true` más `'online'` u `'offline'`, según si el jugador estaba conectado. `false` más la causa cuando la petición se rechaza:

| Segundo valor                                | Causa                                       |
| -------------------------------------------- | ------------------------------------------- |
| `'citizenid inválido'`                       | `citizenid` no es una cadena con contenido. |
| `'cantidad inválida'`                        | `amount` está fuera de rango.               |
| `'sin motivo'`                               | `reason` está vacío.                        |
| `'el jugador está en cárcel administrativa'` | El personaje tiene tiempo de cárcel activo. |
| `'no se pudo guardar en la base de datos'`   | Falló la escritura en la base de datos.     |

```lua
local ok, detail = exports.cuxial_cmservices:AddCommunityService('ABC12345', 10, 'Deathmatch con vehículo', {
    name = GetPlayerName(source),
    identifier = 'ABC00001',
})

if not ok then
    print('Rechazado: ' .. detail)
end
```

{% hint style="warning" %}
El export no comprueba quién lo llama. Comprueba el permiso del miembro del staff en tu propio recurso antes de llamarlo.
{% endhint %}

### RemoveCommunityService

Quita las comunitarias de un personaje. Un jugador conectado es llevado al punto de salida y recibe una notificación.

```lua
exports.cuxial_cmservices:RemoveCommunityService(citizenid, admin)
```

| Parámetro   | Tipo         | Descripción                                                              |
| ----------- | ------------ | ------------------------------------------------------------------------ |
| `citizenid` | string       | Identificador del personaje.                                             |
| `admin`     | table \| nil | Quién las quita: `{ name = string }`. `name` vale `'panel'` por defecto. |

**Devuelve:** `boolean, string`. `true` más `'online'` u `'offline'`. `false` más la causa:

| Segundo valor             | Causa                                       |
| ------------------------- | ------------------------------------------- |
| `'citizenid inválido'`    | `citizenid` no es una cadena con contenido. |
| `'no tiene comunitarias'` | El personaje no tiene comunitarias activas. |

```lua
local ok, detail = exports.cuxial_cmservices:RemoveCommunityService('ABC12345', {
    name = GetPlayerName(source),
})
```


---

# 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/nucleo/cuxial-cmservices/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.