基本设置

这个文件解决什么问题

Chronos 的一切都建立在「玩家身上挂着哪个控制器」之上。setting.yml 就是用来从配置层面解决这个问题：

一名玩家在某个时刻，应该被自动挂上哪个控制器？

它提供了三种由弱到强的规则：

• default_controller —— 兜底。谁都没匹配上时用它。
• switch_by_main_hand —— 看主手物品的一个 NBT 标签，标签值就是控制器 ID。简单直接，适合「一把武器一个控制器」。
• triggers（复合触发器） —— 主手 + 副手 + PlaceholderAPI 的组合条件，适合「剑+盾」「同一把武器不同职业」这类需要多条件判断的场景。

实战中，switch_by_main_hand 和 triggers 选择一个开启，具体关系看本文尾部视图。

配置文件全貌

# 兜底：谁都没匹配上时用这个控制器
default_controller: "idle"
 
# 规则一：按主手物品的 NBT 标签切换控制器
switch_by_main_hand:
  enable: false
  # NBT 路径，多层用点号分隔；该路径的值 = 控制器 ID
  path: "controller"
 
# 规则二：复合触发器（主手/副手 NBT + PAPI 组合条件）
triggers:
  enable: false
  list:
    名称(这个名字随便):
      controller: "控制器ID"
      main_hand:
        path: "nbt路径"
        value: "期望值"
      off_hand:
        path: "nbt路径"
        value: "期望值"
      papi: "%placeholder%"
      papi_value: "期望值"

default_controller —— 默认控制器

default_controller: "idle"

玩家登录、或所有切换规则都没命中时，自动挂载这个控制器。值就是 controllers/ 里的文件名（不含 .yml）。

如果把它留空，且没有任何切换规则命中，玩家将不被挂任何控制器。

switch_by_main_hand —— 按主手物品切换

最简单的自动切换：读玩家主手物品上某个 NBT 标签，标签的值直接当作控制器 ID。

switch_by_main_hand:
  enable: true
  path: "controller"

说明：给武器写一个 NBT 标签，值填控制器 ID。比如一把剑的 NBT 里有 controller: "sword"，玩家拿起它就会自动切到 sword 控制器。

多层路径示例：path: "arcartx.weapon.controller" 对应的物品 NBT 是

arcartx → weapon → controller = "sword"

匹配不到时的回退：如果主手物品没有这个标签、或标签值不是一个存在的控制器 ID，则回落到 default_controller；连默认控制器都为空时，玩家的控制器会被清空。

触发时机：玩家切换手持栏位、关闭背包界面、以及加入服务器时都会重新读取一次主手物品。

triggers —— 复合触发器

当「一个物品对一个控制器」不够用时，用触发器。它能同时判断主手 NBT、副手 NBT、PlaceholderAPI 占位符，全部满足才切换。

典型场景：

• 主手剑 + 副手盾 → 剑盾控制器；只拿剑 → 单手剑控制器
• 同一把武器，战士拿是一套连招，法师拿是另一套（靠职业插件的 PAPI 区分）

triggers:
  enable: true
  list:
    剑盾:
      controller: "sword_shield"
      main_hand:
        path: "weapon_type"
        value: "sword"
      off_hand:
        path: "weapon_type"
        value: "shield"
    单手剑:
      controller: "sword"
      main_hand:
        path: "weapon_type"
        value: "sword"

每个触发器条目的字段

list 下每一项的键名（如 剑盾）只是给你自己看的标识，不参与逻辑。

匹配规则（务必记住）

• 条目内是 AND：一个触发器里配了几个条件，就必须全部满足才算命中。
• 没配的条件视为通过：只写了 main_hand 就只查主手，不管副手和 PAPI。
• 按列表顺序取第一个命中：从上往下逐条判断，命中第一个就停下。所以更具体的条目要放在更宽松的条目前面——上面例子里「剑盾」必须排在「单手剑」之前，否则拿着剑+盾也会先被「单手剑」抢先命中。
• 全不命中就回落：所有条目都不满足时，回到 default_controller。

PAPI 周期检测

物品变化能靠事件立刻感知，但 PAPI 的值（比如玩家职业、状态）可能在玩家没动任何物品的情况下改变。为此，只要触发器里存在 PAPI 条件，Chronos 会**每秒（每 20 tick）**重新检测一次。

实战：结合职业插件

同一把剑，不同职业用不同控制器：

triggers:
  enable: true
  list:
    战士持剑:
      controller: "warrior_sword"
      main_hand:
        path: "weapon_type"
        value: "sword"
      papi: "%myrpg_class%"
      papi_value: "warrior"
    法师持剑:
      controller: "mage_sword"
      main_hand:
        path: "weapon_type"
        value: "sword"
      papi: "%myrpg_class%"
      papi_value: "mage"

玩家转职（%myrpg_class% 变化）后，最迟一秒内就会自动切到对应控制器。

三种规则的关系