触发器
Item 触发器用于让物品在特定事件发生时执行动作。适合制作传送卷轴、药水、任务物品、右键技能道具和装备被动效果。
配置格式
触发器配置在物品定义文件的 actions 块下，格式为触发器名称对应动作列表：
id: town_scroll
item:
source: minecraft-paper
components:
custom_name: "<aqua>回城卷轴</aqua>"
actions:
right_click:
- 'send_message text="<green>正在传送回城。</green>"'
- "play_sound sound=minecraft:entity.enderman.teleport volume=1 pitch=1"
consume:
- "play_sound sound=minecraft:entity.player.burp volume=1 pitch=1"NOTE
每个触发器名称对应一个动作列表。动作语法参见 CoreLib 动作系统文档。
完整触发器列表
交互类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
right_click | 玩家右键空气或方块。 | — |
right_click_air | 玩家右键空气。 | — |
right_click_block | 玩家右键方块。 | — |
left_click | 玩家左键空气或方块，以及攻击实体时。 | 攻击实体时为 target、damage |
left_click_air | 玩家左键空气。 | — |
left_click_entity | 玩家攻击实体。 | target、damage |
shift_left_click | Shift + 左键（空气或方块）。 | — |
shift_right_click | Shift + 右键（空气或方块）。 | — |
战斗类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
attack | 玩家攻击实体命中。 | target、damage |
damage_dealt | 玩家造成的伤害结算完毕（最终伤害大于 0）。 | target、damage |
damaged_by_entity | 被实体伤害。 | attacker、damage |
damaged | 受到非实体来源的伤害（摔落、火焰等）。 | damage |
kill_entity | 击杀非玩家实体。 | target |
kill_player | 击杀玩家。 | target |
death | 玩家死亡。 | — |
attack 判定基于玩家主手物品。近战攻击、玩家发射的投射物命中，以及由玩家造成的致命伤害都会被视为玩家攻击。
damage_dealt 在 MONITOR 优先级派发，只在最终伤害大于 0 时执行，因此可以读取到被其他插件修改后的伤害值。
damage_dealt、kill_entity、kill_player 除主手武器外还会遍历护甲槽派发（跳过主手与副手）；damaged、damaged_by_entity 除主手物品外也会遍历其他装备槽派发（跳过主手）。额外派发的条件是该物品定义的 equip_slot 不为 all 且与实际所在槽位匹配，也就是说护甲件同样能收到这些战斗触发器。
投射物类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
shoot_bow | 射出弓箭。 | projectile_type |
shoot_trident | 掷出三叉戟。 | projectile_type |
arrow_hit | 箭矢命中实体。 | projectile_type |
arrow_land | 箭矢未命中实体。 | projectile_type |
trident_hit | 三叉戟命中实体。 | projectile_type |
trident_land | 三叉戟未命中实体。 | projectile_type |
投射物触发在命中时读取玩家当前主手物品，因此换手后可能不再匹配发射时的物品。
物品操作类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
drop_item | 丢弃物品（Q 键）。 | — |
shift_drop_item | Shift + 丢弃物品。 | — |
swap_items | 交换主副手（F 键）。 | — |
shift_swap_items | Shift + 交换主副手。 | — |
consume | 物品被消耗（食物/药水）。 | consumed_item |
drop_item、swap_items、place_block 和 consume 判定的是事件涉及的那件物品，而不是当前主手物品。
WARNING
触发器名称必须逐字写对，插件不提供别名兼容：actions 下的键只会被转成小写并把空格换成下划线，未注册的名称会被静默忽略且不告警。
方块类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
break_block | 破坏方块。 | block |
place_block | 放置方块。 | block |
其他
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
sneak | 玩家开始潜行（松开时不触发）。 | — |
teleport | 传送。 | — |
login | 玩家登录。 | — |
give | 通过 /ei give 发放物品时。 | amount |
上下文变量
触发器触发时会向动作上下文注入变量，可在动作中通过 %变量名% 引用：
actions:
attack:
- 'send_message text="对 %target% 造成了 %damage% 点伤害"'
kill_entity:
- 'send_message text="击杀了 %target%"'所有触发器都会注入以下基础变量：
| 变量 | 说明 |
|---|---|
player | 玩家名称。 |
item_id | 物品 ID。 |
item_trigger | 触发器名称。 |
item_name | 物品显示名。 |
条件与禁用状态
物品定义的 condition 会在每个触发器执行前求值：不满足时该触发器不执行，并发送 on_fail.message、执行 on_fail.actions；满足时执行 on_pass.actions。
当物品启用了 repair 且主手物品处于禁用状态（耐久归零）时，触发器不会执行。详见物品修复系统。
配置示例
攻击吸血武器
id: vampire_blade
item:
source: minecraft-netherite_sword
components:
custom_name: "<dark_red>吸血之刃</dark_red>"
actions:
attack:
- 'send_message text="<red>对 %target% 造成 %damage% 点伤害。</red>"'
kill_entity:
- 'send_message text="<red>灵魂汲取：%target%</red>"'消耗品
id: health_potion_large
item:
source: minecraft-potion
components:
custom_name: "<red>大型生命药水</red>"
actions:
consume:
- "play_sound sound=minecraft:entity.generic.drink volume=1 pitch=1"
- 'send_message text="<green>你饮下了 %item_name%。</green>"'