Emaki Series

触发器 ​

触发器的配置要点: 主动技能什么时候能放, 被动技能靠哪些游戏事件自动触发, 触发器之间怎么处理冲突, 以及施法模式怎么设置

触发器就是「什么情况下会触发技能」的规则, 插件把它分成主动触发器和被动触发器两类

架构概述 ​

  • 主动触发器: 玩家在 GUI 里把技能绑到触发器槽位, 进了施法模式后做对应操作就能释放
  • 被动触发器: 在技能配置里用 passive_triggers 声明, 条件满足时自动触发
text
主动技能: 玩家在 GUI 绑定技能到 right_click 槽位 → 进入施法模式后右键释放
被动技能: 技能配置 passive_triggers: [attack] → 攻击命中时自动触发

触发器注册表由两部分组成: 插件内置的默认触发器定义, 再加上 config.yml 里 triggers / passive_triggers 的同名覆盖. 所以 config 只管显示名, 启用状态和互斥声明; 如果你想用一个内置清单里没有的触发器 id (例如 consume), 必须在 config 里显式注册, 不然派发时会被直接丢掉, 也不会报错

主动触发器 ​

主动触发器是全局槽位. 你在技能 GUI 里把技能绑到某个槽位, 进入施法模式后做对应操作就能释放

触发器操作
left_click左键
right_click右键
shift_left_clickShift + 左键
shift_right_clickShift + 右键
drop_qQ 键丢弃
hotbar_1 ~ hotbar_9数字键 1~9

NOTE

主动触发器本身不配冷却, 冷却由技能定义中的 cooldown_ticks 和 global_cooldown_ticks 控制

triggers 配置 ​

yaml
triggers:
  left_click:
    display_name: "[左键]"
    enabled: true
    incompatible_with:
      - shift_left_click
字段类型必填默认值取值范围说明
triggers.<id>map否内置默认定义—触发器 id 就是键名. 写成标量值时这个键会被跳过
triggers.<id>.display_namestring否键名; 空白回退 UnknownMiniMessageGUI 和 ActionBar 里显示的触发器名
triggers.<id>.enabledboolean否truetrue / false关掉后这个触发器不再派发, 也不能在 GUI 里绑定
triggers.<id>.incompatible_withlist<\string>否[]触发器 id 列表声明和它互斥的触发器; 互斥是双向的 (见下文触发器的冲突处理)

主动触发器全局设置 ​

yaml
trigger_settings:
  # 启用后仍分发已被 Bukkit 取消的事件; 关闭可避免保护插件拦截后继续耗能或施法
  legacy_dispatch_cancelled_events: false
字段类型必填默认值取值范围说明
trigger_settings.legacy_dispatch_cancelled_eventsboolean否falsetrue / false是否仍然分发已被 Bukkit 取消的交互 / 丢弃 / 切换物品栏事件. 默认 false: 事件被取消时不再派发, 免得被保护类插件拦下后还在耗能或施法; 改成 true 会恢复旧行为, 并在启用时输出一次弃用警告

被动触发器 ​

被动技能只要用 trigger_type: passive 和 passive_triggers 列表声明即可. 列表里的事件一发生, 插件就会自动尝试释放

yaml
id: lifesteal_passive
trigger_type: passive
passive_triggers:
  - attack
cooldown_ticks: 60

完整被动触发器列表 ​

触发器触发时机
attack攻击命中实体 (弹射物造成的攻击也算)
damaged受到任何伤害
damaged_by_entity被实体伤害
death玩家死亡
kill_entity击杀非玩家实体
kill_player击杀玩家
shoot_bow射出弓箭
arrow_hit箭矢命中实体
arrow_land箭矢落地 (没有命中)
shoot_trident掷出三叉戟
trident_hit三叉戟命中实体
trident_land三叉戟落地
break_block破坏方块
place_block放置方块
drop_item丢弃物品
shift_drop_itemShift + 丢弃物品
swap_items交换主副手
shift_swap_itemsShift + 交换主副手
login玩家登录
sneak开始潜行 (只在按下的那一刻, 不包括停止潜行)
teleport传送
timer定时触发 (间隔由 passive_trigger_settings.timer_interval_ticks 控制)
combo_attack连击触发. 连续攻击的间隔不超过 passive_trigger_settings.combo_timeout_ticks 时累计连击状态, 并在派发时提供 %combo_count%

consume 需要自行在 config.yml 注册

监听器会为 PlayerItemConsumeEvent (吃下食物或饮料) 派发 consume, 但 consume 既不在内置默认触发器里, 也不在随插件发货的 config.yml > passive_triggers 里. 没注册的触发器在派发时被直接丢掉, 所以你只写 passive_triggers: [consume] 不会有任何效果, 也不会报错

想启用它, 先在 config.yml > passive_triggers 下补一节:

yaml
passive_triggers:
  consume:
    display_name: "[进食]"
    enabled: true
    incompatible_with: []

passive_triggers 配置 ​

yaml
passive_triggers:
  attack:
    display_name: "[攻击命中]"
    enabled: true
