条件系统

条件系统用于判断"某个操作是否允许继续"。它常见于配方、强化、技能、物品、GUI 和动作系统中。当条件不满足时，模块可以阻止操作、显示提示或执行拒绝动作。

条件能检查什么

条件系统支持多种检查维度：

• 玩家权限。
• 玩家等级、经验、经济余额。
• Attribute 属性值或资源状态。
• 物品来源、数量、PDC、Lore、材质。
• 装备状态，例如强化星级、宝石插槽、套装部位。
• PlaceholderAPI 占位符结果。
• 表达式计算结果（数值比较、字符串比较、逻辑运算）。
• 业务模块自己的状态，例如技能等级、工位状态、配方阶段。

具体可用条件取决于调用模块和已安装的桥接插件。

条件组配置

条件通常以"条件组"形式出现在配置中。一个条件组包含多个条件节点，并定义它们之间的组合逻辑。

完整字段参考

字段	别名	类型	默认值	说明
conditions	entries	list	[]	条件节点列表。
condition_type	type	string	all_of	条件组合方式。
condition_required_count	required_count	integer	0	at_least 或 exactly 模式下需要满足的条件数量。
invalid_as_failure	—	boolean	true	条件配置异常或无法求值时是否视为失败。
deny_message	—	string	""	条件不满足时向玩家发送的提示消息（MiniMessage 格式）。
deny_actions	—	list	[]	条件不满足时执行的动作列表。

条件组合方式

值	说明
all_of	所有条件都必须为 true。适合严格门槛。
any_of	至少一个条件为 true。适合多路线解锁。
none_of	所有条件都必须为 false。适合排除检查。
at_least	至少 required_count 个条件为 true。适合可替代条件。
exactly	恰好 required_count 个条件为 true。适合精确匹配场景。

required_count 仅在 at_least 和 exactly 模式下生效，最小值为 1。

空条件组行为

如果条件列表为空（没有任何条件节点），条件组始终返回 true，即不做任何限制。

条件节点类型

每个条件节点可以是以下形式之一：

字符串节点（简写）

直接写一个表达式字符串：

conditions:
  - '%player_level% >= 10'
  - '%money% >= 1000'

expression 节点

使用对象形式，明确指定类型为 expression：

conditions:
  - type: expression
    expression: '%player_level% >= 20 && %money% >= 1000'

表达式字段支持三个别名，取第一个非空值：expression、condition、value。

group 节点（嵌套组）

在条件组内嵌套另一个条件组，实现复杂逻辑：

conditions:
  - type: group
    condition_type: any_of
    conditions:
      - '%vip_level% >= 1'
      - '%player_level% >= 50'
  - type: expression
    expression: '%money% >= 5000'

上面的配置含义：玩家必须满足"VIP 等级 ≥ 1 或玩家等级 ≥ 50"，同时金币 ≥ 5000。

嵌套深度没有硬性限制，但建议不超过 3 层，否则难以维护和排错。

表达式语法

条件表达式最终由 CoreLib 的布尔表达式引擎求值。

比较运算符

运算符	说明	示例
==	等于	%phase% == "success"
!=	不等于	%world% != "world_nether"
<	小于	%level% < 10
<=	小于等于	%star% <= 5
>	大于	%score% > 100
>=	大于等于	%player_level% >= 20

逻辑运算符

运算符	说明	示例
&&	逻辑与	%level% >= 10 && %money% >= 100
||	逻辑或	%rarity% == "rare" || %rarity% == "epic"
!	逻辑非	!%locked%
()	括号分组	(%a% > 0 && %b% > 0) || %admin%

数值与字符串比较

• 引擎会尝试把左右两侧都当作数值表达式求值。
• 如果无法作为数值求值，则仅支持字符串 == / != 比较。
• 字符串右值建议加引号（单引号或双引号），避免与数字表达式混淆。

布尔字面量

以下值被识别为 true：true、yes、y、on、1。

以下值被识别为 false：false、no、n、off、0。

完整配置示例

基础权限检查

