> 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-multichar/developers.md).

# Exports y eventos

API pública de Cuxial Multichar: exports y eventos para revisar las solicitudes de personajes menores desde tus recursos.

La API pública cubre las solicitudes de personajes menores, para que un panel de administración o una herramienta de staff pueda listarlas, aprobarlas y gestionarlas. Todos los exports son de servidor.

{% hint style="danger" %}
Estos exports no comprueban quién los llama. Verifica el permiso de staff en tu propio recurso antes de llamar a `FamilyReview` o a `FamilySetGrowth`.
{% endhint %}

{% hint style="info" %}
Los exports necesitan `family.enabled = true`. Con los menores desactivados, `FamilyPending` devuelve `0` y el resto no se debe llamar.
{% endhint %}

## El objeto solicitud

`FamilyGet`, `FamilyList` y el evento `cuxial_multichar:family:Changed` devuelven solicitudes con esta forma:

| Campo                      | Tipo         | Contenido                                                                                                            |
| -------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `citizenid`                | string       | Citizenid del menor                                                                                                  |
| `status`                   | string       | `pending`, `approved`, `rejected` o `revoked`                                                                        |
| `bond`                     | string       | `biological` o `adopted`                                                                                             |
| `father`, `mother`         | table / nil  | `{ citizenid, name, onlineId }`. `onlineId` es el ID de servidor del progenitor si se está jugando con ese personaje |
| `motivation`               | string       | Texto escrito por el jugador                                                                                         |
| `child`                    | table        | `{ firstname, lastname, dob, age, gender, nationality }`. `gender` es `0` (hombre) o `1` (mujer)                     |
| `playerName`               | string       | Nombre del jugador que la envió                                                                                      |
| `license`                  | string       | Licencia del jugador                                                                                                 |
| `onlineId`                 | number / nil | ID de servidor del jugador si está conectado                                                                         |
| `reviewedBy`, `reviewNote` | string / nil | Quién la revisó y la nota                                                                                            |
| `reviewedAt`, `createdAt`  | number       | Fechas en milisegundos. `reviewedAt` es `nil` hasta que la solicitud se revisa                                       |
| `growth`                   | table / nil  | `{ enabled, height, max, min, shrink, adult }`. Solo en solicitudes aprobadas                                        |

## Exports

### FamilyPending

Número de solicitudes a la espera de revisión.

```lua
---@return integer
local pendientes = exports.cuxial_multichar:FamilyPending()
```

### FamilyGet

Una solicitud por citizenid.

```lua
---@param citizenid string
---@return table? solicitud
local solicitud = exports.cuxial_multichar:FamilyGet('ABC12345')
```

### FamilyList

Lista paginada de solicitudes. Recibe una tabla con estos campos, todos opcionales:

| Parámetro  | Tipo   | Contenido                                                                     |
| ---------- | ------ | ----------------------------------------------------------------------------- |
| `status`   | string | `pending` (por defecto), `approved`, `rejected`, `revoked`, `history` o `all` |
| `search`   | string | Filtra por citizenid, nombre del jugador o nombre del personaje               |
| `page`     | number | Página, desde `1`                                                             |
| `pageSize` | number | Filas por página. Por defecto `25`, máximo `100`                              |

Devuelve `{ rows, total, page, pages, counts }`. `counts` contiene `pending`, `approved`, `rejected`, `revoked` y `online`.

```lua
local resultado = exports.cuxial_multichar:FamilyList({ status = 'pending', page = 1 })

for _, solicitud in ipairs(resultado.rows) do
    print(solicitud.citizenid, solicitud.child.firstname, solicitud.status)
end
```

### FamilyReview

Aprueba, rechaza o revoca una solicitud. Recibe una tabla:

| Parámetro   | Tipo   | Contenido                                                                     |
| ----------- | ------ | ----------------------------------------------------------------------------- |
| `citizenid` | string | Citizenid del menor                                                           |
| `decision`  | string | `approve` o `reject` para solicitudes pendientes. `revoke` para las aprobadas |
| `note`      | string | Nota opcional que ve el jugador. Hasta 300 caracteres                         |
| `reviewer`  | table  | `{ name }` del miembro del staff. Si falta, se guarda como `Staff`            |

Devuelve `true`, o una cadena de error: `'not_found'` (no hay solicitud para ese citizenid), `'bad_state'` (la decisión no encaja con el estado actual) o `'bad_decision'` (decisión desconocida).

```lua
local resultado = exports.cuxial_multichar:FamilyReview({
    citizenid = 'ABC12345',
    decision = 'approve',
    note = 'Bienvenido',
    reviewer = { name = GetPlayerName(source) },
})
```

Si se revoca un menor con el que se está jugando, ese jugador vuelve a la selección.

### FamilySetGrowth

Fija las reglas de estatura de un menor aprobado. Recibe una tabla. Cada llamada guarda las cuatro reglas: las que omitas se guardan como `false`, y `max` como la estatura actual.

| Parámetro   | Tipo    | Contenido                                                                  |
| ----------- | ------- | -------------------------------------------------------------------------- |
| `citizenid` | string  | Citizenid del menor                                                        |
| `enabled`   | boolean | Deja al jugador cambiar su estatura con el comando de crecimiento          |
| `max`       | number  | Estatura máxima en cm. No puede ser menor que la actual ni mayor que `200` |
| `shrink`    | boolean | Deja al jugador bajar de su estatura actual                                |
| `adult`     | boolean | Quita el escalado: el personaje usa el tamaño adulto                       |

Devuelve `true`, o una cadena de error: `'not_found'` (no hay solicitud para ese citizenid), `'bad_state'` (la solicitud no está aprobada) o `'bad_range'` (`max` fuera de rango).

```lua
exports.cuxial_multichar:FamilySetGrowth({
    citizenid = 'ABC12345',
    enabled = true,
    max = 165,
    shrink = false,
    adult = false,
})
```

## Eventos

### cuxial\_multichar:family:Changed

Evento de servidor. Se dispara cuando una solicitud se crea, se revisa, se cambia con `FamilySetGrowth` o se borra. Recibe el objeto solicitud, con `status` en `'deleted'` cuando el personaje se ha borrado.

```lua
AddEventHandler('cuxial_multichar:family:Changed', function(solicitud)
    -- solicitud.status: 'pending', 'approved', 'rejected', 'revoked' o 'deleted'
    print(solicitud.citizenid, solicitud.status)
end)
```

## State bag

`cuxialScale` se fija en el jugador mientras juega con un menor aprobado. Contiene el factor de escala (estatura dividida entre la estatura adulta de referencia). Es `nil` para el resto, y para los menores marcados como `adult`. Está replicado, así que los clientes también pueden leerlo.

```lua
local escala = Player(source).state.cuxialScale
```


---

# 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-multichar/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.