> 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/getting-started/cuxial-jobs.md).

# Cuxial Jobs

The shared library behind the Cuxial team jobs: crews, runs, payouts and progress.

Cuxial Jobs is the common library used by the Cuxial team jobs: Cuxial Diving, Cuxial Electrician and Cuxial Gardener. It gives all of them the same crews, runs, payouts and player progress, so every job behaves the same way and is configured the same way.

It is included in the package of each of those jobs. You install it once, and all the jobs you own share it.

{% hint style="info" %}
It is a library: it has no commands, interface or configuration file of its own. Each job loads it and uses it with its own settings.
{% endhint %}

## What it adds to each job

| Part        | What the job gets                                                                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Job point   | An NPC with a blip and a target option that opens the job menu.                                                                                     |
| Crews       | Invitations to nearby players, a maximum crew size, a saved seat for members who disconnect during a run, and a reward split set by the crew owner. |
| Runs        | Regions to work in, optionally one crew per region at a time, an optional wait between runs, and the final delivery.                                |
| Payout      | Money paid to the account you choose, several ways to share it among the crew, and optional item rewards.                                           |
| Progress    | Level and experience per job, daily tasks, run history and a leaderboard.                                                                           |
| Work outfit | Optional work clothes for the run, with the player's own outfit restored afterwards.                                                                |
| Guidance    | First-time tips and an end-of-run summary.                                                                                                          |
| Staff tools | Commands to list and close crews, an audit log and Discord logs through a webhook.                                                                  |

Progress is kept per job: a player's level as a diver is separate from their level as an electrician.

## Installation

{% stepper %}
{% step %}

## Check the dependencies

Cuxial Jobs needs nothing by itself. The jobs that use it need:

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

Cuxial Diving and Cuxial Gardener also need their assets resource, `cuxial_diving_assets` and `cuxial_gardener_assets`, delivered with each script.
{% endstep %}

{% step %}

## Copy the resource

Place the `cuxial_jobs` folder in your `resources` directory. One copy serves every job. If two packages bring different versions, keep the newest.

{% hint style="danger" %}
Keep the folder name `cuxial_jobs`. Every job loads it by that exact name and will fail to start if you rename it.
{% endhint %}
{% endstep %}

{% step %}

## Start it before the jobs

Add it below Cuxial Bridge and above every job.

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

```cfg
ensure ox_lib
ensure oxmysql
# your framework and inventory here
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 %}

Only list the jobs you own.
{% endstep %}

{% step %}

## Check the server console

On start, the library prints its version:

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

No SQL to run. The first job that starts creates the shared tables.
{% endstep %}
{% endstepper %}

## Configuration

Cuxial Jobs has no configuration file and no convars of its own. Everything it does is set in each job, in that job's `shared/config.lua` and `data` folder, so two jobs can use different values.

These blocks appear in every job and are read by the library:

| Block in the job's `shared/config.lua` | What it controls                                                          |
| -------------------------------------- | ------------------------------------------------------------------------- |
| `debug`                                | Debug messages in the console.                                            |
| `ui`                                   | Accent colour of the job menu and money format.                           |
| `logs`                                 | Name of the convar that holds the Discord webhook.                        |
| `admin`                                | Days the audit log is kept.                                               |
| `account`                              | Account that receives the money.                                          |
| `job`                                  | Who can do the job: `'all'`, one framework job or a list of them.         |
| `npc`                                  | Position, model, distances and blip of the job NPC.                       |
| `crew`                                 | Crew size, invitation distance and time, reconnection time, reward split. |
| `run`                                  | Wait between runs and whether a region allows one crew at a time.         |
| `reward`                               | How the payout is shared and which items are given.                       |
| `outfit`                               | Work outfit mode.                                                         |
| `leaderboard`, `history`, `profile`    | Size of the leaderboard and the history, and how often progress is saved. |
| `commands`                             | Names of the job commands and who can use them.                           |
| `keys`                                 | Default keys.                                                             |
| `tips`, `finish`                       | Seconds the tips and the final summary stay on screen.                    |

Levels, daily tasks, regions and outfits are in the job's `data` folder: `levels.lua`, `daily.lua`, `regions.lua` and `outfits.lua`.

The page of each job explains its own values and the options that only that job has.

### Convars per job

Each job reads two optional convars. Their names start with the job's folder name, shown here as `<resource>`.

| Convar               | Used for                                                          | Set with |
| -------------------- | ----------------------------------------------------------------- | -------- |
| `<resource>_debug`   | `1` turns on debug messages without editing the config.           | `setr`   |
| `<resource>_webhook` | Discord webhook for that job's logs. Empty means no Discord logs. | `set`    |

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

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

{% endcode %}

{% hint style="warning" %}
The webhook goes in `server.cfg`, never in `shared/config.lua`. It is read once when the job starts, so place the line above the job's `ensure`. The name of the webhook convar can be changed in the job's `logs.convar`.
{% endhint %}

### Commands per job

Each job registers its own commands. Their names are set in the job's `commands` block, and setting a `name` to `false` removes that command.

| Entry   | Who      | What it does                                            |
| ------- | -------- | ------------------------------------------------------- |
| `reset` | Everyone | Resets the player's current run.                        |
| `leave` | Everyone | Leaves the crew. The owner cannot leave during a run.   |
| `list`  | Staff    | Lists the open crews with their size, region and phase. |
| `close` | Staff    | Closes a crew by its number.                            |
| `fast`  | Staff    | Testing shortcut. Works only with `debug` enabled.      |

The staff entries are limited by their `restricted` value, `'group.admin'` by default.

## Database

The jobs share four tables, created automatically when the first job starts:

| Table                     | What it stores                                                |
| ------------------------- | ------------------------------------------------------------- |
| `cuxial_jobs_players`     | Level, experience and daily tasks of each character, per job. |
| `cuxial_jobs_runs`        | Finished runs.                                                |
| `cuxial_jobs_run_members` | Who took part in each run and what they earned.               |
| `cuxial_jobs_audit`       | Audit log of staff actions.                                   |

Removing a job does not delete its rows.

## Updates

A job and the library are made to work together. Each job states which library version it expects, and the library warns in the server console when they do not match:

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

When you update a job, replace the `cuxial_jobs` folder with the one from the same package and restart the server. See [Updating a script](/scripts/getting-started/updating.md).

## Common problems

<details>

<summary>A job fails to start with an error mentioning cuxial_jobs</summary>

**Cause.** The library is missing, was renamed, or starts after the job.

**Fix.** Confirm the folder is named `cuxial_jobs` and that `ensure cuxial_jobs` appears before the job.

</details>

<details>

<summary>The console says a job asks for another library version</summary>

**Cause.** The job and `cuxial_jobs` come from different releases.

**Fix.** Replace `cuxial_jobs` with the copy that came in the newest package you have, and update the other jobs to the same release.

</details>

<details>

<summary>The console warns about items that do not exist in the inventory</summary>

The warning reads `items que no existen en el inventario:` followed by the item names.

**Cause.** The job gives items as a reward and one of them is not registered in your inventory.

**Fix.** Add the items to your inventory, or remove them from the job's `reward.items`.

</details>

<details>

<summary>Progress is not saved</summary>

**Cause.** The shared tables could not be created. The server console shows a failed query from the job.

**Fix.** Check the `oxmysql` connection and that the database user can create tables, then restart the job.

</details>

<details>

<summary>Logs do not reach Discord</summary>

**Cause.** The webhook convar is empty, has a different name from the job's `logs.convar`, or is set after the job starts.

**Fix.** Add the convar to `server.cfg` above the job's `ensure` line and restart the job.

</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/getting-started/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.