> 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/interfaz/cuxial-chat/configuration.md).

# Configuración

Todas las opciones de Cuxial Chat explicadas: config, canales y paleta de comandos.

Todo lo que puedes ajustar está en tres archivos: `shared/config.lua` para el comportamiento, `data/channels.lua` para los canales y `data/commands.lua` para la paleta de comandos. Reinicia el recurso después de cada cambio.

## General

| Opción            | Tipo    | Por defecto | Qué hace                                                                                                                      |
| ----------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `debug`           | boolean | `false`     | Imprime trazas en consola. También se activa poniendo la convar `cuxial_chat_debug` en `1`.                                   |
| `proximity`       | number  | `12.0`      | Radio en metros de los canales de proximidad: IC, OOC, ME, DO, tiradas e imágenes.                                            |
| `persistSettings` | boolean | `true`      | `true` guarda los ajustes de cada jugador en base de datos, ligados al personaje. `false` los deja solo en el PC del jugador. |

## Interfaz · `ui`

| Opción        | Tipo         | Por defecto  | Qué hace                                                                                          |
| ------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------- |
| `accent`      | string (hex) | configurable | Color de acento de la interfaz.                                                                   |
| `openKey`     | string       | `'T'`        | Tecla por defecto que abre el chat. Cada jugador puede cambiarla en los ajustes de teclas de GTA. |
| `maxMessages` | number       | `400`        | Mensajes que la interfaz guarda en memoria. De 21 a 2000.                                         |

## Acciones de rol · `actions`

