> For the complete documentation index, see [llms.txt](https://baobab-interactive.gitbook.io/baobab-interactive-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://baobab-interactive.gitbook.io/baobab-interactive-docs/hotshot-trucking-simulator/frameworks-and-access.md).

# Frameworks and Access

## Select the framework

Set `Config.Framework` in `config/main.lua`.

| Value          | Adapter                                              |
| -------------- | ---------------------------------------------------- |
| `"standalone"` | Internal progression and earnings records            |
| `"esx"`        | `es_extended`                                        |
| `"qb"`         | `qb-core`                                            |
| `"qbox"`       | Native `qbx_core` exports                            |
| `"auto"`       | Detect Qbox, then QB, then ESX; otherwise standalone |

The current copy explicitly selects standalone. `qbcore` is an alias for `qb`; `qbx` is an alias for `qbox`. Hot-Shot does not install a framework or create framework jobs.

Framework payments use `Config.PayAccount`; `cash` and `money` map to the adapter's cash account. Other account names must exist in your framework.

{% hint style="warning" %}
A delivery marked **PAYMENT NOT CONFIRMED** needs operator review of the framework balance and logs. Hot-Shot does not automatically retry an uncertain deposit: a framework export may fail after crediting money. Career earnings record the earned settlement, not a bank reconciliation.
{% endhint %}

## Trucking and inspector permissions

`Config.Access.trucking` and `Config.Access.dot` are independent and apply on every server type.

| Mode                 | Grants access when                                      |
| -------------------- | ------------------------------------------------------- |
| `open`               | Player/character is loaded                              |
| `discordace`         | The configured permission is granted through ACE        |
| `job`                | Active framework job meets minimum grade and duty rules |
| `discordace_or_job`  | Permission or eligible job                              |
| `discordace_and_job` | Permission and eligible job                             |
| `auto`               | ACE on standalone; eligible job on frameworks           |

The release uses `discordace` for both activities. Trucking requires `hotshot.trucking`; inspections require `hotshot.dot`. Set these names in each rule's `permission` field. An unrelated framework administrator role does not grant these permissions automatically.

### Example: public trucking, ACE-restricted inspectors

This is an optional policy change, not the current configuration:

```lua
Config.Access = {
    trucking = { mode = "open", permission = "hotshot.trucking", jobs = {}, requireDuty = false },
    dot = { mode = "discordace", permission = "hotshot.dot", jobs = {}, requireDuty = true }
}
```

Grant the inspector ACE to an existing group with appropriate membership:

```cfg
add_ace group.dot hotshot.dot allow
```

An ACE grant alone does not put a player into that group. Configure membership through your server's normal principals or DiscordAcePerms role mappings. DiscordAcePerms is optional; Hot-Shot uses normal ACE checks and requires no Discord bot token in its config.

### Example: framework job access

Replace the job names and grades with your server's real definitions:

```lua
Config.Access = {
    trucking = { mode = "job", permission = "hotshot.trucking", jobs = { trucker = 0 }, requireDuty = false },
    dot = { mode = "job", permission = "hotshot.dot", jobs = { police = 2 }, requireDuty = true }
}
```

Grades are inclusive minimums. Empty job maps deny job-based access. Only the active primary job counts, not gangs or secondary jobs. Duty checks apply to the job route. If your ESX player object does not expose usable duty information, a required-duty check denies access.

When upgrading an older configuration, replace `ace`, `either`, and `both` modes with `discordace`, `discordace_or_job`, and `discordace_and_job`; rename the rule's `ace` field to `permission`. Remove `Config.Integrations.access` and define `Config.Access` explicitly. This release rejects the old access block and mode names.

Losing trucking access prevents new work. Players can still cancel work and use the physical yard's return-only view to return assigned equipment, subject to normal return checks.

## Framework compatibility

Version 1.33.1 fixed QB/ESX player lookup when FiveM supplies a callable function reference. Version 1.33.2 includes that fix, prefers QB's direct player export where available, and clears cached fallback lookups after errors or framework restarts. Offline or unloaded players remain ineligible.

Install the complete release if an older build cannot recognize a loaded QB/ESX character. This lookup fix does not require changing payout or progression settings.

## Character saves

`Config.Integrations.profileScope = "character"` separates records by framework character. Standalone uses a license-based identity regardless of that setting.

{% hint style="warning" %}
Changing framework or switching between character and license scope does not migrate old data. Keep identity choices stable on an established server.
{% endhint %}

## Optional vehicle keys

| `Config.Integrations.vehicleKeys` | Behavior                                                    |
| --------------------------------- | ----------------------------------------------------------- |
| `"none"`                          | Current value; Hot-Shot does not manage keys                |
| `"auto"`                          | On Qbox, use an available `qbx_vehiclekeys` provider        |
| `"qbox"`                          | Require Qbox and its key provider for equipment preparation |

The adapter grants keys for registered company trucks and assigned forklifts. It does not grant keys for trailers or personal vehicles, or create framework vehicle ownership. Other ESX/QB key systems need their own integration.

{% hint style="info" %}
A Ready notification does not bypass an external engine/key resource. Include actual engine operation in your installation test.
{% endhint %}