成就文件结构

achievements/ 是 AchieveMaster 真正的内容目录。分类只是入口，真正决定玩家会完成什么、怎么完成、给什么奖励、是不是任务、会不会重置，全部都在这里。

加载规则

按当前配置管理器实现，achievements/ 有三个关键规则：

1. 会递归加载所有子目录下的 .yml
2. categories.yml 不算成就文件
3. 每个顶级节点就是一条成就

也就是说，这样写是完全可以的：

achievements/
├── examples.yml
├── 活动/
│   └── 春节任务.yml
└── 收集/
    └── 收藏册.yml

最小成就示例

zombie_killer:
  id: "zombie_killer"
  name: "&a&l僵尸猎人"
  description:
    - "&7击杀50只僵尸"
    - "&7进度: &e{progress}&7/&e50"
  category: "combat"
  icon: "ROTTEN_FLESH"

  trigger:
    type: ENTITY_KILL
    条件:
      实体类型: "ZOMBIE"
    进度: +1

  completion:
    target: 50

  points: 10

顶级字段

字段	作用
id	成就 ID，不写时默认用节点名
name	成就显示名
description	描述列表
category	分类 ID
icon	默认图标
iconUnlocked / icon-unlocked	完成时图标
iconLocked / icon-locked	未完成时图标
hidden	是否隐藏
hiddenUntilComplete	完成前完全不展示
hideAfterComplete	完成后隐藏
sortOrder	分类内排序
prerequisites	前置成就列表
prerequisitesMode	前置模式，默认 all
trigger	触发器配置
completion.target	完成目标值
points	完成后提供的成就分
rewards	这条成就自己的奖励
reset / 重置	重置规则
quest / 任务	任务模式配置
objectives / 目标	多目标配置

描述里的动态占位符

成就描述不只是静态文本。按当前 GUI 和 PAPI 处理逻辑，描述里支持这些占位符：

占位符	作用
{progress}	当前进度
{target}	目标进度
{percentage}	完成百分比
{flag:标记名:未完成值:已完成值}	标记状态替换
{obj:目标ID:progress}	某目标当前进度
{obj:目标ID:target}	某目标目标值
{obj:目标ID:name}	某目标名称
{obj:目标ID:complete:❌:✓}	某目标是否完成

例如：

description:
  - "&7主城: {flag:去过主城:❌:✓}"
  - "&7矿洞: {flag:去过矿洞:❌:✓}"

或者：

description:
  - "&7骷髅王: {obj:skeleton_king:progress}/{obj:skeleton_king:target}"
  - "&7是否完成: {obj:skeleton_king:complete:未完成:已完成}"

奖励块 rewards

成就自己的奖励和 points-rewards.yml 是两套东西。

当前实现里，成就级奖励支持这些字段：

• commands
• messages
• title
• sound
• sound_volume
• sound_pitch
• firework
• broadcast
• script / 脚本
• script-js / 脚本js / js

如果你想做的是“完成这条成就以后立即播报、发命令、放烟花、再跑一段脚本”，就在这里写。

重置块 reset

当前实现支持：

reset:
  enabled: true
  type: weekly
  day: 1
  time: "04:00"

支持的类型有：

• daily
• weekly
• monthly
• cron

也支持中文写法：

• 每日
• 每周
• 每月
• 时间
• 星期
• 日期
• 表达式

任务块 quest

quest:
  enabled: true
  require-accept: true
  auto-submit: false
  allow-cancel: true
  cancel-reset-progress: true
  max-accepts: 3
  concurrent-limit: 1

除了基础开关，还支持三类扩展：

接取条件 accept-conditions

可以检查：

• 等级
• 权限
• 金币
• 成就分
• 前置成就

接取消耗 accept-cost

可以真正扣掉：

• 金币
• 成就分
• 物品

提交条件 submit-conditions

当前实现主要是交物品型提交：

submit-conditions:
  items:
    - material: DIAMOND
      amount: 5

多目标 objectives

多目标适合做“一条成就里同时追踪多个子目标”的场景。

完整写法：

objectives:
  skeleton_king:
    name: "骷髅王"
    target: 5
    icon: "SKELETON_SKULL"
    description: "击杀骷髅王"

简写也支持：

objectives:
  skeleton_king: 5
  dragon_knight: 3

任务、重置、隐藏这三件事怎么分开理解

• hidden / hiddenUntilComplete：控制显示
• quest：控制是否需要接取 / 提交 / 取消 / 限次
• reset：控制多久把这条成就状态重置一次

这三件事是并列配置，不是互相替代。

例如：

• 一条成就既可以是任务模式，又可以每周重置
• 一条成就既可以隐藏，又可以带多目标
• 一条成就既可以不是任务，也可以带积分和广播

使用建议

• 成就 ID 一旦上线，就尽量不要随便改，玩家数据和 PAPI 都会受影响。
• 简单成就优先小文件或按分类拆目录，别把所有内容堆进一个 examples.yml。
• 同类成就尽量统一 points、sortOrder、命名风格和图标风格。
• 多目标成就比“很多条碎成就”更适合做系列挑战。
• 任务模式的取消、提交、重置一定先在测试服完整测一遍。

常见问题

节点名和 id 不一样会怎样

可以。

当前实现会优先读你写的 id；没写时才回退到节点名。

子目录里的成就会不会加载

会。

achievements/ 当前是递归加载。

categories.yml 放在子目录里行不行

不建议。

当前实现只会把根目录下的 categories.yml 当成分类文件，别把它拆走。