分数系统

分数系统是关卡级别的全局变量，可用于追踪进度、统计击杀数、收集计数等。分数定义在主关卡配置中，所有子关卡共享。

配置方式

在主关卡配置的 scores 节中定义：

简写方式

值即最大值，初始值为 0：

scores:
  star: 10        # max=10, initial=0
  kill_count: 50  # max=50, initial=0

详细方式

可自定义最大值和初始值：

scores:
  coin:
    max: 100
    initial: 20  # 可选，默认 0

混合使用

scores:
  star: 10
  coin:
    max: 100
    initial: 20

分数操作

分数值始终被限制在 [0, max] 范围内（自动 clamp）。

在 Kether 脚本中操作

插件注册了 score Kether 语句（命名空间 areamodule）：

# 设置分数
areamodule:score set star to 5

# 增加分数
areamodule:score add kill_count by 1

# 减少分数（传负数）
areamodule:score add coin by -10

# 获取当前值
areamodule:score get star

# 获取最大值
areamodule:score max star

# 获取进度字符串 "当前/最大"
areamodule:score progress star

TIP

score 语句会自动推断当前关卡：优先从脚本变量表中获取 level，其次根据执行者（玩家）所在位置匹配关卡。

通过 API 操作

AreaModuleAPI.setScore("关卡ID", "star", 5)
AreaModuleAPI.addScore("关卡ID", "kill_count", 1)
AreaModuleAPI.getScore("关卡ID", "star")            // 返回 Int?
AreaModuleAPI.getScoreProgressString("关卡ID", "star") // 返回 "5/10"

通过 PlaceholderAPI 读取

%areamodule_score_关卡ID_star%       → 当前值
%areamodule_max_关卡ID_star%         → 最大值
%areamodule_progress_关卡ID_star%    → 当前/最大

省略关卡 ID 时，自动按玩家位置推断：

%areamodule_score_star%
%areamodule_progress_star%

重置行为

• 关卡正常完成/失败：分数会被重置到初始值
• 硬重置 (hardreset)：分数重置到初始值
• 分数不会在子关卡切换时重置，它是关卡级别的全局状态