Quest Codex

The Quest Codex Extension provides a customizable GUI system for players to browse, track, and manage Typewriter quests organized by categories. Menus are rendered through the GUI Extension using reusable layout pools, so large quest books can stay compact and publication-friendly.

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

Features

• Hierarchical Categories - Nest categories with parent/child relationships and visibility criteria.
• Layout Pools - Place CATEGORY_SLOT, QUEST_SLOT, SORT_SLOT, and TRACKED_QUEST_SLOT markers in GUI layouts.
• Scrollable Quest Lists - Quest and category slots work inside scrollable, paginated, and frame layouts.
• Dynamic Sort - Cycle through All, Not Started, Active, and Completed with configurable labels and lore.
• Persistent Multi-Tracking - Track several active quests in QuestCodex while the official Quest extension keeps one primary HUD quest.
• Interaction Recovery - Persist the active Typewriter dialogue or cinematic, including the current cinematic frame, and restore it after a reconnect.
• Client-Side Waypoints - Display optimized packet-only HUD and target layers for fixed positions, locatable objectives, tracked objectives, and entities.
• Composable GPS Layers - Combine text, centered block, and rotating beacon-style displays with per-player configuration. The public waypoint system no longer creates item displays or directional arrow layers.
• Tracked Quests Menu - Build a dynamic @tracked menu with occupied and empty slot states.
• Complete Sound Design - Configure menu, click, scroll, track, and untrack sounds.
• BlueMap Integration - Display quest icons on BlueMap with dynamic labels and visibility rules when BlueMap is available.

Architecture

Waypoint displays are resolved from the active Quest Codex target and sent as packet-only text/block display entities. HUD layers use the player's scheduler and camera anchor; target layers use the objective/entity position. No display entity is persisted in the world.

Entry Library

Configuration

• Quest Codex Config - Global sounds, default rows, multi-tracking, persistent artifact reference, and message templates.
• Quest Codex Tracking Data - Persistent storage for each player's tracked quest list.
• Quest Codex Recovery - Recovery checkpoint for active dialogues and cinematics.

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, tracked slots, and sort buttons.
• Quest Lore - Override lore lines per quest and per status.
• Quest Codex Waypoint - Modular client-side GPS with text, block, and beacon layers, configurable icon text, near-target placement, and a visibility cone.

Quick Start

1. Add the global config

Create one quest_codex entry. For durable multi-tracking, create a quest_codex_tracking_artifact entry in a static page and reference it through trackingArtifact.

{
  "type": "quest_codex",
  "id": "my_codex_config",
  "defaultRows": 5,
  "multiTrackingEnabled": true,
  "maxTrackedQuests": 9,
  "trackingArtifact": "questCodexTrackingData",
  "nowTrackingMessage": "<green>Now tracking: {quest}</green>"
}

For dialogue/cinematic recovery, add a quest_codex_recovery_artifact in a static page and set recoveryEnabled, recoveryArtifact, recoveryRetentionSeconds, and recoveryRestoreDelayTicks on the same config. The recovery snapshot is asynchronous, versioned, and automatically expires.

2. Define categories

Add quest_category entries for each logical group:

{
  "type": "quest_category",
  "id": "main_quests_category",
  "category": "main_quests",
  "title": "<gold>Main Quests"
}

3. Assign quests

Use quest_assignment to link native Typewriter quests to a category:

{
  "type": "quest_assignment",
  "id": "assign_main",
  "category": "main_quests",
  "questRefs": ["quest_main_1", "quest_main_2"],
  "orders": [0, 1]
}

4. Design menus

Create an open_gui entry containing the layout pool, then reference it from category_menu.menu. Use these dynamic markers:

Marker	Use
CATEGORY_SLOT	Root category icons.
QUEST_SLOT	Quest buttons inside a category.
SORT_SLOT	Dynamic sort button.
TRACKED_QUEST_SLOT	Currently tracked quests in the @tracked menu.

5. Add a tracked quests menu

Create a category_menu with category: "@tracked" and an open_gui layout containing TRACKED_QUEST_SLOT markers. Open it with /tw codex tracked or a GUI button running codex:tracked.

{
  "type": "category_menu",
  "id": "tracked_quests_menu",
  "category": "@tracked",
  "title": "<gold>Tracked quests",
  "rows": 3,
  "menu": "tracked_quests_gui"
}

Commands

Command	Permission	Description
/tw codex	typewriter.codex.open	Open the main codex menu.
/tw codex tracked	typewriter.codex.open	Open the dynamic tracked quests menu.
/tw codex <category>	typewriter.codex.open	Open a specific quest category.

Waypoint quick start

Track a quest containing a location_objective, then attach a quest_codex_waypoint entry to the same active criteria. The default target can select the highest-priority locatable objective from the tracked quest:

{
  "type": "quest_codex_waypoint",
  "id": "main_quest_waypoint",
  "target": {
    "case": "tracked_objective_waypoint_target",
    "value": { "selection": "HIGHEST_PRIORITY" }
  },
  "layers": [
    {
      "case": "waypoint_text_layer",
      "value": {
        "enabled": true,
        "text": "{icon} <white>{distance_m} m</white> <aqua>{direction}</aqua>",
        "placement": "HUD",
        "offset": { "x": 0.0, "y": 0.0, "z": 0.0 }
      }
    },
    {
      "case": "waypoint_beacon_layer",
      "value": {
        "enabled": true,
        "material": "LIME_STAINED_GLASS",
        "height": 64,
        "viewDistance": 250.0
      }
    }
  ],
  "icon": "<yellow>✦</yellow>",
  "refreshTicks": 1,
  "nearTargetDistance": 10.0,
  "nearTargetVerticalOffset": 2.25,
  "hudVisibilityAngle": 180.0,
  "hudForwardDistance": 5.5,
  "hudVerticalOffset": 1.0
}

Available targets are fixed_waypoint_target, objective_waypoint_target, tracked_objective_waypoint_target, and entity_waypoint_target. Available layers are waypoint_text_layer, waypoint_block_layer, and waypoint_beacon_layer. The icon field accepts text or a resource-pack glyph; insert it in a text layer with {icon}.

Placeholders

QuestCodex exposes category progress placeholders and tracked quest placeholders through the Typewriter placeholder prefix. See Placeholders for the full reference.

Common tracked placeholders:

Placeholder	Returns
%typewriter_codex_tracked_count%	Number of tracked quests.
%typewriter_codex_tracked_limit%	Configured tracking limit.
%typewriter_codex_tracked_primary_name%	Primary quest shown by the official tracker.
%typewriter_codex_tracked_1_name%	First tracked quest display name.
%typewriter_codex_tracked_1_objectives_lines%	First tracked quest objectives, one per line.

Public Example Pages

A complete tested page bundle should include:

Page role	Content
Main manifest page	QuestCodex config, categories, assignments, menus, and GUI menu entries.
Static storage page	quest_codex_tracking_artifact with a generated UUID artifactId.
Quest definitions page	Test/native Typewriter quests used by the example.
GUI settings page	Global OmniGUI settings used by the menus.

When sharing example pages, use random Typewriter page filenames/top-level page ids and keep readable names inside entries. The artifact's artifactId must stay stable once users have data.

Permissions

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

Dependencies

Extension	Required	Usage
Typewriter	Required	Includes the native quest engine.
GUI Extension	Required	Menu rendering and layout pool system.
PlaceholderAPI	Optional	Placeholder resolution for compatible fields and external displays.