Quest Codex

The Quest Codex Extension provides a fully customizable GUI system for players to browse, track, and manage quests organized by hierarchical categories. Every menu is built through declarative layout pools powered by the GUI Extension — no hardcoded menus, infinite customization.

• Source Code — View source on GitHub.
  • Download Releases — Get the latest JARs.

Features

• Hierarchical Categories — Nest categories with parent/child relationships. Sub-categories inherit visibility from their parent.
  • Layout Pools — Design every menu through declarative layout pools. Placeholders (SORT_SLOT, CATEGORY_SLOT, QUEST_SLOT) are automatically injected.
  • Scrollable Quest Lists — Quest and category slots follow scrollable, paginated and frame viewports — build scrolling quest grids of any size (since 0.3.0).
  • Dynamic Sort — Cycle through All → Not Started → Active → Completed with per-mode button display (label, lore, custom item).
  • Quest Tracking — Track active quests with priority indicators via QuestExtension's native tracking system.
  • Complete Sound Design — Configure sounds for menu open, click, scroll, and quest track/untrack events.
  • BlueMap Integration — Display quest icons on BlueMap with dynamic labels and visibility rules (BTC version).

Architecture

Entry Library

Configuration

• Quest Codex Config — Global sounds, default rows, and message templates.

Category System

• Quest Category — Define a category with title, icon, parent, and visibility criteria.
  • Quest Assignment — Link quest entries to a category with ordering and per-status overrides.

Menu & Display

• Category Menu — Design menus with declarative layout pools, placeholder slots, and per-mode sort buttons.
  • Quest Lore — Override lore lines per quest and per status.

Quick Start

• 1. Add Global Config (Optional) — Create a Quest Codex Config entry in a page JSON to customize sounds and messages. The extension works out of the box without this — it uses sensible defaults. json { "type": "quest_codex", "id": "my_codex_config", "defaultRows": 5, "nowTrackingMessage": "<green>Now tracking: {quest}</green>" } Place this in any compiled page under plugins/Typewriter/pages/. → Quest Codex Config

• 2. Define Categories — Add a Quest Category entry. This defines a logical group of quests in the codex with its display title, icon, and optional parent for nesting. Key fields: - category — Unique internal name (e.g., main_quests) - title — Display title shown to players (MiniMessage) - icon — Item shown in parent/category list - parent — Leave empty for top-level, or set to nest → Quest Category

• 3. Assign Quests — Add a Quest Assignment entry to link your QuestExtension quests to a category. Control ordering and per-status overrides. json { "type": "quest_assignment", "id": "assign_main", "category": "main_quests", "questRefs": ["quest:quest_main_1", "quest:quest_main_2"], "orders": [0, 1] } → Quest Assignment

• 4. Design Menus — Add a Category Menu entry for each category you want a custom GUI for. Use the layout pool to place: - CATEGORY_SLOT — Auto-injected category icons (main menu) - QUEST_SLOT — Auto-injected quest buttons (category menu) - SORT_SLOT — Auto-injected dynamic sort button - Standard GUI items — Decorative items, fills, static buttons The layout pool uses the CUSTOM guiType. Everything is positional: place items at (x, y) coordinates. → Category Menu

• 5. Open the Menu — Access the codex via command: /tw codex → main codex menu (since 0.3.0) /tw codex <category> → a specific category Examples: - /tw codex main_quests — Opens the main quests category - /tw codex daily_tasks — Opens daily tasks > Main menu: either create a category_menu entry with an empty category and CATEGORY_SLOT markers, or build the hub as a GUI Extension open_gui menu whose buttons run codex:open <category> and reference it in the config's mainMenuTrigger — /tw codex and the codex BACK button will then open it.

Commands

Command	Permission	Description
/tw codex	typewriter.codex.open	Open the main codex menu (empty-category category_menu, or the config's mainMenuTrigger).
/tw codex <category>	typewriter.codex.open	Open a specific quest category directly. Tab-completion available.

Placeholders

Prefix: %typewriter_*%

Global Placeholders

Placeholder	Returns	Example
%typewriter_total_quests%	Total quest count across all categories	42
%typewriter_total_completed%	Total completed quests	15
%typewriter_total_in_progress%	Total in-progress quests	5
%typewriter_total_not_started%	Total not-started quests	22
%typewriter_total_progress%	Completed/Total formatted	15/42

Per-Category Placeholders

Replace <name> with the category identifier (e.g., main_quests).

Placeholder	Returns	Example
%typewriter_category_<name>%	Total quests in category	10
%typewriter_category_<name>_completed%	Completed in category	3
%typewriter_category_<name>_in_progress%	In progress in category	2
%typewriter_category_<name>_not_started%	Not started in category	5
%typewriter_category_<name>_progress%	Progress formatted	3/10

Aliases: _inprogress% and _notstarted% also work.

Template Variables (in @Placeholder fields)

Variable	Context	Replaced With
{quest}	Message templates	The quest's display name
{completed}	Progress messages	Number of completed quests
{total}	Progress messages	Total quests in the category

Permissions

Permission	Description
typewriter.codex.open	Open the quest codex.

Dependencies

Extension	Required	Usage
QuestExtension	Required	Core quest engine.
GUI Extension	Required	Menu rendering and layout pool system.
PlaceholderAPI	Optional	For @Placeholder fields.