> 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/primeros-pasos/cuxial-jobs.md).

# Cuxial Jobs

La librería común de los trabajos por equipos de Cuxial: tripulaciones, partidas, pagos y progreso.

Cuxial Jobs es la librería común que usan los trabajos por equipos de Cuxial: Cuxial Diving, Cuxial Electrician y Cuxial Gardener. Les da a todos las mismas tripulaciones, partidas, pagos y progreso del jugador, así que todos los trabajos se comportan igual y se configuran igual.

Viene incluida en el paquete de cada uno de esos trabajos. Se instala una sola vez y la comparten todos los trabajos que tengas.

{% hint style="info" %}
Es una librería: no tiene comandos, interfaz ni archivo de configuración propios. Cada trabajo la carga y la usa con sus propios ajustes.
{% endhint %}

## Qué aporta a cada trabajo

| Parte                 | Qué recibe el trabajo                                                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Punto del trabajo     | Un NPC con blip y una opción de target que abre el menú del trabajo.                                                                                                                 |
| Tripulaciones         | Invitaciones a jugadores cercanos, un tamaño máximo, asiento guardado para quien se desconecta en plena partida y un reparto de la recompensa que decide el dueño de la tripulación. |
| Partidas              | Regiones donde trabajar, opcionalmente una tripulación por región a la vez, una espera opcional entre partidas y la entrega final.                                                   |
| Pago                  | Dinero a la cuenta que elijas, varias formas de repartirlo entre la tripulación y recompensas opcionales en items.                                                                   |
| Progreso              | Nivel y experiencia por trabajo, tareas diarias, historial de partidas y ranking.                                                                                                    |
| Ropa de trabajo       | Ropa de trabajo opcional para la partida; al terminar se recupera la ropa del jugador.                                                                                               |
| Ayudas                | Pistas de primera vez y resumen al final de la partida.                                                                                                                              |
| Herramientas de staff | Comandos para listar y cerrar tripulaciones, registro de auditoría y registros en Discord por webhook.                                                                               |

El progreso se guarda por trabajo: el nivel de un jugador como buzo es independiente de su nivel como electricista.

## Instalación

{% stepper %}
{% step %}

## Revisa las dependencias

Cuxial Jobs no necesita nada por sí misma. Los trabajos que la usan necesitan:

* OneSync
* `ox_lib`
* `oxmysql`
* `cuxial_bridge`
* `sleepless_interact`

Cuxial Diving y Cuxial Gardener necesitan además su recurso de assets, `cuxial_diving_assets` y `cuxial_gardener_assets`, que se entrega con cada script.
{% endstep %}

{% step %}

## Copia el recurso

Coloca la carpeta `cuxial_jobs` en tu directorio `resources`. Una sola copia sirve para todos los trabajos. Si dos paquetes traen versiones distintas, quédate con la más nueva.

{% hint style="danger" %}
Mantén el nombre de carpeta `cuxial_jobs`. Todos los trabajos la cargan con ese nombre exacto y no arrancan si lo cambias.
{% endhint %}
{% endstep %}

{% step %}

## Arráncala antes que los trabajos

Añádela debajo de Cuxial Bridge y encima de todos los trabajos.

{% code title="server.cfg" %}

```cfg
ensure ox_lib
ensure oxmysql
# aquí tu framework y tu inventario
ensure sleepless_interact

ensure cuxial_bridge
ensure cuxial_jobs

ensure cuxial_diving_assets
ensure cuxial_gardener_assets

ensure cuxial_diving
ensure cuxial_electrician
ensure cuxial_gardener
```

{% endcode %}

Pon solo los trabajos que tengas.
{% endstep %}

{% step %}

## Revisa la consola del servidor

Al arrancar, la librería muestra su versión:

```
[cuxial_jobs] 1.0.0 listo (librería de trabajos por equipos)
```

No hay SQL que ejecutar. El primer trabajo que arranca crea las tablas compartidas.
{% endstep %}
{% endstepper %}

## Configuración

Cuxial Jobs no tiene archivo de configuración ni convars propias. Todo lo que hace se ajusta en cada trabajo, en su `shared/config.lua` y su carpeta `data`, así que dos trabajos pueden usar valores distintos.

Estos bloques aparecen en todos los trabajos y los lee la librería:

| Bloque en el `shared/config.lua` del trabajo | Qué controla                                                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `debug`                                      | Mensajes de depuración en la consola.                                                                              |
| `ui`                                         | Color de acento del menú del trabajo y formato del dinero.                                                         |
| `logs`                                       | Nombre de la convar que guarda el webhook de Discord.                                                              |
| `admin`                                      | Días que se conserva el registro de auditoría.                                                                     |
| `account`                                    | Cuenta que recibe el dinero.                                                                                       |
| `job`                                        | Quién puede hacer el trabajo: `'all'`, un trabajo del framework o una lista.                                       |
| `npc`                                        | Posición, modelo, distancias y blip del NPC del trabajo.                                                           |
| `crew`                                       | Tamaño de la tripulación, distancia y tiempo de las invitaciones, tiempo de reconexión y reparto de la recompensa. |
| `run`                                        | Espera entre partidas y si una región admite una sola tripulación a la vez.                                        |
| `reward`                                     | Cómo se reparte el pago y qué items se entregan.                                                                   |
| `outfit`                                     | Modo de la ropa de trabajo.                                                                                        |
| `leaderboard`, `history`, `profile`          | Tamaño del ranking y del historial, y cada cuánto se guarda el progreso.                                           |
| `commands`                                   | Nombres de los comandos del trabajo y quién puede usarlos.                                                         |
| `keys`                                       | Teclas por defecto.                                                                                                |
| `tips`, `finish`                             | Segundos que las pistas y el resumen final permanecen en pantalla.                                                 |

