Category GUI

The category-entry codex is EmakiCodex's second codex model and is independent from the vanilla advancement pages in advancements/*.yml. Players open it with /codex codex (or /codex open); the layout comes from gui/codex_gui.yml and the content from codex/*.yml.

The full category field tables live in Configuration. This page covers layout, interaction, and placeholders.

Opening and permissions

Item	Value
Commands	/codex codex, /codex open
Permission	emakicodex.use, or bypassed by emakicodex.admin
Restrictions	Players only; the GUI does not open when no valid category is loaded
Template id	codex_gui; opening fails with a warning when the template is missing

The four entry states

State	Meaning	Available action
Locked	No unlock path has been satisfied	None; hidden: true entries are not shown at all
Unlocked	Unlocked but not activated	Left click to activate
Activated	rewards.attributes is contributing	Right click to claim the one-time reward
Claimed	The one-time reward has been granted	None (attribute rewards keep applying)

Activation and claiming are separate operations: activation only enables attribute rewards, and claiming only runs rewards.actions once. Attribute values are not stored; they are derived from the current codex/*.yml, so changing the configuration also changes already activated players.

Slot types

Functional slots must declare an explicit type. A slot without type is purely decorative.

type	Purpose
entry	Entry slot. All entry slots together form one page; out-of-range slots render as air. Left click activates, right click claims.
category_tab	Category tab. Filled by ascending category order; out-of-range slots render as air. Clicking switches category and resets to page 1.
page_prev	Previous page. Does nothing on the first page.
page_info	Page information. The page number can only live here, never in the GUI title.
page_next	Next page. Does nothing on the last page.
close	Closes the GUI.

The default template uses 10-16,19-25,28-34 for entries, which is 21 entry slots per page. Page size is derived from the number of entry slots you actually place, so changing the layout changes the page size.

Placeholders

Available in entry slots:

Placeholder	Meaning
%entry_title%	Entry title; replaced with the unknown-entry text while locked
%entry_description%	Entry description; empty while locked
%entry_state%	One of the four state labels
%entry_hint%	Hint for the currently available action
%entry_rewards%	Reward list, expanded to multiple lines (only when the line contains just this placeholder)
%codex_category%	Category id
%codex_entry%	Entry id

Category tabs can use %category_id%, %category_title%, and %category_state%. Page-info slots can use %current_page%, %total_pages%, %entry_count%, and %category_title%.

Default layout excerpt

id: "codex_gui"
gui_type: CHEST
title: "<gradient:#D946EF:#F59E0B>Codex</gradient>"
rows: 6

slots:
  category_tab:
    type: "category_tab"
    slots: "0-8"
    item:
      components:
        custom_name: "%category_title%"
        lore:
          - "<gray>Category: <white>%category_id%</white></gray>"
          - "%category_state%"

  entry:
    type: "entry"
    slots: "10-16,19-25,28-34"
    item:
      components:
        custom_name: "%entry_title%"
        lore:
          - "%entry_description%"
          - "<gray>State: %entry_state%</gray>"
          - "%entry_rewards%"
          - "%entry_hint%"

  page_info:
    type: "page_info"
    slots: [49]
    item:
      source: "book"
      components:
        custom_name: "<gray>Page %current_page%/%total_pages%</gray>"

Locked entries render with a locked icon and the unknown-entry title, so there is no need to configure a separate slot for unknown entries.

Related Pages

• Configuration: the category and entry fields of codex/*.yml.
• Triggers: the events and conditions usable in unlock.triggers.
• Commands and Permissions: opening the GUI, admin unlock, and admin reset.
• Advancements: the separate vanilla advancement model.