Emaki Series

条件系统 ​

CoreLib 的条件系统覆盖条件组写法, "某个操作能不能继续" 的判断, 以及条件不满足时的处理

条件系统用来判断"某个操作是否允许继续". 配方, 强化, 技能, 物品, GUI 和动作系统里都能见到它. 条件不满足时, 模块可以阻止操作, 显示提示或执行拒绝动作

统一条件入口 ​

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

yaml
condition:
  type: all_of
  entries:
    - '%player_level% >= 10'
    - '%money% >= 1000'
  required_count: 0
  invalid_as_failure: true
字段类型必填默认值取值范围说明
condition.typestring否all_ofall_of, any_of, none_of, at_least, exactly条件组合方式; 无法识别的值回退为 all_of
condition.entrieslist否[]字符串表达式, type: expression 节点, 嵌套条件组条件节点列表
condition.required_countinteger否0非负整数at_least 或 exactly 模式下需要满足的条件数量; at_least 下写 0 或负数按 1 处理
condition.invalid_as_failureboolean否truetrue, false条件配置异常或无法求值时是否视为失败
condition.on_pass.actionslist<\string>否[]动作管道行条件通过后执行的动作, 是否生效取决于调用模块
condition.on_fail.actionslist<\string>否[]动作管道行条件失败后执行的动作, 是否生效取决于调用模块
condition.on_fail.block_outputboolean否falsetrue, false条件失败时是否阻断产物输出, 主要用于 Cooking 等产出场景
condition.on_fail.messagestring否""MiniMessage 文本条件失败时发送给玩家的提示, 主要用于 Item 等装备限制场景

条件组合方式 ​

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

required_count 只在 at_least 和 exactly 模式下生效: at_least 下写 0 或负数按 1 处理, exactly 下按 max(0, required_count) 处理. 条件列表为空时, 条件组始终返回 true

条件节点类型 ​

你写的条件节点可以是下列三种形态之一: 字符串表达式, expression 节点对象, 嵌套条件组. 动作系统的目标选择器 在同一套 entries / type / required_count 语法之上额外提供了类型节点 (实体类型, 生命值, 状态, 权限, 第三方生物系统身份等), 组合方式与条件节点完全一致

字符串节点 ​

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

expression 节点 ​

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

注意: 表达式只能写在 expression 字段, 没有其他等价写法. 写成 condition 或 value 不会被读取, 节点会因表达式为空而失效

嵌套条件组 ​

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

yaml
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%

引擎会优先尝试数值求值; 无法作为数值求值时, 仅支持字符串 == / != 比较. 字符串右值记得加引号

配置示例 ​

基础权限检查 ​

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

至少满足 N 个条件 ​

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

条件失败动作 ​

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

invalid_as_failure 的作用 ​

当条件配置有误 (例如变量不存在, 表达式语法错误, 外部插件未加载) 时:

  • condition.invalid_as_failure: true (默认): 异常条件视为失败, 操作被阻止. 这是生产服推荐设置, 防止配置错误导致玩家绕过限制
  • condition.invalid_as_failure: false: 异常条件被跳过, 不计入结果. 适合开发调试阶段, 或者某些条件依赖可选插件时使用
yaml
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% 格式占位符会在求值前被解析

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

PAPI 占位符返回的是字符串, 返回值里带颜色代码或非数字字符时数值比较可能失败, 所以条件里用返回纯数字的占位符更稳妥