EmakiCodex

EmakiCodex registers real advancements from YAML. A file becomes a tab in the vanilla advancement screen, and its entries become genuine server advancements that any plugin can read. Gameplay events grant them automatically, and completing one runs CoreLib action lines, so a reward is part of the definition rather than a separate system. Players read their progress in the screen they already know while the server keeps one YAML source of truth: nine gameplay events drive the unlocks, and a reload reaches online players without a reconnect.

01 Core Features

Entries appear in the vanilla advancement screen and are visible to any plugin that reads advancement progress.

• One YAML file is one tab: A page declares its own title, background, root entry and the entries beneath it, each with an icon, title, description, frame type, parent, hidden state and toast behaviour. The parent chain produces the branching layout players expect, and an entry icon keeps only its base material, so a custom-model item used as an icon does not render with its custom appearance.
• Nine gameplay events as triggers: Entries can unlock on entity kills, MythicMobs kills, block breaks, crop harvests, crafting, furnace extraction, fishing, brewing completion and taming.
• Conditions on top of events: A trigger can carry a CoreLib condition group, and multiple triggers on one entry are treated as alternatives.
• Rewards defined with the entry: Completing an entry runs CoreLib action lines with the completion context injected, so items, currency, messages, effects and commands are part of the advancement definition instead of a separate listener somewhere else.
• Reload resyncs online players: After /codex reload the advancement tree is pushed to online players again, and it is also re-sent shortly after a player joins, so configuration changes land without a restart or a reconnect.
• Six action stages including page resets: Granting, revoking, resyncing, resetting one page, resetting everything, and showing a client-only toast.
• Client-only toast: An achievement popup can be shown to one player and withdrawn afterwards, without occupying a real advancement entry.
• Exact node placement when available: With PacketEvents installed, entries are positioned using the coordinates from the file.
• Configuration pre-check with rollback: Configuration and advancement pages are validated on start and on reload, and a failed validation rolls back to the previous configuration rather than registering a broken tree.
• JS script triggers: With scripts.enabled, .js files under scripts/triggers/ register trigger handlers through triggers.register (...); each handler runs when a trigger event dispatches and returns entry ids that are merged with the ids matched by the configured trigger rules to unlock entries, and a handler error or a timeout_ms overrun is reported as a warning and treated as an empty result.
• Codex GUI: /codex open opens the codex GUI: the categories under codex/ become tabs, every entry shows its unlock progress, and the interface carries the activate and claim actions.
• In-game definition editor: /codex edit opens a graphical editor: browse pages and categories, edit an entry's icon, coordinates, unlock conditions and rewards, and saving writes the YAML straight back to disk

02 Feature Overview

Pages and entries

• One file per tab under advancements/, declaring page title, background, root entry and every entry beneath it.
• Entry fields: icon, title, description, frame type, parent, coordinates, hidden state, toast and announcement behaviour.
• The master switch, which also refuses granting and revoking when off.
• Utility commands: /codex grant, /codex revoke.

Triggers and rewards

• Which event unlocks an entry and the condition group that qualifies it, under triggers.entries in a page file.
• CoreLib action lines run on completion under actions.complete, with completion context available as variables.
• Turns automatic unlocking off entirely, leaving manual granting only.
• Six action stages covering grant, revoke, resync, page reset, full reset and client-only toast.

Runtime behaviour

• Whether coordinates from the file are applied, which requires PacketEvents and is read at startup.
• Whether registered advancements are removed when the plugin is disabled.
• Automatic resync after reload and shortly after a player joins.
• The codex GUI, opened with /codex open, shows the categories from codex/ as tabs with their entries, unlock progress, and the activate and claim actions.
• Utility commands: /codex reload, /codex debug

03 In-Game Views

04 Command Output

Granting an advancement by hand, with a reason when it is already done:

> codex grant JiuWu_02 emakicodex:example/root
[ EmakiCodex ] Granted advancement emakicodex:example/root to JiuWu_02
> codex grant JiuWu_02 emakicodex:example/root
[ EmakiCodex ] Advancement emakicodex:example/root operation failed: The player has already completed this advancement

05 Quick Start

1. Place the EmakiCoreLib and EmakiCodex runtime Jars into plugins/, then start the server to generate advancements/example_page.yml.
2. Copy the example page, set your own page title and root entry, and add two entries with a parent relationship.
3. Give one entry a trigger, such as an entity kill narrowed by a condition, and give it an actions.complete reward line.
4. Run /codex reload and confirm the tab and entries appear in the vanilla advancement screen without reconnecting.
5. Perform the trigger to confirm the automatic unlock and the reward, then test /codex grant and /codex revoke on a player

06 Compatibility and Dependencies

Item	Details
Runtime baseline	Java 25, Paper 1.21.8 or newer
Required dependency	EmakiCoreLib
Main commands and aliases	/codex, /ecodex
Key permissions	emakicodex.use, emakicodex.reload, emakicodex.debug, emakicodex.admin
Main configuration entries	config.yml, advancements/, codex/, gui/codex_gui.yml, scripts/, lang/

Optional integrations, each used only when installed, the plugin is fully functional without any of them:

• PacketEvents: enables file-defined entry coordinates, reload without reconnecting and the client-only toast action
• MythicMobs: supplies its own kill trigger
• EmakiAttribute: receives per-entry attributeRewards contributions from activated entries
• PlaceholderAPI: is resolved inside trigger conditions