Advancements

Each advancements/*.yml file defines one vanilla advancement tab. This page covers the page and node fields, the registration key rules, the PacketEvents coordinate channel and the completion actions.

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	Description
page_id	string	Page ID and key path prefix. Required; a page with a blank page_id is skipped. Example nodes register as emakicodex:example/root.
title	MiniMessage string	Advancement tab title. Falls back to page_id when omitted.
background	string	Vanilla advancement background texture path, such as minecraft:textures/gui/advancements/backgrounds/adventure.png. Defaults to minecraft:textures/gui/advancements/backgrounds/stone.png when omitted.
root	string	Local ID of the root node; must exist under advancements.
advancements	map	Node definitions keyed by local node ID.

Node fields:

Field	Type	Default	Description
icon	ItemSource string	minecraft-book	Node icon using CoreLib ItemSource shorthand, such as minecraft-diamond.
title	MiniMessage string	Node ID	Node title.
description	MiniMessage string	Empty	Node description.
frame	string	task	Vanilla frame style: task, goal, or challenge; unknown values fall back to task.
parent	string	Empty	Local parent node ID; omit for the root.
x	number	0.0	UI X coordinate, effective only through the PacketEvents coordinate channel.
y	number	0.0	UI Y coordinate, effective only through the PacketEvents coordinate channel.
toast	boolean	true	Whether vanilla shows a completion toast.
announce	boolean	false	Whether completion is broadcast.
hidden	boolean	false	Whether the node stays hidden until completed.
actions.complete	list	Empty	CoreLib action lines executed on first completion.
triggers.entries	list	Empty	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

x / y affect the client advancement UI only when all of these are true:

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 executed when a node completes for the first time.

advancements:
  first_step:
    actions:
      complete:
        - "sendmessage text=<green>You took your first codex step!</green>"
        - "giveitem 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.

Related Pages

• Triggers: how to write triggers.entries, the available events and condition examples.
• 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.