EmakiCodex

EmakiCodex is the vanilla-advancement codex module in the Emaki series. It defines advancement pages and nodes through advancements/*.yml, registers them as vanilla advancements, and lets commands, CoreLib actions, the public API, and gameplay triggers grant or revoke nodes.

When PacketEvents is installed, EmakiCodex can inject configured node coordinates into the client advancement tree and re-push the registered tree to online players. Without PacketEvents, advancements still 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.

Basic information

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

Pages

Page	Contents
Commands	/codex and /ecodex subcommands, permissions, and examples.
Configuration	The global switches of config.yml and the lang/*.yml language files.
Advancements	The page and node fields of advancements/*.yml, node key rules, coordinate rules, and completion actions.
Triggers	How to write triggers.entries, the available trigger variables, and condition examples.
CoreLib Actions	Actions registered by EmakiCodex into CoreLib's ActionRegistry.
API	How third-party plugins call Codex 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>.
• Manual grant and revoke: administrators can manage online player progress with /codex grant and /codex revoke.
• Action-based grants: other plugins can call Codex actions such as codex_grant_advancement, codex_revoke_advancement, and codex_reset_page from CoreLib action chains.
• Gameplay triggers: nodes can define triggers.entries for kills, crafting, furnace extraction, fishing, brewing, taming, block breaking, mature crop harvesting, and related CoreLib gameplay events.
• Completion actions: when a node completes, actions.complete can run CoreLib actions such as messages, rewards, or cross-module logic.
• PacketEvents coordinate channel: when PacketEvents is installed and advancement.packet-coordinates is enabled, 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
└─ lang/
   ├─ zh_CN.yml
   └─ en_US.yml

Path	Purpose
config.yml	Main settings for default resource release, advancement registration, PacketEvents coordinates, and trigger enablement.
advancements/*.yml	Advancement pages. Each file defines one page, one root node, and any number of child nodes.
lang/*.yml	Command, reload, and console messages.

Quick start

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. Grant the sample node for testing:

/codex grant Steve example/first_step

The full key form also works:

/codex grant Steve emakicodex:example/first_step

Advancement page quick view

One advancements/*.yml file defines one 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, gameplay triggers in triggers.entries. Trigger conditions use CoreLib condition groups with condition.type and condition.entries.

Nodes register as emakicodex:<page_id>/<node_id>. See Advancements for the full field tables, key rules, and coordinate rules, and Triggers for trigger variables and condition examples.

Notes

• EmakiCodex currently focuses on vanilla advancement codex features and no longer provides recipe/JEI transfer features.
• Nodes are completed through Codex grants: commands, actions, the public API, or triggers award the internal codex criterion.
• actions.complete only runs on the first completion; granting an already completed node does not repeat completion actions.
• If coordinates are enabled, configure x / y for every node in a page to avoid mixing explicit coordinates with client auto-layout.