> ## 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

> Every option in config.lua explained.

All configuration lives in `config.lua` at the root of the `awoken_loadingscreen` resource.

Restart the resource after any change to apply it: `ensure awoken_loadingscreen` (or `restart awoken_loadingscreen` from your console if it's already running).

<Tip>
  Anywhere there are alternatives (backgrounds, socials, music tracks) the file lists them all with only one uncommented. To swap variants, flip which line is commented - remove the `--` from the one you want, add `--` to the one you just had.
</Tip>

## Branding

The top-left logo, hero title, tagline, subtitle, and per-player welcome message.

```lua theme={"dark"}
branding = {
    logoImageUrl    = './media/logo.png',  -- '' to hide
    logoImageHeight = 44,

    serverName = 'AWOKEN',                  -- big hero text
    tagline    = 'Labs',                    -- italic script overlay, '' to hide
    subtitle   = 'Premium FiveM scripts and resources.',  -- '' to hide

    -- {name} is replaced with the connecting player's name.
    welcomeTemplate = 'Welcome, {name}!',   -- '' to hide welcome line
}
```

<Info>
  The player's name comes from the server's `playerConnecting` handler and is substituted into `{name}` automatically. No extra setup needed.
</Info>

## Theme

Every accent colour in the UI (glows, gradients, progress bar, hex icons, hover states) is derived from `accent` + `accentSoft`.

```lua theme={"dark"}
theme = {
    accent     = '#00E5FF',
    accentSoft = '#62ECFF',
    background = '#060a10',
    text       = '#ffffff',
    muted      = '#a0b0b8',
}
```

### Global Awoken colour

Set the accent globally for all Awoken resources via `server.cfg`. This convar overrides `theme.accent` and automatically derives a lighter shade for `accentSoft`.

```cfg server.cfg theme={"dark"}
setr awoken:primaryColor "#00E5FF"
```

Leave the convar unset (or empty) to use the colours in `config.lua`. The convar is read once at resource start, so changing it requires `ensure awoken_loadingscreen` to take effect.

## Fonts

Every piece of text on the screen is driven by **three font "roles"**. Set each role to any font-family name and that typeface is used everywhere that role applies - no need to touch the code.

| Role      | Drives                                                             |
| --------- | ------------------------------------------------------------------ |
| `display` | Hero title, progress %, headings, keycaps (bold display text)      |
| `body`    | Subtitle, descriptions, tips, rules, release notes (readable copy) |
| `script`  | The italic accent word overlaying the hero (decorative)            |

A role's value can point at a **custom font** you register, a **Google font**, one of the three always-available built-ins (`Inter`, `Bebas Neue`, `Dancing Script`), or any system font (`Arial`, `Georgia`, ...). The whole `fonts` block is optional - omit it and the defaults below are used.

```lua theme={"dark"}
fonts = {
    custom = {
        -- self-hosted fonts (see below)
    },
    google = {
        -- extra Google families, e.g. 'Oswald:400,700'
    },
    roles = {
        display = 'Bebas Neue',
        body    = 'Inter',
        script  = 'Dancing Script',
    },
}
```

### Custom (non-Google) fonts

Any font that isn't on Google Fonts - a brand font, a purchase from a foundry, or something from a site like dafont.com - is **self-hosted**: the file ships inside the resource, so it loads instantly and never depends on an external service. This is the most reliable option inside FiveM's browser.

<Steps>
  <Step title="Add the font file">
    Drop the font file into `web/build/media/fonts/`. Supported formats: `.woff2` (smallest, recommended), `.woff`, `.ttf`, `.otf`.

    <Tip>
      If you only have a `.ttf` or `.otf` (e.g. straight from dafont.com), convert it to `.woff2` at a tool like [transfonter.org](https://transfonter.org) for a much smaller file. The `.ttf`/`.otf` will still work as-is if you'd rather skip this.
    </Tip>
  </Step>

  <Step title="Register it">
    Add an entry to `fonts.custom`. The `family` is the name you'll use to select it.

    ```lua theme={"dark"}
    fonts = {
        custom = {
            { family = 'Hemi Head', url = './media/fonts/hemi-head.woff2' },
        },
        roles = {
            display = 'Hemi Head',   -- now drives the hero title, %, headings
            body    = 'Inter',
            script  = 'Dancing Script',
        },
    }
    ```
  </Step>

  <Step title="Restart">
    `ensure awoken_loadingscreen`. The next player to connect sees the new font.
  </Step>
</Steps>

**Multiple weights** of one typeface - add several entries with the same `family` and different files + `weight`:

```lua theme={"dark"}
custom = {
    { family = 'Hemi Head', url = './media/fonts/hemi-head.woff2',      weight = 400 },
    { family = 'Hemi Head', url = './media/fonts/hemi-head-bold.woff2', weight = 700 },
}
```

### Google fonts

List extra Google families in `fonts.google`, then reference them in `roles`. Append `:weights` to load specific weights.

```lua theme={"dark"}
fonts = {
    google = { 'Oswald:400,700', 'Roboto' },
    roles = {
        display = 'Oswald',
        body    = 'Roboto',
        script  = 'Dancing Script',
    },
}
```

<Warning>
  **Licensing.** Make sure you have the right to use any font you ship - especially on a commercial server. Many dafont.com fonts are licensed **"free for personal use" only**; using them commercially requires buying the appropriate licence from the foundry. The resource provides the mechanism; sourcing a properly licensed font file is up to you.
</Warning>

## Background

Pick **one** of six variants. Keep the others commented out.

<Tabs>
  <Tab title="Video">
    Most reliable option. Works regardless of network or YouTube embed restrictions.

    ```lua theme={"dark"}
    background = { kind = 'video', url = './media/bg.mp4' }
    ```

    MP4 / WebM. Drop the file in `web/build/media/`.
  </Tab>

  <Tab title="Image">
    ```lua theme={"dark"}
    background = { kind = 'image', url = './media/bg.jpg' }
    ```

    JPG / PNG / WebP.
  </Tab>

  <Tab title="Carousel">
    Crossfades through a list of images.

    ```lua theme={"dark"}
    background = {
        kind = 'carousel',
        images = {
            './media/bg-1.jpg',
            './media/bg-2.jpg',
            './media/bg-3.jpg',
        },
        intervalMs = 8000,   -- how long each image is shown
        fadeMs     = 1500,   -- length of the crossfade
        shuffle    = false,  -- true = random order
    }
    ```
  </Tab>

  <Tab title="Gradient">
    ```lua theme={"dark"}
    background = {
        kind  = 'gradient',
        from  = '#061218',
        to    = '#010408',
        angle = 135,
    }
    ```
  </Tab>

  <Tab title="Solid">
    ```lua theme={"dark"}
    background = { kind = 'solid', color = '#060a10' }
    ```
  </Tab>

  <Tab title="YouTube">
    ```lua theme={"dark"}
    background = {
        kind     = 'youtube',
        videoId  = 'dQw4w9WgXcQ',
        useAudio = false,
    }
    ```

    `videoId` is the part after `v=` in a YouTube URL:

    | URL                                           | videoId       |
    | --------------------------------------------- | ------------- |
    | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` | `dQw4w9WgXcQ` |
    | `https://youtu.be/dQw4w9WgXcQ`                | `dQw4w9WgXcQ` |
    | `https://www.youtube.com/shorts/dQw4w9WgXcQ`  | `dQw4w9WgXcQ` |

    `useAudio = true` unmutes the video and uses its soundtrack as the loading-screen music; `music.playlist` is ignored. `useAudio = false` keeps the video muted so `music.playlist` can play.

    <Warning>
      Only videos with embedding enabled by the uploader will play. If the video shows "Video unavailable" inside the loading screen, host a copy as MP4 in `media/` and use `kind = 'video'` instead.
    </Warning>
  </Tab>
</Tabs>

## Overlay

Darkens (or tints) the background so foreground text stays readable. Raise opacity for busier videos / images, lower it for clean gradients.

```lua theme={"dark"}
overlay = {
    color    = '#000000',
    opacity  = 0.35,
    vignette = true,
}
```

## Music

Background music playlist. Players press **Space** to pause/play, **arrow keys** to skip, and can drag the **volume slider** in the top-right (their volume saves in their browser).

```lua theme={"dark"}
music = {
    enabled  = true,
    autoplay = true,
    volume   = 0.35,   -- initial volume (0.0 - 1.0), each player can override
    shuffle  = false,

    playlist = {
        { title = 'Track One', artist = 'Artist Name', url = './media/track-1.mp3' },
        { title = 'Track Two', artist = 'Artist Name', url = './media/track-2.mp3' },
    },
}
```

<Info>
  The top-right audio visualiser is live - it reacts to the actual audio waveform when a track is playing.
</Info>

<Tip>
  MP3 is safest, but OGG, WAV, and M4A also work. Leave `playlist` empty for silence. If the YouTube background has `useAudio = true`, this playlist is ignored.
</Tip>

## Socials

Bottom row of social links. Built-in icons are recognised by `platform` name:

```
discord, tiktok, youtube, twitter, twitch, instagram,
facebook, github, reddit, telegram, patreon, email, store, website
```

```lua theme={"dark"}
socials = {
    { platform = 'discord', url = 'https://discord.gg/awokenlabs' },
    { platform = 'website', url = 'https://awokenlabs.com' },
    { platform = 'store',   url = 'https://awokenlabs.com' },
}
```

For anything not in the built-in list (Kick, Steam, a custom forum, ...) supply your own icon:

```lua theme={"dark"}
{
    platform = 'kick',
    url      = 'https://kick.com/mychannel',
    iconUrl  = './media/kick-icon.svg',
    label    = 'Kick',
}
```

* `iconUrl` takes precedence over any built-in icon.
* An unknown `platform` with no `iconUrl` falls back to a generic link icon.
* `label` overrides the tooltip (defaults to the platform name).

## Status tips

Rotating one-liners shown under the loading bar.

```lua theme={"dark"}
status = {
    tipIntervalMs = 7000,

    tips = {
        'Welcome to Awoken Labs - premium FiveM resources and tooling.',
        'Press Space to pause the music, arrow keys to skip tracks.',
        'Need help? Join our Discord for fast support.',
    },
}
```

## Progress bar

Toggle the visual elements of the loading bar.

```lua theme={"dark"}
progress = {
    showPercent = true,   -- percent text
    showStatus  = true,   -- FiveM status string (e.g. "Loading map")
    showPulse   = true,   -- pulsing dot beside the percent
    glow        = true,   -- accent-coloured glow
}
```

## Info panels

A column of hexagon trigger buttons sits at the right edge of the screen. Clicking one opens a centered modal with that panel's content; **Esc**, the **X** button, or **click-outside** closes it.

Three `kind`s are available. Leave the `panels` array empty to hide the column entirely.

### Common fields

| Field   | Description                                                                   |
| ------- | ----------------------------------------------------------------------------- |
| `id`    | Unique internal id (used as React key + open-state tracker).                  |
| `label` | Short text shown to the left of the hexagon (1-2 words).                      |
| `icon`  | One of: `book`, `shield`, `info`, `news`, `keyboard`. Defaults vary per kind. |
| `title` | Heading shown inside the modal. Defaults to `label`.                          |
| `intro` | Optional paragraph shown below the title.                                     |

### `sections` - heading + bullet list

Best for Rules, Support, FAQ, etc.

```lua theme={"dark"}
{
    kind   = 'sections',
    id     = 'rules',
    label  = 'Rules',
    icon   = 'shield',
    title  = 'Server Rules',
    intro  = 'Read carefully before connecting.',
    footer = 'Last updated: 2026-04-28',
    sections = {
        {
            heading = '1. Roleplay',
            items = {
                'Stay in character at all times in IC channels.',
                'No metagaming or powergaming.',
                'Treat new players with patience.',
            },
        },
        {
            heading = '2. Conduct',
            items = {
                'No hate speech, harassment, or discrimination.',
                'Cheats and modded clients are an instant ban.',
            },
        },
    },
}
```

### `releases` - dated changelog

Scrolls when long. Newest at the top.

```lua theme={"dark"}
{
    kind  = 'releases',
    id    = 'updates',
    label = 'Updates',
    icon  = 'news',
    title = 'Release Notes',
    intro = "What's changed recently. Newest at the top.",
    releases = {
        {
            date = '2026-04-28',
            name = 'v1.4.0 - Spring Update',
            items = {
                'New tuner shop in Mirror Park with 30+ visual upgrade kits.',
                'Reduced respawn time after death from 12s to 8s.',
                'Fixed inventory desync when swapping vehicles mid-job.',
            },
        },
        {
            date = '2026-03-15',
            name = 'v1.3.0',
            items = {
                'Added new vehicle: 2024 Drift Tampa.',
                'New radio station: Awoken FM.',
            },
        },
    },
}
```

### `controls` - clickable keyboard

Renders a US-layout keyboard with the bound keys highlighted. Selecting a key shows its label + description below.

```lua theme={"dark"}
{
    kind  = 'controls',
    id    = 'controls',
    label = 'Controls',
    icon  = 'keyboard',
    title = 'Keybinds',
    intro = 'Hover or click a highlighted key to see what it does.',
    bindings = {
        { key = 'F',     label = 'Interact',  description = 'Interact with NPCs, doors, ATMs, and world objects.' },
        { key = 'TAB',   label = 'Inventory', description = 'Open your inventory and equip items.' },
        { key = 'SHIFT', label = 'Sprint',    description = 'Hold to sprint on foot, boost in vehicles.' },
        { key = 'SPACE', label = 'Jump',      description = 'Jump on foot, handbrake in vehicles.' },
    },
}
```

Recognised `key` values (case-insensitive):

| Group      | Keys                                                      |
| ---------- | --------------------------------------------------------- |
| Letters    | `A` - `Z`                                                 |
| Numbers    | `0` - `9`                                                 |
| Function   | `F1` - `F12`                                              |
| Modifiers  | `SHIFT`, `CTRL`, `ALT`, `WIN`, `MENU`                     |
| Navigation | `UP`, `DOWN`, `LEFT`, `RIGHT`                             |
| Other      | `ESC`, `TAB`, `CAPS`, `ENTER`, `SPACE`, `BACKSPACE`       |
| Symbols    | `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/` |

<Tip>
  `SHIFT`, `CTRL`, and `ALT` match both the left and right keys on the keyboard.
</Tip>