> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Branding, colours, the van and who sees the app. Everything else is edited in game.

Most of this resource is not configured in files. Pay, routes, levels, training, loot, depots and doorsteps are all changed in game, with no restart. See [In-game setup](/resources/awoken-courier/in-game-setup).

The files under `config/` hold what has to be known before the database is read: branding, colours and who can see the app. Restart the resource after changing them.

Which framework, inventory, target, keys and dispatch you run is not set here either. [Awoken Bridge](/resources/awoken-bridge/configuration) answers that for every Awoken script at once.

## General

```lua config/core.lua theme={"dark"}
Config.Locale = 'en'
Config.Debug  = false
Config.updateNotifications = true   -- the startup banner and update check
```

<Warning>
  Leave `Config.Debug` off on a live server. It makes ox\_target draw a wireframe around every zone this script owns, which is the first thing players ask about.
</Warning>

## Branding

```lua config/core.lua theme={"dark"}
Config.App = {
    name           = 'GoPostal',
    icon           = 'https://cfx-nui-awoken_courier/web/dist/logo.png',
    iconBackground = '#FFFFFF',
    inAppLogo      = 'https://cfx-nui-awoken_courier/web/dist/app-logo.png',
}
```

* **`name`** is what the app is called on the tablet's home screen.
* **`icon`** is the home screen tile. Use an image link, or the name of a [Lucide](https://lucide.dev/icons) icon such as `'truck'`.
* **`iconBackground`** is the colour behind the icon.
* **`inAppLogo`** is the logo shown inside the app.

## Who sees the app

By default everyone does. Turn on a gate to restrict it. Turn on more than one and a player has to pass all of them.

```lua config/core.lua theme={"dark"}
Config.Visibility = {
    itemGate     = { enabled = false, mode = 'item', item = 'courier_usb', count = 1 },
    jobGate      = { enabled = false, job  = 'courier',  grade = 0 },
    gangGate     = { enabled = false, gang = 'couriers', grade = 0 },
    aceGate      = { enabled = false, ace  = 'courier.access' },
    callbackGate = { enabled = false, resource = 'my_script', name = 'canUseCourier' },
}
```

| Gate | The player must |
| - | - |
| `itemGate` | Have the item. See `mode` below. |
| `jobGate` | Have the job. `grade = 0` is any rank. |
| `gangGate` | Be in the gang. |
| `aceGate` | Have the ace permission. For staff only apps. |
| `callbackGate` | Pass your own rule. The tablet calls `exports[resource][name](src)` and shows the app if it returns `true`. |

`itemGate.mode` decides what "have" means:

* **`'item'`** checks their pockets. They carry it.
* **`'sdcard'`** means the item has to be installed inside their tablet. That needs the tablet's [SD card system](/resources/awoken-tablet/sd-cards). On a server with SD cards turned off it quietly behaves as `'item'`, so picking it is safe either way.

If you turn on `itemGate`, register the item first. See [Installation](/resources/awoken-courier/installation#the-optional-item).

## The van

```lua config/core.lua theme={"dark"}
Config.DepotVehicles = {
    { model = 'boxville2', colors = { primary = 111, secondary = 64 } },
}
```

One is picked at random per shift, and the list is shared by every depot. Add more lines for variety. Each entry can also take `extras` and `livery`.

<Note>
  `boxville2` is the GoPostal van, and its logos are part of its paint. Repainting a branded van wipes them off, so leave `colors` out if you want the stock look.
</Note>

## Map blips

```lua config/core.lua theme={"dark"}
Config.Blips = {
    pickup  = { sprite = 478, color = 27, scale = 0.9 },
    dropoff = { sprite = 478, color = 0,  scale = 1.0 },
}
```

These are the route markers a driver sees on shift. The depot's own blip is set on the depot itself, in the admin panel.

## Notifications

```lua config/core.lua theme={"dark"}
Config.Notifications = {
    position    = 'top',
    durationSec = 4,
}
```

`position` takes any of: `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `center-left`, `center-right`.

## Who answers the door

```lua config/core.lua theme={"dark"}
Config.PorchDelivery = {
    homeownerPeds = {
        'a_m_y_genstreet_01',
        'a_f_y_business_02',
        -- ...
    },
}
```

When a driver hands a parcel over instead of leaving it, one of these residents answers, picked at random.

## Admin access

```lua config/core.lua theme={"dark"}
Config.Creator = {
    ace     = 'awoken_courier.creator',
    aceOnly = false,
}
```

Anyone with the ace can open the admin panel and the creator. So can your normal admin groups, so most servers need no extra line. Set `aceOnly = true` to require the ace and nothing else.

## Colours

The app's palette is in `config/theme.lua`. Every value is a hex colour, `'#RRGGBB'`, or `'#RRGGBBAA'` where the last two digits are how solid it is.

```lua config/theme.lua theme={"dark"}
Config.Theme = {
    primary = '#1FC6FF',  -- buttons, the side menu, accent stripes
    success = '#50DC82',  -- money, completed deliveries
    warning = '#FFC663',  -- anything in progress
    danger  = '#D43F2A',  -- delete buttons, warnings
    gold    = '#FFD15E',  -- premium routes, and 1st on the leaderboard
    silver  = '#C0C8D6',  -- 2nd place
    bronze  = '#CD7F32',  -- 3rd place

    surfaceBase   = '#0B1018',  -- behind everything
    surfaceRaised = '#161B27',  -- the panels on top
    -- ...
}
```

Two smaller tables sit at the bottom of the file:

* **`categoryAccents`** gives each Training category its own colour.
* **`routeTints`** makes one route card stand out. Most routes should not be listed.

<Note>
  Going light on the surface colours means darkening the three text colours to match, or nothing will be readable.
</Note>

## Language

Every line of text is in `config/locales/en.lua`, including everything the app shows, under the `web` table.

* **To reword something**, edit the value in place.
* **To translate**, copy the file, change `Config.Locales.en` to your language such as `Config.Locales.fr`, translate the values, add the file to `shared_scripts` in `fxmanifest.lua`, and set `Config.Locale = 'fr'`.

Text in the `web` table uses `{name}` style placeholders. Keep them exactly as they are.

## Files you can ignore

* **`config/depot.lua`** is read once, on the first start, to create the starting depot. Editing it afterwards does nothing. Depots are edited in the admin panel.
* **`config/neighbourhoods/`** is empty on purpose. Areas and doorsteps live in the database.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.