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

# Theming

> Recolour every game by editing a file - no build step, no Node, no npm.

Awoken Minigames separates its colours into two layers:

| Layer      | What it controls                                               | Where                             |
| ---------- | -------------------------------------------------------------- | --------------------------------- |
| **Accent** | The one highlight colour - zones, rings, active states.        | The `awoken:primaryColor` convar. |
| **Theme**  | Every surface behind it - panels, tiles, text, borders, grids. | A `.lua` file in `web/themes/`.   |

<Tip>
  The accent wins over the theme's own accent by design, so all your Awoken resources stay in unison. Set `awoken:primaryColor` once in `server.cfg` and Minigames, Chat, UI and the rest all match.

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

## Pick a theme

Set it once for every game in `config.lua`:

```lua config.lua theme={"dark"}
theme = 'midnight',
```

Or per call, which overrides the global for that one game:

```lua theme={"dark"}
exports['awoken_minigames']:SkillCheck({ theme = 'nord' })
```

### Built-in themes

| File                      | Id         | Look                                      |
| ------------------------- | ---------- | ----------------------------------------- |
| `web/themes/dark.lua`     | `dark`     | The default slate look.                   |
| `web/themes/midnight.lua` | `midnight` | Blacked out, near-pure black panels.      |
| `web/themes/nord.lua`     | `nord`     | Cool blue-grey. Also sets its own accent. |

## Make your own

A theme is just a table of colours. There's **no build step** - edit, save, restart.

<Steps>
  <Step title="Copy a built-in">
    Duplicate `web/themes/dark.lua` and rename it, e.g. `web/themes/casino.lua`.
  </Step>

  <Step title="Change the id to match the filename">
    The key in the table is the id you'll use in `config.lua`:

    ```lua web/themes/casino.lua theme={"dark"}
    AwokenThemes = AwokenThemes or {}

    AwokenThemes['casino'] = {
        ['--bg-panel'] = '#161920EB',
        -- ...
    }
    ```
  </Step>

  <Step title="Tweak the colours">
    Keep **all** the keys - the UI expects every one of them. Values are hex:

    * **6-digit** for solid: `#101418`
    * **8-digit** to add transparency: `#RRGGBBAA` - the last pair is opacity (`00` = clear, `FF` = solid)
    * `rgb()` / `rgba()` work too if you prefer
  </Step>

  <Step title="Use it">
    ```lua config.lua theme={"dark"}
    theme = 'casino',
    ```
  </Step>

  <Step title="Restart">
    `restart awoken_minigames`. That's it - the theme is read at runtime and handed to the UI. It shows up automatically in-game and in the dev menu.
  </Step>
</Steps>

<Info>
  Themes live in `web/themes/*.lua`, which asset escrow leaves **open** - they're yours to edit. You never need Node, npm, or a build to recolour anything.
</Info>

## The live theme editor

Rather than editing hex by hand, the [dev menu](/resources/awoken-minigames/configuration/overview#the-dev-menu) has a **Theme** button that opens a live editor: recolour every token and watch the panel change as you type. It edits the real CSS variables, so what you see is exactly what a game gets.

<Steps>
  <Step title="Open it">
    With `enableDevMenu = true`, run `/awoken_minigames` and click **Theme**. (It's also in the browser dev panel - `cd web && npm run dev`.)
  </Step>

  <Step title="Start from an existing theme (optional)">
    Load one of your `web/themes/*.lua` files to tweak from, rather than starting blank.
  </Step>

  <Step title="Recolour">
    Adjust any token; the panel behind the editor updates instantly.
  </Step>

  <Step title="Save it">
    Give it an id and hit **Save**. In-game, that writes `web/themes/<id>.lua` straight into the resource for you. In the browser it downloads the `.lua` instead (CEF has no download manager), which you then drop into `web/themes/`.
  </Step>

  <Step title="Use it">
    Set `theme = '<id>'` in `config.lua` and `restart awoken_minigames`.
  </Step>
</Steps>

<Warning>
  The editor's **Save** writes a file into the resource, so it's gated behind `enableDevMenu`. That's another reason to keep the dev menu **off on a live server**.
</Warning>

## The keys

Each theme file documents every key inline. The main groups:

| Key                | What it paints               |
| ------------------ | ---------------------------- |
| `--bg-panel`       | The main card background.    |
| `--bg-panel-inner` | Inset areas inside the card. |
| `--bg-tile`        | Buttons and tiles.           |
| `--bg-tile-hover`  | Tile hover state.            |
| `--bg-grid`        | Grid / board backdrop.       |
| `--border-subtle`  | Hairline borders.            |
| `--border-strong`  | Emphasised borders.          |
| `--text-primary`   | Headings and key text.       |
| `--text-secondary` | Supporting copy.             |

<Warning>
  Don't delete keys you're not using - the UI reads every one. To make something invisible, set it fully transparent (`#00000000`) rather than removing the line.
</Warning>

## Per-call theming

Because `theme` is a [shared option](/resources/awoken-minigames/configuration/overview#shared-options), you can theme a single job differently without touching the global:

```lua theme={"dark"}
-- A cold, clinical look for the hospital job only
exports['awoken_minigames']:Fingerprint({
    theme    = 'nord',
    brand    = 'Pillbox Medical',
    title    = 'Biometric Lock',
})
```