Skip to main content

Codex

Discovery codex with unlockable categories, recipe books and collectible fragments.

Privatev0.0.3Quests & narrative
RequiresTypeWriter0.9BasicGUIQuestoptionalQuest Codexoptional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview​

Codex is a discovery log. You define categories (a bestiary, a lore book, a list of places) and the items inside them, and each item or category unlocks by TypeWriter criteria: a fact, a quest status, a permission, anything a criteria can check. Locked entries stay visible with their own lore, so players see what is left to discover. You can also add recipe categories, which show a vanilla crafting recipe in a small crafting-table view when the player clicks a recipe.

The extension also contains a fragment system: collectible items that players pick up, grouped into sets, with a sequence that fires once enough fragments are gathered. Everything is a TypeWriter entry, built in the web panel, and the menus are rendered by the GUI extension.

The extension runs on the BTC build of TypeWriter (BTC Core, Paper/Folia) and is documented here for reference.

Features​

  • Discovery categories — group items, with nested sub-categories through parentCategory.
  • Criteria-based unlocking — categories and items unlock from criteria; locked ones can show their own item and lore.
  • Completion counters — unlocked, locked, total and percent are available in category icons and as placeholders.
  • Recipe books — show the ingredients and result of a vanilla recipe from its recipeKey.
  • Unlock triggers — fire triggers the first time a category, item or recipe unlocks for a player, saved so they never fire twice.
  • Four menu layouts — PAGINATED, SCROLLABLE, FRAME or SIMPLE for each category.
  • Global codex menu — a GUI layout where category icons are placed by markers, inheriting a shared menu chassis.
  • Collectible fragments — pick up an item to collect a fragment, with a trigger when a group is completed.
  • Open command and action — open a category from a command, a dialogue or any trigger.

Installation​

  1. Install the GUI extension (GuiAndDialogs in the BTC build) and TypeWriter's Basic extension. Codex will not load without them.
  2. Optionally install the Quest extension and the Quest Codex extension if you want to unlock entries from quest progress.
  3. Put the Codex JAR in plugins/Typewriter/extensions/ and restart the server.
  4. Add a Codex Unlock artifact if you use unlock triggers, and a Fragment Storage artifact if you use fragments.

Getting started​

Build a "Forest creatures" category with two items:

  1. In the TypeWriter web panel, open a manifest page and add a Discovery Codex Category entry.
  2. Set category to a unique identifier such as forest_creatures, a title, rows (for example 3) and an icon.
  3. Set itemSlotRange to the slots to fill, for example 10-16 (the numbers start at 1), and choose guiLayout.
  4. In items, add an item: entryId wolf, an item shown when unlocked, a lockedItem shown before, and in criteria the fact that means "the player has seen a wolf". Add unlockedLore and lockedLore.
  5. Add a static or sequence page entry with an Open Discovery Codex action, set definition to your category, and trigger it from an NPC, an item or a dialogue option. You can also use /tw codex open forest_creatures.
  6. Publish and open the codex. Items whose criteria are not met stay locked.
Items without criteria

An item with an empty criteria list is always unlocked. Add criteria to every item you want to hide.

How it works​

A category shows either its sub-categories and recipe categories (when other categories name it as parentCategory) or its own items. Category criteria and item criteria are evaluated each time the menu is built for the player.

Each Discovery Codex Category is its own inventory menu with rows rows (1 to 6). Items go in the slots of itemSlotRange (for example 1-25, counted from 1), or from startSlot filling by row or by column. The buttons have defaults: previous page in slot 0, next page in slot 8, info in slot 4 and back in slot 44. They use arrows and a book by default and can be replaced with previousButton, nextButton, infoButton and backButton. The back button only appears when the category was opened from a parent. A background item fills every free slot.

The guiLayout field chooses how items are arranged when they do not fit on one page: PAGINATED (page buttons), SCROLLABLE (scroll buttons), FRAME (one frame per row) or SIMPLE (everything on one screen).

The name and lore of a category icon (iconName, iconLore, lockedIconLore) can use {unlocked}, {locked}, {total} and {percent}, which are replaced when the icon is shown in a parent category or in the global menu. The other lore fields (items, info and navigation buttons) are shown as written, even if their help text lists placeholders.

A leaf item whose entryId matches an entryId of a Recipe Category opens the recipe view when clicked. The recipe view shows the crafting grid in craftingGridSlots and the result in resultSlot; a recipe that is not registered on the server shows a barrier item named "Recipe not found".

