> For the complete documentation index, see [llms.txt](https://dirkscripts.gitbook.io/dirkscripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dirkscripts.gitbook.io/dirkscripts-documentation/resources/dirk-lib/getting-started.md).

# Getting Started

## 🚀 Quick Start

Ensure `dirk_lib` is started **after** your framework, inventory, and targeting resources. There is **no `.cfg` file to edit** — `dirk_lib` auto-detects supported resources and exposes everything else through its in-game configurator.

```properties
# Example start order
ensure qb-core
ensure ox_inventory
ensure ox_target

ensure dirk_lib
```

That's it. No convars, no setup file — start the server and configure live in-game.

***

## ⚙️ Configuring `dirk_lib` In-Game

`dirk_lib` is configured entirely through its **in-game Live Script Configurator**. Settings save to the `dirk_scriptConfig` database table and apply **live** — no resource restart, no SQL edits.

{% hint style="success" %}
**Opening the configurator**

You have two options, both registered by `dirk_lib` itself:

* **`/dirk_lib`** — opens the configurator straight to the dirk\_lib config.
* **`/dirk_config`** — opens the chooser listing every dirk-powered script on the server (dirk\_lib, dirk\_fishing, etc.) and lets you pick which one to edit.

By default, only players with the `admin` ACE permission can access either command. The exact permission is controlled by a convar (see below).
{% endhint %}

### 🔐 Access Control

Two layers control who can edit which scriptConfigs:

* **Master ACE permission (convar):** the floor — anyone matching this permission can edit *any* registered scriptConfig (including `dirk_lib` itself).
* **Per-resource overrides (Script Config tab):** purely additive grants for non-master ACE groups or specific player identifiers, set per-resource.

```properties
# server.cfg — defaults to "group.admin,admin,command" if unset
setr dirk_lib_master_group "group.admin,admin,command"
```

The convar accepts a **comma-separated list** of values. Each is passed to `IsPlayerAceAllowed` in turn — if **any one of them** allows the player, they're treated as master. The default covers the three permissions most server.cfgs grant to admins, so it works out of the box on stock txAdmin / QB / QBX / ESX setups without configuration.

The convar is the **escape hatch**: even if a per-resource override save goes wrong, the master still works because it's read from `server.cfg` before scriptConfig loads. Editing the master from inside the panel would defeat that, so it's intentionally convar-only.

Common values you can put in the list:

* `group.admin` — principal membership (works when the cfg has `add_ace group.admin group.admin allow`).
* `admin` — bare permission (works when the cfg has `add_ace group.admin admin allow`).
* `command` — built-in admin permission (default in most txAdmin and framework cfgs).
* `mod`, `command.dirk_config`, etc. — any custom permission your cfg grants.

If your server only allows mods (not admins) to edit, replace the default with your own list:

```properties
setr dirk_lib_master_group "group.mod"
```

For per-resource grants beyond the master, see the **Script Config** tab inside `/dirk_lib`.

The configurator has seven sections.

***

### 🎨 Appearance

Global UI theme used by every dirk\_lib-powered NUI. Pick a Mantine palette key (e.g. `blue`, `grape`, `teal`) or use the built-in `dirk` palette and customise the **10-stop colour palette** directly. The shade index (0 lightest → 9 darkest) controls which colour is picked as the primary accent for buttons, borders and highlights.

***

### 🏷️ Branding

* **Server Name** — string shown across NUIs that surface a server name.
* **Logo** — URL or `nui://` path to your server logo, displayed in dirk\_lib menus.
* **Item Image Path** — defaults to `auto` (resolves from your detected inventory), or override with a full `nui://` / CDN URL.

***

### 🌐 Localization

* **Language** — locale code (e.g. `en`, `es`, `fr`, `de`, `pt`, `nl`). This is the global language for **every dirk\_lib-consuming resource** — switching it here changes the locale used by `dirk_fishing`, your custom scripts, and anything else that calls `lib.locale()`.
* **Currency** — symbol prefixed to money values rendered by dirk\_lib UIs.

{% hint style="info" %}
Each resource ships its own `locales/*.json` files. Switching the language here picks the matching file from every consumer resource simultaneously — no per-resource configuration needed.
{% endhint %}

***

### 🔌 Bridging

This is where `dirk_lib` decides which third-party resources to talk to. **Every resource bridge defaults to `auto`** so you don't normally need to touch anything — install the resources and `dirk_lib` will detect them.

| Bridge         | Used For                                          |
| -------------- | ------------------------------------------------- |
| Framework      | Player data, identifiers, jobs/groups             |
| Inventory      | Item lookups, give/remove, image paths            |
| Target         | Entity interactions                               |
| Interact       | Prompt-based interactions (alternative to target) |
| Time / Weather | Sky and clock sync                                |
| Keys           | Vehicle keys / lockpicking                        |
| Fuel           | Vehicle fuel                                      |
| Phone          | Messages, mail, etc.                              |
| Garage         | Vehicle storage                                   |
| Clothing       | Character appearance                              |
| Ambulance      | Death + revive                                    |
| Prison         | Jail system                                       |
| Dispatch       | Police alerts                                     |
| Doorlock       | Door systems                                      |
| Skills         | Progression systems                               |
| Housing        | Player housing                                    |

#### UI Providers

`dirk_lib` ships its own UI components but **defaults every UI provider to `ox_lib`** — servers running `ox_lib` get its native UIs out of the box without configuration. Switch any of these to `dirk_lib` to use the built-in NUI instead.

| Provider        | Controls                                 |
| --------------- | ---------------------------------------- |
| **notify**      | `lib.notify` toast notifications         |
| **progress**    | `lib.progressBar` / `lib.progressCircle` |
| **showTextUI**  | `lib.showTextUI` / `hideTextUI`          |
| **contextMenu** | `lib.registerContext` / `showContext`    |
| **alertDialog** | `lib.alertDialog` confirm modals         |
| **inputDialog** | `lib.inputDialog` form prompts           |

***

### 👥 Groups

Defaults for the dirk\_groups system: max members, max invite distance, invite-valid time, log-off kick time.

***

### 🛡️ Script Config

Per-resource access overrides for `/dirk_config`. The master ACE permission (set via the [`dirk_lib_master_group` convar](#access-control)) is shown read-only at the top — that's the floor.

Below it, add per-resource overrides:

* **Resource** — pick one of the registered scriptConfig resources from the dropdown.
* **ACE Groups** — extra permission strings checked via `IsPlayerAceAllowed`. Anything FiveM ACE recognises works (`group.mod`, `dirkscripts.command.druglabs`, custom permissions). Press **Enter** to add a tag.
* **Player Identifiers** — specific players granted access regardless of group membership. The dropdown shows currently online players; you can also paste a known identifier directly (`license:`, `steam:`, `discord:`, etc.) for offline grants.

Each row's grants are **additive** — they only *add* edit access for that resource. They cannot remove access from the master, and `dirk_lib` itself is master-only by design (so a non-master can never grant themselves master-tier access via the panel).

***

### 🔧 Advanced

Manual JSON edit, history / audit log, reset-to-defaults — same controls as every other dirk configurator.

***

## Developers

To use `dirk_lib` in your own resource, include the shared script in your `fxmanifest.lua`:

```lua
shared_scripts {
  '@dirk_lib/init.lua'
}
```

You can pre-load specific modules (modules also dynamically import on use):

```lua
dirk_libs {
  'math',
  'objects'
}
```

***

## Supported Resources

`dirk_lib` supports two kinds of integration:

* **Bridge systems** — resources with dedicated bridge implementations under `dirk_lib/bridge/*`
* **Autodetected integrations** — resources detected from `src/autodetect.lua`. Both can be auto-selected or forced via the **Bridging** section in the configurator.

### Bridge Systems

| System                | Supported Resources                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Framework             | `es_extended`, `pork_core`, `qb-core`, `qbx_core`                                                                                                                             |
| Inventory             | `codem-inventory`, `dirk_inventory`, `ox_inventory`, `qb-inventory`, `qs-inventory`, `tgiann_inventory`                                                                       |
| Target                | `ox_target`, `qb-target`, `qtarget`                                                                                                                                           |
| Interact              | `interact`, `sleepless_interact`                                                                                                                                              |
| Time / Weather        | `av_weather`, `cd_easytime`, `qb-weathersync`, `Renewed-Weathersync`, `vSync`                                                                                                 |
| Keys                  | `cd_garage`, `MrNewbVehicleKeys`, `okokGarage`, `qb-vehiclekeys`, `qbx_vehiclekeys`, `qs-vehiclekeys`, `Renewed-Vehiclekeys`, `t1ger_keys`, `vehicles_keys`, `wasabi_carlock` |
| Fuel                  | `cdn-fuel`, `LegacyFuel`, `okokGasStation`, `ox_fuel`, `ps-fuel`, `Renewed-Fuel`, `ti_fuel`, `x-fuel`                                                                         |
| Clothing / Appearance | `dirk_charCreator`, `esx_skin`, `illenium-appearance`, `qb-clothing`, `rcore_clothing`, `tgiann-clothing`                                                                     |

### Other Autodetected Integrations

| System                | Autodetect Targets                                                                                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Framework             | `es_extended`, `qbx_core`, `qb-core`, `nd-framework`, `pork_core`                                                                                                                            |
| Inventory             | `dirk_inventory`, `ox_inventory`, `qb-inventory`, `qs-inventory`, `codem-inventory`, `tgiann_inventory`, `mf-inventory`, `core_inventory`                                                    |
| Target                | `ox_target`, `qb-target`, `q-target`, `bt-target`                                                                                                                                            |
| Interact              | `redm-uiprompt`, `sleepless_interact`, `interact`                                                                                                                                            |
| Time / Weather        | `av_weather`, `cd_easytime`, `qb-weathersync`, `Renewed-Weathersync`, `vSync`, `wasabi_wheather`                                                                                             |
| Keys                  | `cd_garage`, `MrNewbVehicleKeys`, `t1ger_keys`, `okokGarage`, `qb-vehiclekeys`, `qbx_vehiclekeys`, `qs-vehiclekeys`, `Renewed-Vehiclekeys`, `vehicles_keys`, `wasabi_carlock`, `ludaro-keys` |
| Fuel                  | `cdn-fuel`, `LegacyFuel`, `ox_fuel`, `ps-fuel`, `Renewed-Fuel`, `ti_fuel`, `x-fuel`, `wasabi_fuel`, `okokGasStation`                                                                         |
| Phone                 | `lb-phone`, `qb-phone`, `gksphone`, `high-phone`, `npwd`                                                                                                                                     |
| Garage                | `qb-garages`, `wasabi_garage`, `renewed-garage`                                                                                                                                              |
| Clothing / Appearance | `esx_skin`, `qb-clothing`, `rcore_clothing`, `illenium-appearance`, `fivem-appearance`, `dirk_charCreator`, `tgiann_clothing`                                                                |
| Ambulance             | `qb-ambulancejob`, `wasabi_ambulance`, `core_ambulance`                                                                                                                                      |
| Prison                | `qb-prison`, `rcore_prison`, `wasabi_jail`                                                                                                                                                   |
| Dispatch              | `bub_mdt`, `cd_dispatch`, `linden_outlawalert`, `qs_dispatch`, `ps-dispatch`, `tk_dispatch`                                                                                                  |
| Skills                | `sd_skills`, `evolent_skills`, `core_skills`, `B1-skillz`, `skill_system_v1.5`, `skillsystem_v3`, `boii_skills`, `skillsystem_v2`, `ot_skill_system`                                         |
| Housing               | `qs-housing`, `bcs_housing`                                                                                                                                                                  |

{% hint style="warning" %}
This list reflects the current `dirk_lib` source. If you're forcing an override, use a resource name that matches the current source for your version.
{% endhint %}