| Opción    | Tipo   | Por defecto | Qué hace                                                                                                                                                                                                                  |
| --------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display` | string | `'head'`    | Dónde se ven `/me`, `/do` y las tiradas para quien no lo haya elegido. `'both'` = en el chat y sobre la cabeza, `'head'` = solo sobre la cabeza, `'chat'` = solo en el chat. Cualquier otro valor funciona como `'both'`. |

{% hint style="info" %}
Es solo el valor por defecto del servidor. Cada jugador puede elegir el suyo en los ajustes del chat, y su elección manda.
{% endhint %}

## Burbujas · `bubble`

| Opción       | Tipo    | Por defecto | Qué hace                                                                                                   |
| ------------ | ------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `distance`   | number  | `25.0`      | Metros a partir de los que no se dibuja la burbuja. También es el alcance del aviso de «está escribiendo». |
| `ms`         | number  | `6000`      | Milisegundos que vive una burbuja.                                                                         |
| `tick`       | number  | `50`        | Milisegundos entre refrescos con burbujas a la vista. Menos es más fluido y consume más.                   |
| `idle`       | number  | `300`       | Milisegundos entre comprobaciones cuando no hay nada que dibujar.                                          |
| `typingMs`   | number  | `8000`      | Milisegundos hasta que caduca el aviso de «está escribiendo».                                              |
| `typingSelf` | boolean | `true`      | `true` muestra tu propio aviso de escritura. `false` solo lo ven los demás.                                |
| `stack`      | number  | `3`         | Máximo de burbujas apiladas por jugador.                                                                   |

## Nombre anónimo · `anonymous`

Oculta el nombre del jugador mientras lleva máscara.

| Opción     | Tipo      | Por defecto              | Qué hace                                                                                |
| ---------- | --------- | ------------------------ | --------------------------------------------------------------------------------------- |
| `enabled`  | boolean   | `true`                   | `true` oculta el nombre con máscara. `false` muestra siempre el nombre.                 |
| `anyMask`  | boolean   | `true`                   | `true` vale cualquier máscara. `false` solo las de la lista `masks`.                    |
| `masks`    | number\[] | `{}`                     | Números de máscara (drawable) que ocultan el nombre. Solo se usa con `anyMask = false`. |
| `label`    | string    | `'anonymous_label'`      | Nombre que se muestra en su lugar. Clave de locale o texto literal.                     |
| `channels` | table     | `me`, `do`, `dice`, `ic` | Canales en los que se oculta el nombre: `true` lo oculta, `false` lo muestra.           |

Solo los canales de proximidad pueden ocultar el nombre: `ic`, `ooc`, `me`, `do` y `dice`. Los mensajes privados y el canal de organizaciones muestran siempre el nombre real.

## Canal de organizaciones · `gchat`

Un canal común a todas las organizaciones. La variante pública también la lee la policía.

| Opción           | Tipo         | Por defecto            | Qué hace                                                                                                                 |
| ---------------- | ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `enabled`        | boolean      | `true`                 | `false` quita los dos comandos.                                                                                          |
| `command`        | string       | `'gchat'`              | Comando del canal entre organizaciones.                                                                                  |
| `publicCommand`  | string       | `'gchatp'`             | Comando de la variante que también lee la policía.                                                                       |
| `policeJobs`     | string\[]    | `{ 'leo' }`            | Lista de trabajos policiales. Añade los de tu servidor. Cada entrada vale como tipo de trabajo o como nombre de trabajo. |
| `requireDuty`    | boolean      | `true`                 | `true` = la policía solo lee y escribe estando de servicio. `false` = siempre.                                           |
| `policeCanWrite` | boolean      | `true`                 | `true` = la policía puede escribir en el canal público. `false` = solo leer.                                             |
| `fallbackColor`  | string (hex) | `'#8b5cf6'`            | Color de una organización sin color propio.                                                                              |
| `policeColor`    | string (hex) | `'#4f8cff'`            | Color de los mensajes de la policía y de la etiqueta «Abierto».                                                          |
| `policeLabel`    | string       | `'gchat_police_label'` | Etiqueta de la policía. Clave de locale o texto literal.                                                                 |

{% hint style="info" %}
Una organización es la banda (gang) del jugador, tal como la informa `cuxial_bridge`. Todo lo que escribe la policía se envía siempre como público.
{% endhint %}

## Imágenes · `images`

| Opción       | Tipo      | Por defecto                                                                    | Qué hace                                                         |
| ------------ | --------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| `enabled`    | boolean   | `false`                                                                        | `true` registra el comando de imágenes.                          |
| `command`    | string    | `'img'`                                                                        | Comando para enviar una imagen.                                  |
| `channel`    | string    | `'ooc'`                                                                        | Canal por el que sale la imagen. Un `id` de `data/channels.lua`. |
| `hosts`      | string\[] | `i.imgur.com`, `cdn.discordapp.com`, `media.discordapp.net`, `media.tenor.com` | Dominios permitidos. Cualquier otro enlace se rechaza.           |
| `extensions` | string\[] | `png`, `jpg`, `jpeg`, `gif`, `webp`                                            | Extensiones de archivo permitidas, en minúsculas.                |
| `perMinute`  | number    | `3`                                                                            | Imágenes por jugador y minuto.                                   |

Solo se aceptan enlaces `https` de hasta 400 caracteres, y el enlace tiene que acabar en el archivo de imagen. Las imágenes llegan siempre a los jugadores cercanos, sea cual sea el canal.

## Registros · `logs`

| Opción             | Tipo    | Por defecto                | Qué hace                                                                                                                          |
| ------------------ | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`          | boolean | `true`                     | `false` no guarda nada.                                                                                                           |
| `channels`         | table   | `ooc`, `ic`, `pm`, `gchat` | Canales que se registran. Una tabla vacía registra todos.                                                                         |
| `database`         | boolean | `true`                     | `true` guarda en la tabla `cuxial_chat_logs`. `false` envía solo a Discord.                                                       |
| `keepDays`         | number  | `14`                       | Días que se conservan los registros en base de datos. `0` los guarda para siempre. Los antiguos se borran al arrancar el recurso. |
| `discord.convar`   | string  | `'cuxial_chat_webhook'`    | Nombre de la convar de `server.cfg` con la URL del webhook. Convar vacía = sin Discord.                                           |
| `discord.batch`    | number  | `15`                       | Mensajes en cola que provocan un envío inmediato al webhook.                                                                      |
| `discord.flushMs`  | number  | `20000`                    | Milisegundos entre volcados. Vale para el webhook y para la base de datos.                                                        |
| `discord.username` | string  | `'Chat'`                   | Nombre con el que publica el webhook.                                                                                             |

## Canales · `data/channels.lua`

