Skip to main content

Quest Codex

Quest log menus with categories, multi-tracking, GPS waypoints, advancements and BlueMap icons.

Freev2.16Quests & narrative
RequiresTypeWriter0.9QuestGUI0.18+BlueMapoptional
DownloadSource codeSupport

Overview​

Quest Codex gives players a quest book. A main menu lists categories (Main story, Side quests, Dungeons...), each category opens a list of its quests, and clicking an active quest tracks it. The quests themselves are the ones you create with the official TypeWriter Quest extension: Quest Codex only organizes and displays them.

You draw every screen yourself. A menu is a layout of the GUI extension in which you place marker items: a QUEST_SLOT marker is replaced by the player's quests, a CATEGORY_SLOT marker by categories, a SORT_SLOT marker by the sort button. Everything around the markers (borders, titles, buttons, scrolling, pages) is ordinary GUI content.

Beyond the menu, the extension adds multi-quest tracking that survives reconnections, recovery of an interrupted dialogue or cinematic, client-side GPS waypoints and locator bar dots, custom Minecraft advancements granted from a page, and quest icons on BlueMap.

Features​

  • Categories — nested categories with order, icon, visibility and completion criteria, and per-status messages.
  • Quest assignment — put quests in a category, set their order, and override the icon, name, lore and visibility per status.
  • Layout pools — you design each menu with GUI layouts; the codex fills QUEST_SLOT, CATEGORY_SLOT, TRACKED_QUEST_SLOT and SORT_SLOT markers.
  • Sort button — cycles All, Not started, In progress and Completed, with a label, icon and lore per mode.
  • Multi-tracking — track several active quests at once; the last one is the primary quest of the official HUD tracker.
  • Tracked quests menu — a dedicated menu of the quests the player is tracking.
  • Waypoints — packet-only text, block and beacon layers pointing to an objective, a position or an entity, plus a vanilla locator bar variant.
  • Interaction recovery — restores the active dialogue or cinematic after a disconnect.
  • Advancements — define Minecraft advancement tabs in the panel and grant them with an action.
  • BlueMap icons — place a quest icon with a popup on BlueMap.

Installation​

  1. Install TypeWriter on a Paper or Folia server, with its official Quest extension, which defines the quests Quest Codex displays.
  2. Install the GUI extension (version 0.18 or newer).
  3. Optional: install PacketEvents (already required by TypeWriter) for waypoints, and BlueMap for map icons.
  4. Download the Quest Codex JAR from the GitHub releases (the button in the summary panel above), put it in plugins/Typewriter/extensions/ and restart the server.
  5. Give your players the typewriter.codex.open permission, see Permissions below.

Getting started​

Build a quest log with one category:

  1. On a static page, add a Quest Codex Tracking Data entry. This is where tracked quests are saved.
  2. On a manifest page, add a Quest Codex Global Settings entry. Set trackingArtifact to the artifact, and review maxTrackedQuests and the sounds.
  3. Add a Quest Category entry with category main_quests, a title such as <gold>Main Story and an icon.
  4. Add a Quest Assignment entry with category main_quests, and your quests in questRefs. orders is optional.
  5. Create two Open GUI entries used only as containers for layouts. In the first, main_gui, add a simple layout with the id main, set mainLayoutId to main, guiType to CUSTOM and size to SIZE_36. Add an item with buttonPrefix codex_button:, buttonType CATEGORY_SLOT, x 1, y 1, count 7 and direction right. In the second, quests_gui, do the same with the marker QUEST_SLOT, and add a CLOSE item on the bottom row.
  6. Add a Category Menu with an empty category, rows 4 and menu set to main_gui. This is the main menu.
  7. Add a second Category Menu with category main_quests, rows 4 and menu set to quests_gui.
  8. Publish, then run /tw codex in game. Click the category, then click an active quest to track it.
Keep rows and size equal

The inventory is built from the Category Menu rows and not from the size of the Open GUI. If they differ, slots below the smaller height are dropped and the console warns you at startup.

Markers

One marker slot shows one quest. Use count, direction, gap and repeatY to spread a marker over a grid: count 7, direction right and repeatY 3 gives 21 quest slots. Without a direction, the marker stays a single slot. Quests fill the markers in reading order, and the next page of quests is reached with a PAGE_NEXT button.

How it works​

