条件系统

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

统一条件入口

各模块统一使用 condition 作为条件块入口。条件块由 CoreLib 的 ConditionBlock 解析，并向内部条件组提供组合逻辑、条目列表、解析失败策略和可选动作。

condition:
  type: all_of
  entries:
    - '%player_level% >= 10'
    - '%money% >= 1000'
  required_count: 0
  invalid_as_failure: true

字段	类型	默认值	说明
condition.type	string	all_of	条件组合方式。
condition.entries	list	[]	条件节点列表。
condition.required_count	integer	0	at_least 或 exactly 模式下需要满足的条件数量。
condition.invalid_as_failure	boolean	true	条件配置异常或无法求值时是否视为失败。
condition.on_pass.actions	list	[]	条件通过后执行的动作，是否生效取决于调用模块。
condition.on_fail.actions	list	[]	条件失败后执行的动作，是否生效取决于调用模块。
condition.on_fail.block_output	boolean	true	条件失败时是否阻断产物输出，主要用于 Cooking 等产出场景。
condition.on_fail.message	string	""	条件失败时发送给玩家的提示，主要用于 Item 等装备限制场景。

条件组合方式

值	说明
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。

条件节点类型

字符串节点

condition:
  type: all_of
  entries:
    - '%player_level% >= 10'
    - '%money% >= 1000'

expression 节点

condition:
  type: all_of
  entries:
    - type: expression
      expression: '%player_level% >= 20 && %money% >= 1000'

表达式字段支持 expression、condition、value，解析时取第一个非空值。

嵌套条件组

在 entries 中写入带有 entries 的对象即可形成嵌套组。嵌套组的 type 仍表示组合方式，不需要额外写 type: group。

condition:
  type: all_of
  entries:
    - type: any_of
      entries:
        - '%vip_level% >= 1'
        - '%player_level% >= 50'
    - type: expression
      expression: '%money% >= 5000'

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

表达式语法

条件表达式最终由 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%

引擎会优先尝试数值求值；无法作为数值求值时，仅支持字符串 == / != 比较。字符串右值建议加引号。

配置示例

基础权限检查

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

至少满足 N 个条件

condition:
  type: at_least
  required_count: 3
  entries:
    - '%strength% >= 50'
    - '%agility% >= 50'
    - '%intelligence% >= 50'
    - '%vitality% >= 50'
    - '%luck% >= 50'

条件失败动作

condition:
  type: all_of
  entries:
    - '%player_level% >= 30'
    - '%money% >= 5000'
  on_fail:
    actions:
      - 'playsound sound=minecraft:entity.villager.no volume=1 pitch=1'
      - 'sendmessage text="<red>需要 30 级以上且拥有 5000 金币。</red>"'

invalid_as_failure 的作用

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

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

condition:
  invalid_as_failure: true
  entries:
    - '%attribute_attack% >= 100'

变量来源

条件表达式中的变量 %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%

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

PlaceholderAPI

如果服务器安装了 PlaceholderAPI，条件表达式中的 %placeholder% 格式占位符会在求值前被解析。

condition:
  entries:
    - '%player_level% >= 30'
    - '%vault_eco_balance% >= 10000'

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