> For the complete documentation index, see [llms.txt](https://docs.tworst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tworst.com/tw-lib/tw-lib/installation.md).

# Installation

Install tw-lib once; every Tworst job on your server uses the same copy.

***

## Step 1: Download

Download **`tw-lib-<version>.zip`** from [GitHub Releases](https://github.com/Tworst-Shop/tw-lib/releases/latest), or take tw-lib from your Cfx.re **Granted Assets** next to your job.

{% hint style="danger" %}
Do **not** use "Code → Download ZIP" on GitHub. That folder is named `tw-lib-main` and the jobs will not find it.
{% endhint %}

***

## Step 2: Extract

Put the folder into your `resources` directory. It must be named exactly `tw-lib`.

```
resources/
├── tw-lib/              ← Tworst library
│   └── config.lua       # Admin menu language and who may open it
├── tw-scrapyard/        ← your Tworst jobs
└── ...
```

***

## Step 3: server.cfg

Start tw-lib after your framework and oxmysql, and **before** every Tworst job:

```cfg
ensure oxmysql
ensure qb-core           # or qbx_core / es_extended / ... (if any)
# ... your inventory, keys, fuel, clothing, target scripts

ensure tw-lib
ensure tw-scrapyard      # your Tworst jobs
```

{% hint style="info" %}
If a job starts before tw-lib, tw-lib restarts that job once by itself and prints a warning. Fix the order anyway.
{% endhint %}

***

## Step 4: Database

{% hint style="success" %}
**Nothing to import.** tw-lib creates its own tables on the first start:

| Table                 | Holds                           |
| --------------------- | ------------------------------- |
| `tw_lib_settings`     | The job settings you changed    |
| `tw_lib_players`      | Player names for the admin menu |
| `tw_lib_ledger`       | Every payout (money, XP, items) |
| `tw_lib_ledger_daily` | Daily totals for the charts     |
| `tw_lib_job_history`  | Finished jobs                   |
| {% endhint %}         |                                 |

***

## Step 5: Start & Check

Start the server and look at the console:

```
[tw-lib] server loaded
[tw-lib] 1.0.0 | framework=qb | inventory=qb-inventory | keys=qs-vehiclekeys | fuel=LegacyFuel | clothing=qb-clothing
[tw-lib] up to date: tw-lib 1.0.0, tw-scrapyard 3.0.0
```

* The second line shows what tw-lib detected.
* The last line appears a few seconds later. It lists every Tworst script that uses tw-lib. If one has a new version, it says `update available: <script> <yours> -> <new>` with a link instead.

***

## Admin Menu Permission

A player can open `/twlib` in any of three ways, set in `tw-lib/config.lua`:

| Way                 | How                                                                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ACE**             | Grant `tw-lib.admin` in `server.cfg`: `add_ace group.admin tw-lib.admin allow`                                                                          |
| **Framework admin** | QBCore / QBox players with `god` or `admin`, and ESX players in the `admin` or `superadmin` group, are allowed automatically (`frameworkAdmins = true`) |
| **Identifier list** | Add anyone else to `identifiers`, comma separated: `license:...`, `discord:...`, `fivem:...`, `steam:...` or a QBCore citizenid                         |

```lua
Config.Admin = {
    ace = 'tw-lib.admin',
    frameworkAdmins = true,
    identifiers = 'license:1a2b3c4d5e, discord:123456789012345678',
}
```

Restart tw-lib after editing the file. See [Configuration → Config File](/tw-lib/tw-lib/configuration.md#config-file).

***

## Updating

Replace the `tw-lib` folder with the new one and restart the server.

{% hint style="info" %}
Your job settings live in the database, not in the tw-lib folder, so an update never resets them. When tw-lib restarts, the Tworst jobs it had to stop are started again.
{% endhint %}

***

## Troubleshooting

### `Could not find dependency tw-lib for resource ...`

tw-lib is not installed, not started, or its folder is not named `tw-lib`.

### `... needs tw-lib X or newer`

Your tw-lib is older than the job needs. Download the latest from [GitHub](https://github.com/Tworst-Shop/tw-lib/releases/latest) and replace the folder.

### Wrong framework / inventory / keys / fuel / clothing detected

Check that the script is started and that its folder has its original name. Otherwise pick it by hand: see [Configuration → Choosing a Script by Hand](/tw-lib/tw-lib/configuration.md#choosing-a-script-by-hand).

### `database did not answer in 10s`

oxmysql did not respond in time. The jobs start with the values in their config files; your saved settings are not lost. Fix the database, then restart the jobs.

### `settings could not be loaded`

The settings table could not be read. The jobs run with their defaults; your saved settings are not lost. Fix the database and restart.

### `<job>: saved setting ignored (...)`

A value you had saved no longer fits the new version of the job (for example, a setting was removed). The job uses the default for it. Nothing else is affected.

### `/twlib` does nothing

The player is not allowed: no `tw-lib.admin` ace, not a framework admin, and not in the `identifiers` list of `tw-lib/config.lua`. The console prints a line with the player's name when this happens. See [Admin Menu Permission](#admin-menu-permission).

***

## Need Help?

{% hint style="info" %}
Open a ticket on our [Discord](https://discord.gg/tworst) with the `[tw-lib] ...` status line from your console and any red error lines.
{% endhint %}