触发器

Item 触发器用于让物品在特定事件发生时执行动作。适合制作传送卷轴、药水、任务物品、右键技能道具和装备被动效果。

配置格式

触发器配置在物品定义文件的 actions 块下，格式为触发器名称对应动作列表：

id: town_scroll
item:
  source: minecraft-paper
  components:
    custom_name: "<aqua>回城卷轴</aqua>"
actions:
  right_click:
    - 'sendmessage text="<green>正在传送回城。</green>"'
    - "playsound sound=minecraft:entity.enderman.teleport volume=1 pitch=1"
  consume:
    - "playsound sound=minecraft:entity.player.burp volume=1 pitch=1"

每个触发器名称对应一个动作列表。动作语法参见 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
damaged_by_entity	被实体伤害。	attacker、damage
damaged	受到非实体来源的伤害（摔落、火焰等）。	damage
kill_entity	击杀非玩家实体。	target
kill_player	击杀玩家。	target
death	玩家死亡。	—

attack、kill_entity、kill_player、damaged 等判定基于玩家主手物品。近战攻击、玩家发射的投射物命中，以及由玩家造成的致命伤害都会被视为玩家攻击。

投射物类

触发器	触发时机	上下文变量
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	丢弃物品（Q 键）。	—
shift_drop	Shift + 丢弃物品。	—
swap_hand	交换主副手（F 键）。	—
shift_swap_hand	Shift + 交换主副手。	—
consume	物品被消耗（食物/药水）。	consumed_item

drop、swap_hand、place_block 和 consume 判定的是事件涉及的那件物品，而不是当前主手物品。

方块类

触发器	触发时机	上下文变量
break_block	破坏方块。	block
place_block	放置方块。	block

其他

触发器	触发时机	上下文变量
sneak	玩家开始潜行（松开时不触发）。	—
teleport	传送。	—
login	玩家登录。	—
give	通过 /ei give 发放物品时。	amount

上下文变量

触发器触发时会向动作上下文注入变量，可在动作中通过 %变量名% 引用：

actions:
  attack:
    - 'sendmessage text="对 %target% 造成了 %damage% 点伤害"'
  kill_entity:
    - 'sendmessage 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:
    - 'sendmessage text="<red>对 %target% 造成 %damage% 点伤害。</red>"'
  kill_entity:
    - 'sendmessage text="<red>灵魂汲取：%target%</red>"'

消耗品

id: health_potion_large
item:
  source: minecraft-potion
  components:
    custom_name: "<red>大型生命药水</red>"
actions:
  consume:
    - "playsound sound=minecraft:entity.generic.drink volume=1 pitch=1"
    - 'sendmessage text="<green>你饮下了 %item_name%。</green>"'