CoreLib Actions

Operators can look up each stage's parameters and wire EmakiCodex's advancement management into an action chain. Every stage follows the same layout -- parameter table, example, failure handling, success output -- so you can copy and run it

Prerequisite: EmakiCodex must be enabled for the stages to register in the CoreLib action registry. Once registered, they are callable from other modules' rewards, triggers, or pipeline templates to grant, revoke, resync, or reset Codex nodes, or to show a client-only advancement toast

NOTE

Only the stages registered by EmakiCodex are documented here. CoreLib built-in stages are documented in CoreLib Actions

Shared constraints: 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

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

Target selection: 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'

Failure handling: 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

Verification: 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'

Failure handling: 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

Failure handling: 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

Verification: 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'

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

Failure handling: a blank page fails with INVALID_CONFIG; a page that matches no registered node is skipped

Verification: 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 execution order matches codex_reset_page

Verification: 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>"'

Edge case: 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, failures, and verification:

• 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