Advancements

Writing advancements/*.yml means knowing which fields pages and nodes accept, how node keys are formed, how client coordinates take effect, and what runs after a node completes

Keep one sentence in mind: each advancements/*.yml file defines one vanilla advancement tab. Everything below is organized into four parts: page and node fields, registration key rules, the PacketEvents coordinate channel, and completion actions

NOTE

Only vanilla advancements are covered here. The category entries in codex/*.yml are a separate model whose category_id does not substitute for page_id here; see Category GUI

For automatic grants, see Triggers

advancements/*.yml

Basic structure:

page_id: "example"
title: "<gradient:#F59E0B:#EC4899>Codex Example</gradient>"
background: "minecraft:textures/gui/advancements/backgrounds/adventure.png"
root: "root"

advancements:
  root:
    icon: "minecraft-enchanted_book"
    title: "<gold>Codex Path</gold>"
    description: "<gray>Start your journey.</gray>"
    frame: "task"
    x: 0.0
    y: 1.0
    toast: false
    announce: false
    hidden: false
    actions:
      complete: []

Page fields:

Field	Type	Required	Default	Allowed values	Description
page_id	string	No	empty	non-blank string	Page ID and key path prefix; a page with a blank page_id is skipped. Example nodes register as emakicodex:example/root
title	MiniMessage string	No	page_id	MiniMessage	Advancement tab title
background	string	No	minecraft:textures/gui/advancements/backgrounds/stone.png	resource-pack texture path	Vanilla advancement background texture path, such as minecraft:textures/gui/advancements/backgrounds/adventure.png
root	string	No	empty	local node ID	Local ID of the root node; must exist under advancements, otherwise the whole page is skipped
advancements	map	No	empty	keys are local node IDs	Node definitions

Node fields:

Field	Type	Required	Default	Allowed values	Description
icon	ItemSource string	No	minecraft-book	CoreLib ItemSource shorthand	Node icon, such as minecraft-diamond
title	MiniMessage string	No	node ID	MiniMessage	Node title
description	MiniMessage string	No	empty	MiniMessage	Node description
frame	string	No	task	task / goal / challenge	Vanilla frame style; unknown values fall back to task
parent	string	No	empty	local node ID	Local parent node ID; omit for the root. Empty or missing means the node is a root
x	number	No	0.0	any double	UI X coordinate, effective only through the PacketEvents coordinate channel
y	number	No	0.0	any double	UI Y coordinate, effective only through the PacketEvents coordinate channel
hidden	boolean	No	false	true / false	Whether the node stays hidden until completed
toast	boolean	No	true	true / false	Whether vanilla shows a completion toast
announce	boolean	No	advancement.announce_default	true / false	Whether completion is broadcast; falls back to config.yml advancement.announce_default when omitted
actions.complete	list<string>	No	empty	CoreLib action line	CoreLib action lines executed on first completion
triggers.entries	list	No	empty	trigger list	Automatic grant trigger entries, see Triggers

Node key rules

EmakiCodex registers nodes as:

emakicodex:<page_id>/<node_id>

Examples:

emakicodex:example/root
emakicodex:example/first_step
emakicodex:example/challenge

Commands, API calls, and actions can use either short example/first_step IDs or full emakicodex:example/first_step keys

PacketEvents coordinate rules

For coordinates to take effect, x / y must meet all three conditions before they reach the client advancement UI:

1. PacketEvents is installed and enabled
2. config.yml > advancement.packet_coordinates: true
3. At least one coordinate on the node is not 0.0

Notes:

• x=0.0 and y=0.0 is treated as "not set", so that node falls back to client auto-layout
• Configure coordinates for every node in the same page to avoid mixing explicit coordinates with auto-layout
• Without PacketEvents, advancements still register normally; only coordinate injection is unavailable

While advancement.enabled: true, joining players receive one delayed advancement re-push so coordinates and the latest registration result apply right after login

Completion actions

actions.complete is a list of CoreLib action lines (command-style lines executed uniformly across modules) that runs when a node completes for the first time

advancements:
  first_step:
    actions:
      complete:
        - "send_message text=<green>You took your first codex step!</green>"
        - "give_item item=minecraft-diamond amount=1"

Behavior:

• Commands, API calls, actions, and triggers all complete nodes through the same vanilla advancement completion flow
• Granting an already completed node does not complete it again and does not repeat actions.complete
• Actions that need a player target should only be used when the completion context has a player
• Context variables available while actions.complete runs: advancement_id (full key), advancement_node (local node ID), advancement_title, and advancement_page (page ID)

Related Pages

• Triggers: how to write triggers.entries, the available events and condition examples
• Category GUI: the separate category-entry model, which can reference these node keys through unlock.advancements
• Configuration: the advancement.enabled and packet_coordinates global switches
• Commands and Permissions: granting, revoking and /codex reload
• CoreLib Actions: granting advancements from another module's action chain