CoreLib 动作

EmakiCodex 启用后会向 CoreLib 动作注册表追加成就管理动作。它们可用于其他模块的奖励、触发器、脚本或动作模板中，用来授予、撤销、重推、重置 Codex 图鉴节点，或显示只存在于客户端的成就 Toast。

本页只记录 EmakiCodex 注册的 CoreLib 动作；CoreLib 自带通用动作见 CoreLib 动作系统。

所有 Codex 动作的 source 为 emakicodex，分类为 codex。当前规范动作 ID 使用下划线形式，不再使用旧的连字符别名。

动作总览

动作 ID	说明
codex_grant_advancement	授予在线玩家一个 Codex 节点。
codex_revoke_advancement	撤销在线玩家一个 Codex 节点。
codex_resync_advancement	通过 PacketEvents 向在线玩家重推 Codex Advancement 数据。
codex_reset_page	撤销在线玩家某一页下的所有已完成节点。
codex_reset_all	撤销在线玩家所有已注册 Codex 节点。
showachievementtoast	向当前玩家显示客户端成就 Toast，不注册或授予真实进度。

codex_grant_advancement

授予在线玩家一个 EmakiCodex 成就节点。

参数	类型	必填	默认值	说明
advancement	STRING	是	—	成就 ID。可写 page/node，也可写完整 NamespacedKey。
target	STRING	否	动作上下文玩家	目标在线玩家名或 UUID。

actions:
  - 'codex_grant_advancement advancement=example/first_step'
  - 'codex_grant_advancement advancement=emakicodex:example/challenge target=Steve'

失败场景：

• 没有动作上下文玩家，且没有提供在线 target。
• advancement 为空、未注册，或玩家已经完成该节点。

codex_revoke_advancement

撤销在线玩家一个 EmakiCodex 成就节点。

参数	类型	必填	默认值	说明
advancement	STRING	是	—	成就 ID。可写 page/node，也可写完整 NamespacedKey。
target	STRING	否	动作上下文玩家	目标在线玩家名或 UUID。

actions:
  - 'codex_revoke_advancement advancement=example/first_step'
  - 'codex_revoke_advancement advancement=emakicodex:example/challenge target=Steve'

失败场景：

• 没有动作上下文玩家，且没有提供在线 target。
• advancement 为空、未注册，或玩家尚未完成该节点。

codex_resync_advancement

向在线玩家重推当前已注册的 Codex Advancement 数据。该动作依赖 PacketEvents；未安装或不可用时会失败。

参数	类型	必填	默认值	说明
target	STRING	否	动作上下文玩家	目标在线玩家名或 UUID。

actions:
  - 'codex_resync_advancement'
  - 'codex_resync_advancement target=Steve'

适用场景：

• 配置重载后，希望不要求玩家重登就刷新客户端成就树。
• 自定义流程里需要在授予或重置后主动刷新显示。

codex_reset_page

撤销在线玩家某一页下所有已注册的 Codex 节点。实现会按注册节点的反向顺序逐个 revoke，适合先撤销子节点再撤销父节点。

参数	类型	必填	默认值	说明
page	STRING	是	—	成就页 ID，例如 example。
target	STRING	否	动作上下文玩家	目标在线玩家名或 UUID。

actions:
  - 'codex_reset_page page=example'
  - 'codex_reset_page page=example target=Steve'

返回结果会包含 mode、page、nodes 与 revoked，可用于调试动作执行情况。

codex_reset_all

撤销在线玩家所有当前已注册的 Codex 节点。

参数	类型	必填	默认值	说明
target	STRING	否	动作上下文玩家	目标在线玩家名或 UUID。

actions:
  - 'codex_reset_all'
  - 'codex_reset_all target=Steve'

返回结果会包含 mode=all、nodes 与 revoked。

showachievementtoast

向当前玩家显示客户端成就 Toast，不注册、不授予、不保存真实进度。该动作依赖 PacketEvents，并需要玩家上下文。

参数	类型	必填	默认值	说明
title	STRING	是	—	Toast 标题，支持 MiniMessage。
description	STRING	否	""	Toast 描述文本，支持 MiniMessage。
icon	STRING	否	minecraft-book	Toast 图标物品来源；支持 CoreLib 物品来源短写，无法解析时回退为原版材质。
frame	STRING	否	task	Toast 框体：task、goal 或 challenge。
id	STRING	否	随机 UUID	客户端临时进度 ID，最终命名空间为 emakicodex:toast/<id>。
remove_delay	TIME	否	20t	发送后移除临时进度包的延迟。

actions:
  - 'showachievementtoast title="<gold>图鉴发现</gold>" description="<gray>新的篇章已点亮</gray>" icon=minecraft-book frame=goal id=codex_discovery remove_delay=20t'

使用提示

• 这些动作只处理在线玩家；target 可以是在线玩家名或 UUID。
• 如果不提供 target，动作会使用当前 CoreLib ActionContext 的玩家。
• 节点是否可见、父子关系、toast、广播与完成动作仍由 advancements/*.yml 控制。
• codex_resync_advancement 与 showachievementtoast 需要 PacketEvents；授予/撤销/重置动作不依赖 PacketEvents。
• 文档、示例和配置应只使用当前下划线规范 ID，不再继续传播历史连字符写法。