CoreLib 动作

运维按段查参数, 把 EmakiCodex 的成就管理能力接进动作链. 每段的结构都是参数表, 示例, 异常处理与成功输出, 照抄即可执行

前置条件: 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 段