At startup the extension loads the categories, the assignments and the menus. When a player opens a menu, it rewrites each marker of the layout into an indexed marker (QUEST_SLOT#0, QUEST_SLOT#1, ...) before the layout is parsed, so markers behave like ordinary slots inside scrollable, paginated and frame layouts. At render time each marker is replaced by the n-th quest or category.

Which entries make a menu​

A Category Menu is the entry you open. Its menu field points to an Open GUI entry that only provides the layout pool, the main layout, the window type and the sounds. Do not trigger that Open GUI yourself.

category of the Category MenuMenuMarker it must contain
emptyMain menu listing the root categoriesCATEGORY_SLOT
a category nameQuests of that categoryQUEST_SLOT
@trackedQuests the player is trackingTRACKED_QUEST_SLOT

Every defined category needs a Category Menu, otherwise opening it does nothing and the console says so at startup.

Markers and buttons​

Set buttonPrefix to codex_button: and buttonType to one of:

buttonTypeRole
CATEGORY_SLOTA category icon, with its title, progress {completed}/{total}, click hint and status message. Clicking opens the category.
QUEST_SLOTA quest. The icon follows its status, the name and lore come from the quest, the assignment and Quest Lore entries. Clicking an active quest tracks or untracks it.
TRACKED_QUEST_SLOTA tracked quest in the @tracked menu. An empty slot keeps your own item and stays inert, so it is your empty state.
SORT_SLOTThe sort button. Configure each mode in sortDisplay of the Category Menu.
PAGE_NEXT, PAGE_PREVMove to the next or previous page of quests or categories.
SCROLL_UP, SCROLL_DOWN, SCROLL_LEFT, SCROLL_RIGHTScroll the menu.
BACKReturns to the main menu when there is one, else to the mainMenuTrigger entry, else to the previous menu, else closes.
CLOSECloses the menu.
SORTA sort button placed as a plain navigation slot.

Navigation buttons keep the item, name and lore you configure; the built-in arrow, barrier or hopper is used only when the slot has no item.

Put markers in simple layouts that belong to the Open GUI referenced by menu. Markers in other layout types, or in the layouts of a shared chassis, are not indexed and stay hidden.

Chassis, views and tabs​

To build a quest book with tabs, set baseMenuId on the Category Menu to a shared Open GUI shell and add views, defaultViewId and breadcrumbSeparator, exactly as in Views, tabs and inheritance. pushHistoryOnViewSwitch makes Back return to the previous tab. A chassis whose root layout has an _extended variant gets the ten-row canvas automatically.

Quest display​

  • A quest icon defaults to a book, a clock or an emerald for not started, in progress and completed. Override it per status in the Quest Assignment (notStartedItem, inProgressItem, completedItem).
  • notStartedName, inProgressName and completedName replace the quest name, and the matching lore fields add lines. Hide a quest per status with hideWhenNotStarted, hideWhenInProgress and hideWhenCompleted.
  • A Quest Lore entry adds lines per status to a quest, in one category or in all.
  • Quest order follows orders first, then the order of questRefs. A category also lists the quests of its sub-categories.
  • The main menu lists only top-level categories (those without a parent). A sub-category is opened with /tw codex <category> or a button running codex:open <category>.

Configuration​

The Quest Codex Global Settings entry holds the options that are not tied to a menu. Create one only; without it defaults are used.

  • Sounds — soundOnOpen, soundOnSwitch, soundOnClick, soundOnTrack, soundOnUntrack.
  • Tracking — multiTrackingEnabled, maxTrackedQuests (at least 1) and trackingArtifact. Without an artifact, tracked quests are kept in memory only and the console warns at startup. The artifact is a file that must keep its artifactId once players use it.
  • Recovery — recoveryEnabled, recoveryArtifact, recoveryRetentionSeconds (10 to 86400) and recoveryRestoreDelayTicks (1 to 20). When a player leaves during a dialogue or a cinematic, the snapshot is stored and restored shortly after the player rejoins. Without an artifact, recovery is disabled.
  • Messages — nowTrackingMessage, stoppedTrackingMessage, questInactiveMessage, questCompletedMessage, trackingLimitMessage ({quest}, {max}), categoryProgressMessage ({completed}, {total}), and the hints on category and quest lore.
  • Navigation labels — navLabels sets the name of each built-in button (next, previous, up, down, left, right, back, close, sort). It is used only when the tagged slot has no item of its own: a slot that carries an item keeps its own name and lore.
  • Sort button — sortTexts sets the label of each sort mode (allLabel, notStartedLabel, activeLabel, completedLabel) and the hint lore line. A Category Menu that sets a label or lore in its sortDisplay for a mode keeps its own.
  • Menu titles — mainMenuTitle and trackedQuestsTitle are the titles used when the matching Category Menu has an empty title.
  • Command error — unknownCategoryMessage is the error /tw codex <category> shows for a category that does not exist ({category}).
  • Main menu fallback — mainMenuTrigger is triggered when there is no main Category Menu, for example an Open GUI of your own whose buttons run codex:open <category>.

Waypoints and locator bar​

Quest Codex Waypoint is an audience entry: connect it to an audience filter to choose who sees it. Its target is a fixed position, a locatable objective, the tracked objective (selection HIGHEST_PRIORITY, FIRST, CLOSEST, ALL or ONE_PER_QUEST) or an entity. Its layers combine a text layer (placeholders {icon}, {distance}, {distance_m}, {distance_km}, {elevation}, {direction}, {vertical_direction}, {target}, {world_name}, {height_diff} and {eta}), a block layer and a beacon layer. displayMode is HUD_LOCKED (default), WORLD_DIRECTIONAL, TARGET_ANCHORED or ADAPTIVE, and each layer may override it. Everything is sent by packets; no entity is saved in the world.

Quest Codex Locator Bar shows the same targets as dots on the vanilla locator bar, which needs Minecraft 1.21.6 or newer, and pairs with a 3D waypoint.

Advancements and BlueMap​

  • Advancement Definition describes an advancement. One without a parent becomes a tab. They are written at startup into a datapack called questcodex_advancements in the world folder, and the server reloads its data when the content changed, so a new definition needs a restart. The advancement is earned only by the Grant Advancement action.
  • BlueMap Icon places a marker with a label and a popup on the BlueMap maps of its world at startup. In description, <objectives> is replaced by the objectives of the quest.

Commands​

All commands are subcommands of /typewriter, usually typed as /tw, and require typewriter.codex.open.

CommandDescription
/tw codexOpen the main menu: the Category Menu with an empty category, otherwise the mainMenuTrigger entry.
/tw codex trackedOpen the tracked quests menu.
/tw codex <category>Open a category. Tab completion lists the defined categories.

Menu buttons can also run these internal commands: codex:open <category>, codex:tracked, codex:quest <quest_id> and codex:nav <action>. Use codex:open and codex:tracked in the buttons of your own GUI menus.

Permissions​

PermissionGrants
typewriter.codex.openEvery /tw codex command. The extension declares it with an operator-only default and it appears in your permissions plugin: grant it to the groups that may use /tw codex.

Opening a menu from a Category Menu action or a menu button needs no permission.

Placeholders​

PlaceholderAPI placeholders, with the typewriter expansion. They need a player.

PlaceholderReturns
%typewriter_total_quests%Number of quests across all categories.
%typewriter_total_completed%, %typewriter_total_in_progress%, %typewriter_total_not_started%Number of quests in each status for the player.
%typewriter_total_progress%Completed over total, for example 15/42.
%typewriter_category_<name>%Number of quests in the category.
%typewriter_category_<name>_completed%, _in_progress%, _not_started%Quests of the category in that status.
%typewriter_category_<name>_progress%Completed over total for the category.
%typewriter_codex_tracked_count%, _limit%Number of tracked quests, and the maximum.
%typewriter_codex_tracked_multi_enabled%, _has_any%true or false.
%typewriter_codex_tracked_ids%, _names%, _names_lines%Tracked quest ids or names, comma-separated or one per line.
%typewriter_codex_tracked_primary_id%, _primary_name%The primary quest shown by the official tracker.
%typewriter_codex_tracked_has_<quest_id>%Whether that quest is tracked.
%typewriter_codex_tracked_<n>_id%, _name%, _status%, _primary%Details of the n-th tracked quest, from 1. Empty when there is none.
%typewriter_codex_tracked_<n>_objective_count%, _objectives%, _objectives_lines%, _priority%Visible objectives of the n-th tracked quest.

<name> is the category name, matched without regard to case. More detail on Placeholders, Commands and Permissions.

Entries​

12 entries, generated from the extension source.

Actions2
Audiences2
Artifacts2
Manifests6

Troubleshooting​

/tw codex does nothing. There is no Category Menu with an empty category and no mainMenuTrigger. The console logs Main menu could not open with the cause. For a category, create a Category Menu whose category equals the Quest Category category.

A menu opens with nothing in it. The console reports it at startup: no slot of the referenced Open GUI carries the marker the menu needs (CATEGORY_SLOT, QUEST_SLOT or TRACKED_QUEST_SLOT), menu is empty or not an Open GUI, the layout pool is empty, or mainLayoutId is not in it. Markers need buttonPrefix codex_button:.

Slots on the lower rows are missing. The Category Menu rows is smaller than the Open GUI size. Set both to the same number of rows.

Quests appear one slot apart instead of one empty slot between them. gap is a step: 1 is adjacent and 2 leaves one empty slot. Menus written before Quest Codex 0.3.0 used gap as a spacing, so double the value. A collision with a decoration is reported as a Slot overlap warning.

Several markers stack on one cell. The marker has count but no direction, or the position falls outside the grid. Set a direction.

A quest is missing from a category. The quest is hidden by a hideWhen... option for its current status, the current sort mode filters it, or the assignment could not resolve it (Quest '...' could not be resolved in the console).

A tracked quest disappears after a restart. trackingArtifact is empty, or its artifactId changed. A quest that is no longer active is removed from the tracked list.

Waypoints do not show. The waypoint entry must be inside an audience the player matches, the quest must be tracked, and the objective must be locatable. A text layer with {icon} stays empty until icon is set.

A new advancement is unknown to the server. Definitions are written at startup; restart after adding one. A definition whose icon is not an item is skipped with a warning.

  • GUI — layouts, markers, views and the open_gui chassis used by every Quest Codex menu.
  • Shops — uses the same marker mechanism for shop menus.