触发器
Item 触发器用于让物品在特定事件发生时执行动作。适合制作传送卷轴、药水、任务物品、右键技能道具和装备被动效果。
配置格式
触发器配置在物品定义文件的 actions 块下，格式为触发器名称对应动作列表：
yaml
id: town_scroll
display_name: '<aqua>回城卷轴'
material: PAPER
actions:
right_click:
- 'sendmessage text="<green>正在传送回城。"'
- 'teleport world=world x=0 y=64 z=0'
consume:
- 'playsound sound=ENTITY_PLAYER_BURP'每个触发器名称对应一个动作列表。动作语法参见 CoreLib 动作系统文档。
完整触发器列表
交互类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
right_click | 玩家右键（含空气和方块）。 | — |
right_click_air | 玩家右键空气。 | — |
right_click_block | 玩家右键方块。 | — |
left_click | 玩家左键（含空气和实体）。 | — |
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 | 玩家死亡。 | — |
投射物类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
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 |
方块类
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
break_block | 破坏方块。 | block |
place_block | 放置方块。 | block |
其他
| 触发器 | 触发时机 | 上下文变量 |
|---|---|---|
sneak | 潜行切换。 | — |
teleport | 传送。 | — |
login | 玩家登录。 | — |
give | 通过命令发放物品时。 | amount |
上下文变量
触发器触发时会向动作上下文注入变量，可在动作中通过 {变量名} 引用：
yaml
actions:
attack:
- 'sendmessage text="对 %target% 造成了 %damage% 点伤害"'
kill_entity:
- 'sendmessage text="击杀了 %target%"'所有触发器都会注入以下基础变量：
| 变量 | 说明 |
|---|---|
player | 玩家名称。 |
item_id | 物品 ID。 |
item_trigger | 触发器名称。 |
item_name | 物品显示名。 |
禁用状态
当物品处于修复禁用状态（耐久归零）时，所有触发器不会触发。详见物品修复系统文档。
配置示例
右键传送卷轴
yaml
id: town_scroll
display_name: '<aqua>回城卷轴'
material: PAPER
actions:
right_click:
- 'sendmessage text="<green>正在传送回城。"'
- 'teleport world=world x=0 y=64 z=0'
consume:
- 'playsound sound=ENTITY_PLAYER_BURP'攻击吸血武器
yaml
id: vampire_blade
display_name: '<dark_red>吸血之刃'
material: NETHERITE_SWORD
actions:
attack:
- '@chance=30% heal amount=3'
- '@chance=30% spawnparticle particle=DAMAGE_INDICATOR count=5'
kill_entity:
- 'heal amount=10'
- 'sendmessage text="<red>灵魂汲取！"'潜行触发护盾
yaml
id: shield_amulet
display_name: '<gold>护盾护符'
material: TOTEM_OF_UNDYING
actions:
sneak:
- '@if="%resource_mana% >= 20" sendmessage text="<gold>护盾激活！"'