CoreLib 动作

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

NOTE

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

七个段的分类都是 codex，目标要求都是 REQUIRED_ENTITY，非玩家目标会跳过。旧的 showachievementtoast 现在写作 codex_show_toast；五个 Advancement 段的 id 未变。

这些段作用于原版 Advancement 与客户端提示，不修改分类条目图鉴（codex/*.yml）的解锁、激活或领取状态。

「作用于谁」由 source 决定，不再有 target 参数：作用于执行者自己写 self，指定玩家用 player_by_name。

段总览

段 ID	说明
codex_grant_advancement	授予目标玩家一个 Codex 节点。
codex_revoke_advancement	撤销目标玩家一个 Codex 节点。
codex_resync_advancement	向目标玩家重推 Codex Advancement 数据。
codex_reset_page	撤销目标玩家某一页下的所有已注册节点。
codex_reset_all	撤销目标玩家所有已注册 Codex 节点。
codex_show_toast	向目标玩家显示客户端成就 Toast，不注册或授予真实进度。
codex_broadcast_achievement	用原版风格句式向全服播报一条成就消息。

codex_grant_advancement

授予目标玩家一个 EmakiCodex 成就节点。

参数	类型	必填	默认值	说明
advancement	STRING	是	—	成就 ID。可写 page/node，也可写完整 NamespacedKey。

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

advancement 为空时以 INVALID_CONFIG 失败。节点未注册与玩家已完成该节点合并报为一个 REJECTED：成就服务的返回值区分不出这两种情况，在这里细分诊断只会是猜测。

成功时输出 advancement 与 target。

codex_revoke_advancement

撤销目标玩家一个 EmakiCodex 成就节点。

参数	类型	必填	默认值	说明
advancement	STRING	是	—	成就 ID。可写 page/node，也可写完整 NamespacedKey。

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

advancement 为空时以 INVALID_CONFIG 失败；节点未注册或玩家尚未完成该节点时以 REJECTED 失败。

codex_resync_advancement

向目标玩家重推当前已注册的 Codex Advancement 数据。无参数。

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

适用场景：

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

这个段依赖 PacketEvents：网关不存在或当前不支持重推时以 MISSING_CONTEXT 失败，重推本身失败时以 INTERNAL_ERROR 失败。成功时输出 target 与 player。

codex_reset_page

撤销目标玩家某一页下所有已注册的 Codex 节点。

参数	类型	必填	默认值	说明
page	STRING	是	—	成就页 ID，例如 example。

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

节点按注册顺序的反向逐个撤销，也就是先子节点后父节点：先撤父节点会让客户端显示已经不存在的进度。

page 为空时以 INVALID_CONFIG 失败；该页没有匹配到任何已注册节点时按跳过处理。成功时输出 target、player、mode、page、nodes、revoked。

codex_reset_all

撤销目标玩家所有当前已注册的 Codex 节点。无参数。

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

撤销顺序与 codex_reset_page 相同。成功时输出 mode=reset_all、nodes 与 revoked，page 为空字符串。

codex_show_toast

向目标玩家显示客户端成就 Toast，不注册、不授予、不保存真实进度。Toast 是一个通过封包推送的假成就，稍后再撤回，所以撤回是被调度出去的而不是立即执行。

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

actions:
  - 'self | codex_show_toast title="<gold>图鉴发现</gold>" description="<gray>新的篇章已点亮</gray>" icon=minecraft-book frame=goal id=codex_discovery remove_delay=20t'
  - 'self | codex_show_toast title="<yellow>解锁新配方</yellow>"'

同一个 id 反复触发时，旧的撤回任务不会误删新推送的 Toast：撤回带有一次性令牌，令牌在重载后依然有效，所以重载前调度的撤回能识别出自己那份 Toast 已被替换。

codex_broadcast_achievement

用原版风格句式把一条成就播报给全服。与 codex_show_toast 不同，它只发送聊天消息，不推送客户端进度包，因此不需要 PacketEvents。

参数	类型	必填	默认值	说明
title	STRING	是	—	成就标题，支持 MiniMessage。
description	STRING	否	""	悬浮提示内容。
frame	STRING	否	task	使用哪套默认句式：task、goal 或 challenge。
format	STRING	否	""	非空时整句覆盖默认句式，可用 %player% 与 %title%。
permission	STRING	否	""	非空时只有持有该权限的玩家收到播报。
console	BOOLEAN	否	true	是否同时向控制台回显。

actions:
  - 'self | codex_broadcast_achievement title="<gold>初次讨伐</gold>" frame=task'
  - 'player_by_name name=Steve | codex_broadcast_achievement title="<light_purple>无伤通关</light_purple>" frame=challenge description="<gray>不受任何伤害完成挑战</gray>"'
  - 'self | codex_broadcast_achievement title="<yellow>秘境开启</yellow>" format="<white>%player% 点亮了 <yellow>[%title%]</yellow></white>" permission=emakicodex.use console=false'

行为说明：

• 该段的执行目标是 global，但仍要求上下文里有玩家目标：句式中的 %player% 取自该目标。
• title 为空以 INVALID_CONFIG 失败；frame 不是三个允许值之一同样以 INVALID_CONFIG 失败。
• 默认句式优先取语言键 broadcast.frame.<frame>，缺失时回退到内置中文句式。
• 成功时输出 player、title、frame 与实际收到播报的 recipients 数量。

使用提示

• 这些段只处理在线玩家。
• 节点是否可见、父子关系、toast、广播与完成动作仍由 advancements/*.yml 控制。
• codex_resync_advancement 与 codex_show_toast 需要 PacketEvents；授予、撤销、重置和播报段不依赖 PacketEvents。
• 相关服务尚未就绪时，段以 MISSING_CONTEXT 失败而不是静默跳过。
• 要改动分类条目图鉴状态，使用 /codex admin unlock、/codex admin reset 或 GUI 交互，而不是这些 Advancement 段。