> 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/configuration.md).

# Configuration

Change the existing settings in your installed resource. Do not paste a second `Config = {}` or replace an entire file with a short example.

## File map

| File                   | Settings                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| `config/main.lua`      | Framework, access, commands, dispatch, paperwork, contracts, progression, perks, and reports      |
| `config/advanced.lua`  | Forklift behavior, recovery, validation, route checks, cargo placement, and strap physics/visuals |
| `config/vehicles.lua`  | Approved trucks, checkout catalog, truck/trailer compatibility, service, and rebuild tasks        |
| `config/locations.lua` | Depot, parking bays, return area, freight sites, shipping contacts, and forklift staging          |
| `config/cargo.lua`     | Freight levels, pay/XP inputs, cargo props, trailer layouts, and securement points                |

The manifest loads main, advanced, vehicles, locations, and cargo in that order, followed by `shared/config_defaults.lua`. The defaults resolver fills omitted settings and preserves explicit choices. Keep that order.

## Current main settings

| Setting                                          | Value          | Meaning                                                         |
| ------------------------------------------------ | -------------- | --------------------------------------------------------------- |
| `Config.Framework`                               | `"standalone"` | No framework economy adapter                                    |
| `Config.PayAccount`                              | `"bank"`       | Account used by a selected framework                            |
| `Config.Access.trucking.mode`                    | `"discordace"` | Requires `hotshot.trucking` permission                          |
| `Config.Access.dot.mode`                         | `"discordace"` | Requires `hotshot.dot` permission                               |
| `Config.Integrations.profileScope`               | `"character"`  | Character saves on frameworks; standalone remains license based |
| `Config.Integrations.vehicleKeys`                | `"none"`       | No Hot-Shot vehicle-key grants                                  |
| `Config.MobileDispatch.keybind`                  | `"F3"`         | Default tablet key mapping                                      |
| `Config.OffersPerRefresh`                        | `5`            | Base board choices before perks                                 |
| `Config.OfferRefreshSeconds`                     | `300`          | Board refresh interval                                          |
| `Config.JobTimeoutMinutes`                       | `45`           | Base contract timeout                                           |
| `Config.Progression.xpPerLevel`                  | `500`          | XP per level                                                    |
| `Config.Progression.maxLevel`                    | `12`           | Level cap                                                       |
| `Config.Paperwork.requireSignatureBeforePickup`  | `true`         | Pickup requires a signature                                     |
| `Config.CargoOperations.securementActionSeconds` | `6`            | Base strap/unstrap duration                                     |
| `Config.CargoOperations.requireUnloading`        | `false`        | Automatic delivery after required strap removal                 |

To use command-only mobile dispatch, set `Config.MobileDispatch.keybind = ""`. Set its `enabled` field to false for yard-only access. Players may have their own saved FiveM key mappings.

## First-job guide settings

```lua
Config.Tutorial = {
    enabled = true,
    autoStart = true,
}
```

These are the release defaults. Set `autoStart = false` for manual activation through dispatch only. Set `enabled = false` to disable the guide and its controls. There is no separate guide command or tutorial command setting.

Guide visibility is saved locally per client/resource, across that client's characters. It does not change contract validation or character progression.

## Move the yard

Set `Config.Depot.coords` in `config/locations.lua`. The current garage menu uses `Config.Garage.coords = Config.Depot.coords`.

Then survey and update:

* `Config.Garage.spawns`: trailer checkout bays.
* `Config.Garage.companyTrucks.spawns`: company-truck bays.
* `Config.Garage.returnArea`: shared return center and radius.

A spawn list supports 1–32 `vector4` entries and takes precedence over a single `spawn`. The current copy has four trailer bays and four truck bays. Checkout tries clear spaces in order. Leave enough room for the longest trailer and its coupling approach.

The current return radius is 35 metres. Moving the depot alone does not reposition every bay or freight site.

## Configure freight sites

In `Config.Pickups` and `Config.Deliveries`, `vector3` values are world X/Y/Z; `vector4` adds heading.

Pickup fields include `coords`, `spawn`, `forkliftSpawn`, and `forkliftCargoOrigin`. An optional `forkliftCargoSpawns` list places individual pieces instead of a row. Supply enough positions for the largest eligible load. A per-site `forkliftWorkRadius` can override the normal work area.

Shipping-contact example:

```lua
shippingContact = {
    model = "a_m_m_farmer_01",
    label = "Farmer",
    coords = vector4(1738.8623, 4696.3359, 43.1833, 90.0),
    interactionDistance = 2.5,
},
```

Replace the coordinates with your surveyed position. Copy standing-player Z unchanged. Contacts must be within 100 metres of the site; interaction distance is 1–4 metres. Keep the contact clear of trucks, cargo, walls, and forklift routes.

Set `shippingContact = false`, or `enabled = false` inside its table, for normal remote manifest signing at that site. Delivery sites can define contacts for backhaul pickups.

## Customize cargo and vehicles

A freight entry defines its unlock level, pay/XP inputs, primary trailer layout, and additional `trailerOptions`. Offsets for props, work points, and straps are model-local, not world positions.

Keep cargo props, securement points, strap references, and trailer compatibility consistent. For the current crate layouts, quantity follows the selected layout's prop count. The 20-foot trailer carries three crates; 30/40-foot layouts carry four.

Omitted cargo/mobile/heavy-haul tow lists inherit `Config.AllowedTowVehicles`. Trailer labels inherit from the garage catalog where possible. An explicit override remains an override.

After changes, restart with no active work and test a fresh contract using every affected trailer. Leave advanced validation and physics settings alone unless you are tuning a specific, reproduced problem.