主题

自定义成就系统 ​

自定义成就系统允许开发者通过配置 JSON 创建一套符合自身需求的成就系统。系统内置了击杀生物和获得物品两种预设成就类型，开发者也可通过脚本监听自定义事件来扩展成就触发条件。成就完成时还支持自动调用奖励函数。

Demo

参考官方示例 CustomAchievementMod 了解自定义成就系统的完整实现。

概述 ​

自定义成就系统的核心功能：

  • 通过 JSON 定义成就节点树（支持多级父子关系）
  • 内置"击杀生物"和"获得物品"两种预设成就类型
  • 支持自定义成就触发条件（通过脚本事件）
  • 支持成就完成自动回调奖励函数
  • 提供成就 UI 界面（入口图标、成就分页、提示框）
  • 支持云成就（联机大厅/Apollo）

待补充：成就系统架构图与数据流向。

成就树 JSON（customAchievements/） ​

每个成就节点对应一个 JSON 文件，必须放在行为包的 behavior_pack/customAchievements/ 文件夹下。

behavior_pack/
└── customAchievements/
    ├── root_node.json        # 根节点
    ├── child_node_1.json     # 子节点
    └── child_node_2.json     # 子节点

排序规则

节点的排序方式使用 Python 的 sort 函数，按 node_ID 的字符逐位排序。如果对节点位置有要求，请按此规则编写节点 ID。

待补充：多 Mod 成就节点冲突检查说明。

成就节点 ​

根节点 ​

根节点是成就树的起点，其 title 将作为对应成就分页的主标题，unfinished_icon 将作为分页标题图标。

json
{
  "node_ID": "rootNode",
  "title": "成就分类名称",
  "unfinished_icon": "textures/ui/item/diamond_sword",
  "finished_icon": "textures/ui/item/diamond_sword",
  "goal_number": 3,
  "node_description": "描述信息",
  "window_background": "textures/ui/background/sign_warped"
}

非根节点 ​

非根节点通过 parent_node 字段指定父节点，可选通过 depend_parent 设置是否依赖父节点完成。

属性说明
node_ID唯一标识符，不可重复
parent_node父节点的 node_ID（非根节点必填）
title成就标题，支持颜色代码
unfinished_icon未完成图标路径
finished_icon已完成图标路径
goal_number成就目标值
node_description成就描述
window_background根节点特有，成就分页背景图
reward奖励函数配置
is_hidden是否隐藏节点
finish_tip完成时是否弹出提示框
is_cloud是否为云成就
depend_parent是否依赖父节点完成

注意

修改已发布节点的 goal_number 时需要注意奖励函数的调用逻辑。详见官方文档中的说明。

待补充：use_default_icon_background、auto_sent_cloud 等可选字段详细说明。

触发条件 ​

击杀生物 ​

将 goal_details 的 goal_type 设为 "default_kill"，系统将自动监听指定生物的击杀事件。

json
"goal_details": {
  "goal_type": "default_kill",
  "entity_identifier": "minecraft:cow"
}

获得物品 ​

将 goal_details 的 goal_type 设为 "default_get"，系统将自动监听物品栏变化并统计目标物品数量。

json
"goal_details": {
  "goal_type": "default_get",
  "item_dict": {
    "newItemName": "minecraft:apple"
  }
}

限制

每个成就节点只能监听一种生物或一种物品。item_dict 中必须配置 newItemName，不可配置 count 和 userdata。

待补充：自定义成就触发条件的脚本实现方式。

奖励回调 ​

通过 reward 字段配置成就完成时自动调用的奖励函数：

json
"reward": [
  {
    "function_name": "onReward",
    "name_space": "myNamespace:myServerSystem",
    "data": {
      "EXP": 100,
      "item": "minecraft:diamond"
    }
  }
]
字段说明
function_nameServerSystem 中的函数名
name_spacenameSpace:systemName 格式
data传入函数的参数字典（自动附加 playID）

注意

name_space 中的 System 必须为 ServerSystem，不可为 ClientSystem。

待补充：多奖励函数配置与调用顺序说明。

成就 UI 显示 ​

入口图标 ​

  • 仅当存在可见节点时显示
  • 支持拖拽（拖动释放不触发按钮事件）
  • UI 层级为 110

提示框 ​

  • 最多同时显示 5 个提示框
  • 多余提示缓存至有空槽位时弹出
  • UI 层级为 150（高于入口图标）

相关接口与事件 ​

名称说明
GetNodeDetailInfo获取节点信息
SetNodeFinish设置节点完成
AddNodeProgress增加节点进度
GetChildrenNode获取子节点列表
AchievementCompleteEvent成就完成事件

待补充：各接口的参数说明与代码示例。

完整示例 ​

待补充：一个包含根节点、子节点、击杀成就、获得成就与奖励回调的完整示例。

下一步 ​