The Codex Global Menu action opens a hub built from a GUI layout pool. Place codex_button:CODEX_CATEGORY markers (with count, gap and direction to repeat them) and each marker is filled with one top-level category, sorted by order. A category without a matching marker is not shown, and a marker without a category stays empty. CODEX_BACK goes back, and CODEX_INFO, CODEX_PAGE_NEXT and CODEX_PAGE_PREV are plain decorative items in this version.

CODEX_RECIPE markers show recipes: the Nth marker, in order of appearance in the layout (as for CODEX_CATEGORY), shows the icon of the Nth recipe. The recipes of all Recipe Categories are put in one flat list, with the categories sorted by order and the recipes in the order of their list. Clicking an unlocked recipe opens its detail view. With more recipes than markers, the extra recipes are not shown; with more markers than recipes, the extra markers stay empty.

Marker spacing

In count markers, gap is a step, not a spacing: 1 places the slots side by side and 2 leaves one empty slot between them. The Codex uses the shared GUI formula. This is the same rule that applies to Quest Codex markers since Quest Codex 0.3.0, so a layout copied from an older Quest Codex menu may need its gap doubled. See the GUI extension for the layout reference.

The category menus themselves can open inside a shared chassis when baseMenuId is set (use rows of 3 or fewer so they fit the content area). The UiCore extension can also display the codex: its Codex screen sorts top-level categories into four tabs (Bestiary, Items, Places and Fragments) by looking for keywords such as fragment, place, region, item or recipe in the category identifier and name, and puts everything else in the Bestiary.

Configuration​

The extension has no configuration file. State is kept in two artifacts, both saved a few seconds after a change and when TypeWriter unloads:

  • Codex Unlock remembers which unlock triggers have already fired for each player.
  • Fragment Storage remembers the fragments each player has collected, per group.

Commands​

CommandDescription
/tw codex open <category> [targets]Opens the category with that category identifier for yourself or the selected players. Alias: /tw dcx open.

The command has no permission check of its own beyond the access to the TypeWriter command. A category whose criteria are not met answers "This codex is locked" and an unknown identifier answers "Unknown category".

The extension also registers an internal /codexmenu command used by menu clicks (category, recipecat, recipe). It works only for players and is not meant to be typed by hand.

Placeholders​

These are MiniPlaceholders tags of the discoverycodex expansion, available in any MiniMessage text that supports placeholders. Replace cat with the category identifier and item with the item's entryId. Identifiers may contain underscores.

PlaceholderReturns
<discoverycodex_category_unlocked:cat>Number of unlocked items in the category for the player.
<discoverycodex_category_total:cat>Number of items in the category.
<discoverycodex_category_locked:cat>Number of locked items for the player.
<discoverycodex_category_percent:cat>Percentage of unlocked items, from 0 to 100.
<discoverycodex_category_name:cat>The name of the category entry.
<discoverycodex_item_unlocked:item>true or false for that item.

Entries​

10 entries, generated from the extension source.

Actions2
Artifacts2
Manifests6

Troubleshooting​

The extension does not load. Codex requires the Basic and GUI (GuiAndDialogs) extensions. Check the TypeWriter startup log for the missing dependency.

Unlock triggers never fire. The log says "No CodexUnlockArtifactEntry configured: skipping unlock triggers". Add one Codex Unlock artifact to a published page. Without it the triggers are skipped on purpose, so that rewards are not given again after each restart.

Unlock triggers fired once and never again. That is intended: each trigger fires once per player, and the record is stored in the artifact. To test again, use a new player or remove their data from the artifact.

The items land in the wrong slots or the last slot is empty. itemSlotRange counts from 1 (1-25 means slots 0 to 24 of the inventory). Slots outside the menu size are ignored, and items beyond the number of slots go to the next page.

A recipe shows "Recipe not found". recipeKey must be the namespaced key of a recipe registered on the server, such as minecraft:iron_pickaxe. Recipes added by other plugins use their own namespace.

A fragment is not collected. The player must pick up the item: it must match customItem (or displayItem when customItem is empty), and the log must not say "No FragmentArtifactEntry found". Add a Fragment Storage artifact. A fragment already collected is not consumed again.

The group never completes. requiredCount defaults to 0, meaning every fragment listed in fragments; a number above the list length is capped to the list length. The group's groupId must be the same text as the fragmentGroup of its fragments.

Markers in a global menu are one slot apart. gap is a step, so use gap 2 to leave one empty slot between markers.

  • GUI — menu engine, layouts and markers.
  • Quest Codex — quest menus; Codex is an optional companion.
  • UiCore — can render the codex in its own interface.