conditions:
  condition_type: all_of
  conditions:
    - type: expression
      expression: '%has_permission_emaki.forge.use% == true'
  deny_message: '<red>你没有使用锻造台的权限。'

多条件组合

conditions:
  condition_type: all_of
  conditions:
    - '%player_level% >= 30'
    - '%money% >= 5000'
    - '%world% == "world"'
  deny_message: '<red>需要 30 级以上、5000 金币，且在主世界。'
  deny_actions:
    - 'playsound sound=minecraft:entity.villager.no volume=1 pitch=1'

任意满足（多路线解锁）

conditions:
  condition_type: any_of
  conditions:
    - '%vip_level% >= 2'
    - '%player_level% >= 60'
    - '%quest_completed_master_smith% == true'
  deny_message: '<red>需要 VIP2 以上、60 级或完成大师铁匠任务。'

满足指定数量

conditions:
  condition_type: at_least
  condition_required_count: 3
  conditions:
    - '%strength% >= 50'
    - '%agility% >= 50'
    - '%intelligence% >= 50'
    - '%vitality% >= 50'
    - '%luck% >= 50'
  deny_message: '<red>至少需要 3 项属性达到 50。'

嵌套条件组

conditions:
  condition_type: all_of
  conditions:
    - type: group
      condition_type: any_of
      conditions:
        - '%class% == "warrior"'
        - '%class% == "paladin"'
    - type: expression
      expression: '%player_level% >= 40'
    - type: expression
      expression: '%star% < 10'
  deny_message: '<red>仅限战士或圣骑士，40 级以上，当前强化低于 +10。'

配合动作系统的 @if 前缀

条件也可以直接写在动作行的 @if 控制前缀中：

actions:
  - '@if=%phase%=="success" sendmessage text="<green>成功阶段"'
  - '@if=%player_level%>=50 givemoney amount=500 provider=vault'
  - '@if=%world%!="world_nether" && %money%>=100 sendmessage text="<gold>奖励条件满足"'

invalid_as_failure 的作用

当条件配置有误（例如变量不存在、表达式语法错误、外部插件未加载）时：

• invalid_as_failure: true（默认）：异常条件视为失败，操作被阻止。这是生产服推荐设置，防止配置错误导致玩家绕过限制。
• invalid_as_failure: false：异常条件被跳过，不计入结果。适合开发调试阶段，或者某些条件依赖可选插件时使用。

# 生产服推荐
conditions:
  invalid_as_failure: true
  conditions:
    - '%attribute_attack% >= 100'

# 开发调试或可选条件
conditions:
  invalid_as_failure: false
  conditions:
    - '%optional_plugin_value% >= 10'

变量来源

条件表达式中的变量 %name% 由调用模块注入。不同场景可用变量不同：

场景	常见变量
强化	%star%、%level%、%recipe_id%
锻造	%quality%、%recipe_id%、%material_count%
技能	%skill_level%、%skill_id%、%cooldown%
宝石	%gem_level%、%slot_count%、%gem_type%
物品触发	%item_id%、%trigger_type%
通用	%player_level%、%money%、%world%、%has_permission_xxx%

各模块实际注入的变量名请参阅对应模块文档。如果变量不存在且 invalid_as_failure 为 true，条件会失败。

与 PlaceholderAPI 的关系

如果服务器安装了 PlaceholderAPI，条件表达式中的 %placeholder% 格式占位符会在求值前被解析。这意味着你可以使用任何 PAPI 占位符作为条件变量：

conditions:
  conditions:
    - '%player_level% >= 30'
    - '%vault_eco_balance% >= 10000'

注意：PAPI 占位符返回的是字符串，如果返回值包含颜色代码或非数字字符，数值比较可能失败。建议使用返回纯数字的占位符。

错误：YAML 会把 > 解析为折叠块标记

conditions:

• %level% > 10

正确：加引号

conditions:

• '%level% > 10'

### 条件中使用了不存在的变量

如果变量不存在：

- 数值比较会失败（无法转为数字）。
- 字符串比较中，缺失变量会被替换为空字符串。
- 当 `invalid_as_failure: true` 时，整个条件视为失败。

建议在配置前确认当前模块和场景支持哪些变量。