CoreLib Actions

When EmakiCodex is enabled, it adds advancement management stages to the CoreLib action registry. Use them in other modules' rewards, triggers, or pipeline templates to grant, revoke, resync, or reset Codex nodes, to show a client-only advancement toast, or to announce an achievement server-wide.

NOTE

This page documents only the stages registered by EmakiCodex. CoreLib built-in stages are documented in CoreLib Actions.

All seven stages use the category codex and declare REQUIRED_ENTITY; non-player targets are skipped. The old showachievementtoast is now written codex_show_toast; the five advancement stage IDs are unchanged.

These stages act on vanilla advancements and client-side presentation. They do not change unlocked, activated, or claimed state in the category-entry codex (codex/*.yml).

Which player is affected comes from the source, so there is no target parameter any more: use self for the caster, or player_by_name for a named player.

Stage overview

Stage ID	Description
codex_grant_advancement	Grants one Codex node to the target player.
codex_revoke_advancement	Revokes one Codex node from the target player.
codex_resync_advancement	Resends the Codex advancement data to the target player.
codex_reset_page	Revokes every registered node on one page for the target player.
codex_reset_all	Revokes every registered Codex node for the target player.
codex_show_toast	Shows a client-side advancement toast without registering or granting real progress.
codex_broadcast_achievement	Announces an achievement to the whole server with a vanilla-style sentence.

codex_grant_advancement

Grants one EmakiCodex advancement node to the target player.

Parameter	Type	Required	Default	Description
advancement	STRING	Yes	—	Advancement ID. Accepts page/node or a full NamespacedKey.

actions:
  - 'self | codex_grant_advancement advancement=example/first_step'
  - 'player_by_name name=Steve | codex_grant_advancement advancement=emakicodex:example/challenge'

A blank advancement fails with INVALID_CONFIG. An unregistered node and an already-completed node are reported together as one REJECTED: the advancement service's result cannot tell them apart, so narrowing the diagnostic here would be a guess.

On success the stage reports advancement and target.

codex_revoke_advancement

Revokes one EmakiCodex advancement node from the target player.

Parameter	Type	Required	Default	Description
advancement	STRING	Yes	—	Advancement ID. Accepts page/node or a full NamespacedKey.

actions:
  - 'self | codex_revoke_advancement advancement=example/first_step'
  - 'player_by_name name=Steve | codex_revoke_advancement advancement=emakicodex:example/challenge'

A blank advancement fails with INVALID_CONFIG; an unregistered node or a node the player has not completed fails with REJECTED.

codex_resync_advancement

Resends the currently registered Codex advancement data to the target player. No parameters.

actions:
  - 'self | codex_resync_advancement'
  - 'player_by_name name=Steve | codex_resync_advancement'

Useful when:

• A configuration reload should refresh the client advancement tree without asking players to relog.
• A custom flow needs to refresh the display after granting or resetting.

This stage depends on PacketEvents: a missing gateway or one that cannot resync right now fails with MISSING_CONTEXT, and a failed resync fails with INTERNAL_ERROR. On success it reports target and player.

codex_reset_page

Revokes every registered Codex node on one page for the target player.

Parameter	Type	Required	Default	Description
page	STRING	Yes	—	Advancement page ID, for example example.

actions:
  - 'self | codex_reset_page page=example'
  - 'player_by_name name=Steve | codex_reset_page page=example'

Nodes are revoked in reverse registration order, children before parents: revoking a parent first can leave the client showing progress that no longer exists.

A blank page fails with INVALID_CONFIG; a page that matches no registered node is skipped. On success the stage reports target, player, mode, page, nodes, and revoked.

codex_reset_all

Revokes every currently registered Codex node for the target player. No parameters.

actions:
  - 'self | codex_reset_all'
  - 'player_by_name name=Steve | codex_reset_all'

The revoke order matches codex_reset_page. On success it reports mode=reset_all, nodes, and revoked, with page as an empty string.

codex_show_toast

Shows a client-side advancement toast to the target player without registering, granting, or persisting real progress. The toast is a fake advancement pushed over the wire and withdrawn again a moment later, so the removal is scheduled rather than immediate.

Parameter	Type	Required	Default	Description
title	STRING	Yes	—	Toast title, MiniMessage supported.
description	STRING	No	""	Toast description, MiniMessage supported.
icon	STRING	No	minecraft-book	Toast icon item source. Accepts CoreLib item source shorthand and falls back to a vanilla material when it cannot be resolved.
frame	STRING	No	task	Toast frame: task, goal, or challenge.
id	STRING	No	""	Client-side toast ID. Empty generates a random one; the final namespace is emakicodex:toast/<id>.
remove_delay	DURATION	No	20t	Delay before the temporary progress packet is withdrawn.

actions:
  - 'self | codex_show_toast title="<gold>Codex Discovery</gold>" description="<gray>A new chapter is lit</gray>" icon=minecraft-book frame=goal id=codex_discovery remove_delay=20t'
  - 'self | codex_show_toast title="<yellow>New recipe unlocked</yellow>"'

Firing the same id repeatedly does not let a stale removal cancel the newer toast: removals carry a one-shot token, and the tokens survive a reload, so a removal scheduled before the reload recognises that its own toast has since been replaced.

codex_broadcast_achievement

Announces an achievement to the whole server with a vanilla-style sentence. Unlike codex_show_toast, it only sends chat messages and pushes no client progress packet, so it does not require PacketEvents.

Parameter	Type	Required	Default	Description
title	STRING	Yes	—	Achievement title, MiniMessage supported.
description	STRING	No	""	Hover tooltip content.
frame	STRING	No	task	Which default sentence to use: task, goal, or challenge.
format	STRING	No	""	Replaces the default sentence entirely when non-empty; supports %player% and %title%.
permission	STRING	No	""	When non-empty, only players holding this permission receive the announcement.
console	BOOLEAN	No	true	Whether to echo the announcement to the console.

actions:
  - 'self | codex_broadcast_achievement title="<gold>First Hunt</gold>" frame=task'
  - 'player_by_name name=Steve | codex_broadcast_achievement title="<light_purple>Flawless Run</light_purple>" frame=challenge description="<gray>Cleared without taking damage</gray>"'
  - 'self | codex_broadcast_achievement title="<yellow>Realm Opened</yellow>" format="<white>%player% lit up <yellow>[%title%]</yellow></white>" permission=emakicodex.use console=false'

Behavior:

• The stage executes on the global target but still requires a player in context: %player% comes from that target.
• A blank title fails with INVALID_CONFIG, and a frame outside the three allowed values also fails with INVALID_CONFIG.
• The default sentence comes from the language key broadcast.frame.<frame>, falling back to a built-in sentence when the key is missing.
• On success it reports player, title, frame, and the recipients count that actually received the announcement.

Notes

• These stages only handle online players.
• Node visibility, parent/child relationships, toasts, broadcasts, and completion actions are still controlled by advancements/*.yml.
• codex_resync_advancement and codex_show_toast require PacketEvents; the grant, revoke, reset, and broadcast stages do not.
• When the relevant service is not ready, the stage fails with MISSING_CONTEXT rather than skipping silently.
• To change category-entry state, use /codex admin unlock, /codex admin reset, or GUI interaction rather than these advancement stages.