字段类型必填默认值取值范围说明
passive_triggers.<id>map否内置默认定义—被动触发器 id 就是键名. 写成标量值时这个键会被跳过
passive_triggers.<id>.display_namestring否键名; 空白回退 UnknownMiniMessage显示名. 被动触发器不能让玩家在 GUI 里绑定, 这个值主要用来展示
passive_triggers.<id>.enabledboolean否truetrue / false关掉后这个被动触发器不再派发
passive_triggers.<id>.incompatible_withlist<\string>否[]触发器 id 列表和主动触发器含义一样. 被动触发器不用玩家绑定, 留空就行

被动触发器全局设置 ​

yaml
passive_trigger_settings:
  # timer 的检查间隔, 单位: tick; 小于 1 的值会按 1 处理
  timer_interval_ticks: 20
  # combo_attack 的超时, 单位: tick; 超时未攻击时重置连击计数
  combo_timeout_ticks: 60
字段类型必填默认值取值范围说明
passive_trigger_settings.timer_interval_ticksinteger否20≥ 1, 小于 1 按 1timer 被动触发器的检查间隔, 单位 tick
passive_trigger_settings.combo_timeout_ticksinteger否60≥ 1, 小于 1 按 1combo_attack 连击状态的超时, 单位 tick; 超过这个间隔没攻击就重置连击计数

Cron 被动触发器 ​

技能定义里填了 cron_expression 时, 插件会自动注册一个 ID 为 cron_<技能 id> 的被动触发器, 并把它加进这个技能的 passive_triggers, 你不用手写. 表达式格式和 spawn_rules 的 cron 一样, 见 CoreLib 表达式 - Cron 表达式. cron_max_executions 限制总共能触发几次, 0 表示不限. 表达式不合法时会记一条警告, 并跳过这个技能

触发器冲突解决 ​

触发器之间可以声明互斥关系, 用 incompatible_with 写, 而且是双向的:

  • 每个触发器和它自己冲突 (同一个触发器不能绑两个技能)
  • 互斥的两个触发器不能同时绑技能 (比如 left_click 和 shift_left_click)

冲突关系在配置加载时就算好了, 玩家在 GUI 里绑定时插件会自动检查冲突. 内置默认触发器声明了四组互斥: left_click ↔ shift_left_click, right_click ↔ shift_right_click

施法模式 ​

想放主动技能, 先进入施法模式

yaml
cast_mode:
  # 入口固定为 F; enabled 仅控制 F 键切换, 不是施法模式总开关
  entry_key: "f"
  # false 时 F 恢复原版换手, 命令和 GUI 仍可切换
  enabled: true
  # 玩家重新加入后是否恢复上次的施法模式状态
  restore_last_state_on_join: true
字段类型必填默认值取值范围说明
cast_mode.entry_keystring否"f"恒为 f入口键. 源码在构造配置时把它固定写成 f, 配置里填别的值不会生效
cast_mode.enabledboolean否truetrue / false是否启用 F 键切换施法模式. 填 false 时 F 键恢复原版换手, 命令和 GUI 仍然能切换
cast_mode.restore_last_state_on_joinboolean否truetrue / false玩家重新进服后是否恢复上次的施法模式状态
  • 默认是按 F 键切换施法模式
  • 施法模式开启后, 主动触发器才会监听左键, 右键, Q 键, 数字键这些服务端能看到的操作; 你没进施法模式时, 这些操作不会派发技能
  • 施法模式下 ActionBar 显示技能槽信息, 模板和变量见 技能状态栏

配置示例 ​

主动技能 ​

yaml
id: fireball
trigger_type: active
display_name: '<red>火球术'
cooldown_ticks: 100
global_cooldown_ticks: 20
resource_costs:
  - type: ea-resource
    target_id: mana
    amount: 20
    operation: consume

玩家在 GUI 里把火球术绑到 right_click 槽位, 进施法模式后右键就能释放

被动技能 ​

yaml
id: thorns_aura
trigger_type: passive
passive_triggers:
  - damaged_by_entity
display_name: '<yellow>荆棘反击'
cooldown_ticks: 40

被实体伤害时它会自动触发, 并受 cooldown_ticks 冷却限制

定时被动 ​

yaml
id: regen_aura
trigger_type: passive
passive_triggers:
  - timer
display_name: '<green>恢复光环'
cooldown_ticks: 0
resource_costs:
  - type: ea-resource
    target_id: mana
    amount: 5
    operation: consume

它会按全局 timer_interval_ticks 的间隔自动触发

连击被动 ​

combo_attack 派发时会在触发调用里带上 combo_count (这次的连击计数), 技能可以用它做条件或变量判断. 随插件发货的 skills/example_combo_skill.yml 就用条件块读取了它:

yaml
id: combo_finisher
trigger_type: passive
passive_triggers:
  - combo_attack
condition:
  type: all_of
  entries:
    - "%combo_count% >= 5"
cooldown_ticks: 100

条件表达式里的 %...% 必须能被 PlaceholderAPI 解析, 细节见 技能定义 - condition 条件块. combo_attack 把刚被攻击的实体当作目标和范围中心