Los niveles, las tareas diarias, las regiones y la ropa están en la carpeta `data` del trabajo: `levels.lua`, `daily.lua`, `regions.lua` y `outfits.lua`.

La página de cada trabajo explica sus propios valores y las opciones que solo tiene ese trabajo.

### Convars por trabajo

Cada trabajo lee dos convars opcionales. Sus nombres empiezan por el nombre de la carpeta del trabajo, aquí `<recurso>`.

| Convar              | Para qué                                                                                        | Se define con |
| ------------------- | ----------------------------------------------------------------------------------------------- | ------------- |
| `<recurso>_debug`   | `1` activa los mensajes de depuración sin editar el config.                                     | `setr`        |
| `<recurso>_webhook` | Webhook de Discord para los registros de ese trabajo. Vacía significa sin registros en Discord. | `set`         |

{% code title="server.cfg" %}

```cfg
setr cuxial_diving_debug "0"
set cuxial_diving_webhook "https://discord.com/api/webhooks/..."
```

{% endcode %}

{% hint style="warning" %}
El webhook va en `server.cfg`, nunca en `shared/config.lua`. Se lee una sola vez al arrancar el trabajo, así que coloca la línea encima del `ensure` del trabajo. El nombre de la convar del webhook se puede cambiar en `logs.convar` del trabajo.
{% endhint %}

### Comandos por trabajo

Cada trabajo registra sus propios comandos. Sus nombres se definen en el bloque `commands` del trabajo, y poner un `name` a `false` quita ese comando.

| Entrada | Quién | Qué hace                                                             |
| ------- | ----- | -------------------------------------------------------------------- |
| `reset` | Todos | Reinicia la partida actual del jugador.                              |
| `leave` | Todos | Sale de la tripulación. El dueño no puede salir durante una partida. |
| `list`  | Staff | Lista las tripulaciones abiertas con su tamaño, región y fase.       |
| `close` | Staff | Cierra una tripulación por su número.                                |
| `fast`  | Staff | Atajo de pruebas. Solo funciona con `debug` activado.                |

Las entradas de staff están limitadas por su valor `restricted`, `'group.admin'` por defecto.

## Base de datos

Los trabajos comparten cuatro tablas, que se crean solas cuando arranca el primer trabajo:

| Tabla                     | Qué guarda                                                          |
| ------------------------- | ------------------------------------------------------------------- |
| `cuxial_jobs_players`     | Nivel, experiencia y tareas diarias de cada personaje, por trabajo. |
| `cuxial_jobs_runs`        | Partidas terminadas.                                                |
| `cuxial_jobs_run_members` | Quién participó en cada partida y qué ganó.                         |
| `cuxial_jobs_audit`       | Registro de auditoría de las acciones del staff.                    |

Quitar un trabajo no borra sus filas.

## Actualizaciones

Un trabajo y la librería están hechos para funcionar juntos. Cada trabajo indica qué versión de la librería espera, y la librería avisa en la consola del servidor cuando no coinciden:

```
[cuxial_jobs] cuxial_diving pide la librería 2.0 y esta es la 1.0.0
```

Cuando actualices un trabajo, sustituye la carpeta `cuxial_jobs` por la del mismo paquete y reinicia el servidor. Consulta [Actualizar un script](/scripts/es/primeros-pasos/updating.md).

## Problemas frecuentes

<details>

<summary>Un trabajo no arranca y el error menciona cuxial_jobs</summary>

**Causa.** La librería falta, se ha renombrado o arranca después del trabajo.

**Solución.** Comprueba que la carpeta se llama `cuxial_jobs` y que `ensure cuxial_jobs` aparece antes que el trabajo.

</details>

<details>

<summary>La consola dice que un trabajo pide otra versión de la librería</summary>

**Causa.** El trabajo y `cuxial_jobs` vienen de versiones distintas.

**Solución.** Sustituye `cuxial_jobs` por la copia del paquete más nuevo que tengas y actualiza los demás trabajos a esa misma versión.

</details>

<details>

<summary>La consola avisa de items que no existen en el inventario</summary>

El aviso dice `items que no existen en el inventario:` seguido de los nombres de los items.

**Causa.** El trabajo entrega items como recompensa y alguno no está registrado en tu inventario.

**Solución.** Añade los items a tu inventario o quítalos de `reward.items` del trabajo.

</details>

<details>

<summary>El progreso no se guarda</summary>

**Causa.** Las tablas compartidas no se pudieron crear. La consola del servidor muestra una consulta fallida del trabajo.

**Solución.** Revisa la conexión de `oxmysql` y que el usuario de la base de datos pueda crear tablas, y reinicia el trabajo.

</details>

<details>

<summary>Los registros no llegan a Discord</summary>

**Causa.** La convar del webhook está vacía, tiene un nombre distinto del `logs.convar` del trabajo o se define después de que el trabajo arranque.

**Solución.** Añade la convar a `server.cfg` encima de la línea `ensure` del trabajo y reinicia el trabajo.

</details>


---

# 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/primeros-pasos/cuxial-jobs.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.