EmakiCodex

EmakiCodex is driven by a small set of configuration files, and a couple of commands run right after installation verify that it works

EmakiCodex ships with two independent codex models, so tell them apart first. The first is advancements/*.yml, which defines and registers vanilla advancement pages and nodes; advancements are Minecraft's built-in progress system. The second is codex/*.yml, which defines categories, entries, unlock conditions, and rewards for a separate category-entry GUI

The two models can be linked through advancement unlocks, but page_id and category_id are not interchangeable

With PacketEvents (a dependency plugin that handles packet I/O) installed, EmakiCodex enables two extra capabilities: injecting node coordinates into the client advancement tree, and re-pushing the registered tree (sending the advancement data again) to online players

Without PacketEvents everything still works: vanilla advancements register normally, but node placement is handled by the vanilla client parent tree and online players may need to reconnect after a reload to see the updated tree

The category-entry GUI does not require PacketEvents; its action rewards still run through CoreLib, while attribute rewards are derived from the current configuration

Basic information

Item	Value
Runtime/POM version	1.1.6
API Jar	emaki-codex-api-1.1.5.jar
Default config structure version	1.1.6
Main class	emaki.jiuwu.craft.codex.EmakiCodexPlugin
Main command	/codex
Alias	/ecodex
Required dependency	EmakiCoreLib
Optional dependencies	EmakiAttribute, PlaceholderAPI, PacketEvents, MythicMobs
Minimum server	Paper 26.1+ (api-version: 26.1, folia-supported: true)
Java	Java 25
Main permissions	emakicodex.use (default true), emakicodex.reload (op), emakicodex.debug (op), emakicodex.admin (op)

The runtime module and default config.yml version is 1.1.6, while the API artifact is 1.1.5. The internal AppConfig.CURRENT_VERSION = "1.0.14" is a configuration-migration structure constant, not a plugin release version or API coordinate

Pages

Page	Contents
Commands	/codex and /ecodex subcommands, permissions, and examples
Configuration	The entry points and version semantics of config.yml, codex/*.yml, gui/codex_gui.yml, and lang/*.yml
Advancements	The page and node fields of advancements/*.yml, node key rules, coordinate rules, and completion actions
Category GUI	Category/entry definitions, four-state progress, activation and one-time claims, layout types, and placeholders
Triggers	Vanilla advancement triggers.entries and category-entry unlock.triggers
CoreLib Actions	The seven action stages registered by EmakiCodex into CoreLib's ActionRegistry
API	How third-party plugins call the vanilla-advancement layer through emaki-codex-api

Core features

• Vanilla advancement codex: each advancements/*.yml file is one vanilla advancement tab, with node keys like emakicodex:<page>/<node>
• Category-entry codex: each codex/*.yml file defines one GUI category; composite entry ids use <category_id>/<entry_id>, ordered by order
• Four entry states: entries move through locked, unlocked, activated, and claimed; activation and claiming are separate operations
• Two unlock paths: unlock.triggers listens to shared events, while unlock.advancements listens to vanilla advancements; either path can unlock an entry
• Two reward paths: rewards.attributes contributes live attributes after activation, while rewards.actions runs once when the player claims the reward
• Manual grant/revoke and admin entry control: administrators use /codex grant and /codex revoke for vanilla nodes, and admin unlock/reset for category entries
• Action grants and announcements: CoreLib exposes five advancement operations plus codex_show_toast and codex_broadcast_achievement
• Gameplay triggers: vanilla nodes use triggers.entries; category entries use unlock.triggers with shared gameplay events and conditions
• Completion and claim actions: vanilla completion runs actions.complete; category claims run rewards.actions
• PacketEvents coordinate channel: when PacketEvents is installed and advancement.packet_coordinates is enabled, vanilla node x / y values are sent to the client advancement screen

File layout

After startup, EmakiCodex mainly uses these files:

plugins/EmakiCodex/
├─ config.yml
├─ advancements/
│  └─ example_page.yml
├─ codex/
│  └─ example_category.yml
├─ gui/
│  └─ codex_gui.yml
├─ data/
│  └─ <player-uuid>.yml
└─ lang/
   ├─ zh_CN.yml
   └─ en_US.yml

Path	Purpose
config.yml	Main settings for default resource release, advancement registration, PacketEvents coordinates, and trigger enablement; version is currently 1.1.6
advancements/*.yml	Vanilla advancement pages. Each file defines one page, one root node, and any number of child nodes
codex/*.yml	Category-entry definitions. Each file defines one GUI category; the composite entry id is <category_id>/<entry_id>
gui/codex_gui.yml	Category-entry GUI template; functional slots must declare an explicit type
data/<uuid>.yml	Per-player unlocked, activated, and claimed state; attribute values are derived from current configuration rather than stored
lang/*.yml	Command, GUI, reload, and console messages

Quick start

Follow these seven steps in order to get running:

1. Put EmakiCoreLib-*.jar and EmakiCodex-*.jar into the server plugins/ directory
2. Do not put emaki-codex-api-*.jar into plugins/; the API Jar is only for developer compile dependencies
3. After first startup, inspect plugins/EmakiCodex/advancements/example_page.yml
4. After editing or adding pages, run:

/codex reload

5. Open the category-entry codex GUI:

/codex codex

6. Grant the sample vanilla node for testing:

/codex grant Steve example/first_step

7. Manage a category entry with its composite id:

/codex admin unlock Steve example/first_blood
/codex admin reset Steve example/first_blood

The full key form also works:

/codex grant Steve emakicodex:example/first_step

Two configuration models at a glance

The split is simple to remember. One advancements/*.yml file defines one vanilla advancement page:

• Page level: page_id (the key path prefix), title, background, root
• Node level: icon, title, description, frame, parent, x / y, toast, announce, hidden
• Node completion actions go in actions.complete, and gameplay triggers go in triggers.entries

One codex/*.yml file defines one category-entry page:

• Category level: category_id, title, icon, order, entries
• Entry level: title, description, icon, hidden, unlock.triggers, unlock.advancements, rewards.attributes, and rewards.actions
• Commands, GUI state, and data files use the composite id <category_id>/<entry_id>

Both trigger systems use CoreLib condition groups with condition.type and condition.entries. Vanilla nodes register as emakicodex:<page_id>/<node_id>. See Advancements and Category GUI for the full field tables and interaction rules

Notes

• Vanilla advancements and the category-entry GUI keep separate state; do not use advancements/<page_id> where codex/<category_id> is required
• Vanilla nodes are completed through Codex grants: commands, actions, the public API, or triggers award the internal codex criterion
• actions.complete runs only on first vanilla completion; category rewards.actions runs only on the one-time claim
• Category rewards.attributes are not stored as numbers; they are derived from current configuration, so changing the reward config affects already activated players
• If advancement coordinates are enabled, configure x / y for every node in a page to avoid mixing explicit coordinates with client auto-layout