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

# Building Codex Menus

> How the Quest Codex reuses the GUI Extension layout system — slot placeholders, sort modes, and a complete menu walkthrough

# Building Codex Menus

The Quest Codex draws **zero hardcoded menus**. Every screen a player sees — the category browser, the quest list, the sort button — is a regular [GUI Extension layout pool](/extensions/Typewriter-GUIExtension/guide/introduction) that **you** design. The codex only *injects content* into the slots you mark for it.

If you haven't read the GUI guides yet, start there: [Introduction](/extensions/Typewriter-GUIExtension/guide/introduction) → [Layout Types](/extensions/Typewriter-GUIExtension/guide/layouts) → [Interactions](/extensions/Typewriter-GUIExtension/guide/interactions). Everything on this page builds on those concepts.

## The big picture

```mermaid theme={null}
graph LR
    A["quest_category<br/>(what exists)"] --> B["quest_assignment<br/>(which quests belong where)"]
    B --> C["category_menu<br/>(how it LOOKS — a GUI layout pool)"]
    C --> D["GUI Extension<br/>renders + handles clicks"]
    D --> E["Player browses,<br/>sorts, tracks quests"]
```

Three entry types share the work:

| Entry                                                                                              | Role                                                                 | Analogy                 |
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------- |
| [`quest_category`](/extensions/Typewriter-QuestCodexExtension/entries/manifest/quest_category)     | Declares a category: title, icon, parent, visibility criteria        | The folder              |
| [`quest_assignment`](/extensions/Typewriter-QuestCodexExtension/entries/manifest/quest_assignment) | Links quests into a category, with ordering and per-status overrides | The folder's contents   |
| [`category_menu`](/extensions/Typewriter-QuestCodexExtension/entries/manifest/category_menu)       | The menu design: a full GUI `layoutPool` with placeholder slots      | The folder's appearance |

## Slot placeholders — the one codex-specific concept

Inside a `category_menu` layout pool you place **placeholder slots**. At render time the codex replaces them with live content:

| Placeholder     | Replaced by                                                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CATEGORY_SLOT` | One sub-category icon per visible category (title, icon, click → opens it)                                                                                           |
| `QUEST_SLOT`    | One quest per assignment (icon + per-status lore from [`quest_lore`](/extensions/Typewriter-QuestCodexExtension/entries/manifest/quest_lore), click → track/untrack) |
| `SORT_SLOT`     | The sort-mode button (cycles All → Not Started → Active → Completed)                                                                                                 |

Everything else in the pool — borders, titles, decoration, extra buttons — is plain GUI content and behaves exactly as documented in the [GUI guides](/extensions/Typewriter-GUIExtension/guide/layouts).

## A complete category menu

A 6-row browser: border, scrollable quest area, sort button bottom-right:

```json theme={null}
{
  "type": "category_menu",
  "name": "default_codex_menu",
  "mainLayoutId": "main",
  "layoutPool": [
    { "case": "composite", "value": { "id": "main", "children": ["border", "quests", "controls"] } },

    { "case": "simple", "value": { "id": "border", "items": [
        { "x": 0, "y": 0, "count": 9, "direction": "right",
          "item": { "material": "BLACK_STAINED_GLASS_PANE" }, "displayName": " " },
        { "x": 0, "y": 5, "count": 9, "direction": "right",
          "item": { "material": "BLACK_STAINED_GLASS_PANE" }, "displayName": " " }
    ] } },

    { "case": "scrollable", "value": {
        "id": "quests", "innerId": "quest_grid",
        "virtualWidth": 9, "virtualHeight": 12,
        "buttons": [
          { "direction": "UP",   "step": 1, "item": { "x": 8, "y": 1, "item": { "material": "ARROW" }, "displayName": "<white>▲" } },
          { "direction": "DOWN", "step": 1, "item": { "x": 8, "y": 4, "item": { "material": "ARROW" }, "displayName": "<white>▼" } }
        ] } },

    { "case": "simple", "value": { "id": "quest_grid", "items": [
        { "x": 1, "y": 1, "buttonType": "QUEST_SLOT", "item": {} }
    ] } },

    { "case": "simple", "value": { "id": "controls", "items": [
        { "x": 8, "y": 5, "buttonType": "SORT_SLOT", "item": {} }
    ] } }
  ]
}
```

What to notice:

* The **structure is 100 % GUI Extension**: `composite` stacking, a `scrollable` viewport, repetition fields for the border.
* Placeholder slots are ordinary items tagged with `buttonType` — the codex fills them and multiplies `QUEST_SLOT`/`CATEGORY_SLOT` across the available area.
* Scrolling, clicks and sounds are handled by the GUI engine; the codex only decides *what* goes in each slot.

## The sort button

`SORT_SLOT` renders the current sort mode and cycles on click. Each mode can have its own label, lore and item via the menu's `sortDisplay` configuration — see [category\_menu](/extensions/Typewriter-QuestCodexExtension/entries/manifest/category_menu). Modes: **All → Not Started → Active → Completed**.

## Per-status quest appearance

A quest slot adapts to the player's progress. [`quest_lore`](/extensions/Typewriter-QuestCodexExtension/entries/manifest/quest_lore) defines the lore blocks per status (not started / active / completed), and [`quest_assignment`](/extensions/Typewriter-QuestCodexExtension/entries/manifest/quest_assignment) can override icon or visibility per status. Clicking an active quest tracks/untracks it through QuestExtension's native tracker.

## Checklist for a working codex

1. A [`quest_codex_config`](/extensions/Typewriter-QuestCodexExtension/entries/manifest/quest_codex_config) entry (global sounds, defaults, messages).
2. At least one `quest_category` (top level = no parent).
3. One `quest_assignment` per category, listing quest entries.
4. A `category_menu` whose layout pool contains at least one `QUEST_SLOT` (and `CATEGORY_SLOT` if you use sub-categories).
5. Open it via the [commands](/extensions/Typewriter-QuestCodexExtension/commands) or a Typewriter trigger.

<Tip>
  Design tip: build and test your layout as a plain `open_gui` menu first (fast iteration with the [GUI cookbook](/extensions/Typewriter-GUIExtension/guide/cookbook) recipes), then transplant the pool into your `category_menu` and swap the content slots for placeholders.
</Tip>