Cada entrada es un canal: su pestaña, su color y el comando con el que se escribe.

| Campo     | Tipo         | Qué hace                                                                                        |
| --------- | ------------ | ----------------------------------------------------------------------------------------------- |
| `id`      | string       | Identificador interno. Lo usan el config y los exports.                                         |
| `label`   | string       | Clave de locale del nombre que sale en la pestaña.                                              |
| `voice`   | string       | Clave de locale del rótulo que sale en la burbuja.                                              |
| `color`   | string (hex) | Color del canal.                                                                                |
| `tab`     | boolean      | `true` le da pestaña propia. `false` lo muestra solo en la vista general.                       |
| `order`   | number       | Posición de la pestaña.                                                                         |
| `icon`    | string       | Icono de la burbuja: `user`, `eye`, `dice`, `lock`, `radio`, `message`, `shield` o `megaphone`. |
| `command` | string       | Comando del canal. Solo se puede escribir directamente en una pestaña si su canal lo tiene.     |
| `sound`   | boolean      | `true` suena al llegar un mensaje.                                                              |
| `bubble`  | boolean      | `true` muestra sus mensajes sobre la cabeza del autor.                                          |
| `mutable` | boolean      | `false` impide que los jugadores silencien el canal en sus ajustes.                             |

Canales incluidos: `ic`, `ooc`, `me`, `do`, `pm`, `dice`, `gchat`, `sancion` y `system`.

{% hint style="warning" %}
No borres `ic` ni `system`. Los mensajes sin canal caen en `ic` y los de otros recursos en `system`.
{% endhint %}

## Paleta de comandos · `data/commands.lua`

La lista que el chat sugiere cuando el jugador escribe `/`. Solo describe los comandos; no los crea.

| Campo     | Tipo   | Qué hace                                                                          |
| --------- | ------ | --------------------------------------------------------------------------------- |
| `name`    | string | Comando sin la barra.                                                             |
| `help`    | string | Clave de locale de la descripción.                                                |
| `channel` | string | Canal al que pertenece el comando. Da el color a la sugerencia.                   |
| `params`  | table  | Argumentos que se muestran, cada uno con `name` y, si procede, `optional = true`. |

Los comandos que anuncian otros recursos se añaden solos a esta lista.

## Textos

Todos los textos están en `locales/es.json` y `locales/en.json`. El idioma sigue la convar `ox:locale`.

## Cambios habituales

### Mostrar las acciones también en el chat

{% code title="shared/config.lua" %}

```lua
actions = {
    display = 'both',
},
```

{% endcode %}

### Ocultar el nombre solo con ciertas máscaras

{% code title="shared/config.lua" %}

```lua
anonymous = {
    enabled = true,
    anyMask = false,
    masks = { 51, 52, 111 },
    label = 'anonymous_label',
    channels = {
        me = true,
        ['do'] = true,
        dice = true,
        ic = false,
    },
},
```

{% endcode %}

### Activar las imágenes

{% code title="shared/config.lua" %}

```lua
images = {
    enabled = true,
    command = 'img',
    channel = 'ooc',
    hosts = { 'i.imgur.com' },
    extensions = { 'png', 'jpg', 'jpeg', 'gif', 'webp' },
    perMinute = 3,
},
```

{% endcode %}

### Cambiar el nombre de los comandos de organizaciones

{% code title="shared/config.lua" %}

```lua
gchat = {
    command = 'org',
    publicCommand = 'orgp',
    -- deja el resto del bloque como está
},
```

{% endcode %}

{% hint style="info" %}
Después de renombrarlos, actualiza las entradas `gchat` y `gchatp` de `data/commands.lua` para que la paleta muestre los nombres nuevos.
{% endhint %}

### Registrar todos los canales solo en Discord

{% code title="shared/config.lua" %}

```lua
logs = {
    enabled = true,
    channels = {},
    database = false,
    keepDays = 14,
    discord = {
        convar = 'cuxial_chat_webhook',
        batch = 15,
        flushMs = 20000,
        username = 'Chat',
    },
},
```

{% endcode %}


---

# 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/interfaz/cuxial-chat/configuration.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.