动作系统

动作系统用于在 YAML 中描述“发生某件事后要执行哪些效果”。它是 CoreLib 最常被业务模块调用的能力之一，常见于：

• 锻造成功后发送消息、播放音效、发放奖励。
• 强化失败后显示 Title、执行惩罚动作。
• 技能释放时扣资源、执行命令、触发 MythicMobs 技能。
• 烹饪完成后发放物品、广播提示、播放粒子。
• GUI 按钮点击后打开界面、执行命令或触发业务流程。

动作列表的基本写法

不同模块的字段名可能不同，例如 action.success、actions、deny_actions、result.action。但核心思想一致：一个动作列表按顺序执行。

动作行由“控制前缀 + 动作 ID + 参数”组成：

@chance=25% @delay=20t sendmessage text="<green>触发成功</green>"

推荐统一使用 key=value 参数写法。参数值包含空格、MiniMessage 标签、命令空格或 YAML 特殊字符时，请加引号。

action:
  success:
    - 'sendmessage text="<green>锻造成功！</green>"'
    - 'playsound sound=minecraft:entity.player.levelup volume=1 pitch=1'
    - 'runcommandasconsole command="say %player_name% 完成了一次锻造"'

动作执行前会先解析占位符。CoreLib 自带 %player_name%、%player_uuid%、%player_world%、%player_x%、%player_y%、%player_z%、%phase%，并会解析调用模块写入 ActionContext 的其他占位符。各模块可用的业务变量请参阅对应模块文档。

动作行语法细节

• 空行与以 # 开头的行会被忽略。
• 动作 ID 会转成小写；如果写成带下划线但注册项不带下划线，报错会提示使用无下划线版本，例如 send_message 应改为 sendmessage。
• 参数必须写成 key=value。没有 = 的参数 token 会被视为语法错误。
• 同一个动作行内重复参数会报错。
• 单引号和双引号都可用于包裹参数值。被引号包裹时支持 \n、\t、\\、\"、\' 转义。
• createitem、clearitem、dropitem、placeblock、runjs、usetemplate 支持动态参数，详见下文。

参数类型说明

动作参数有以下类型，在后续参数表中会标注：

类型	说明	示例
STRING	字符串。含空格或特殊字符时需加引号。	text="<green>成功"
INTEGER	整数。	amount=3、count=10
DOUBLE	浮点数。	volume=0.8、amount=25.5
BOOLEAN	布尔值。true/false。	keep=false、silent=true
TIME	时间值。支持 t（tick）、s（秒）、ms（毫秒），纯数字视为 tick。	20t、1s、500ms

控制前缀

控制前缀写在动作 ID 之前，用于控制动作是否执行、何时执行、失败时是否继续。每个前缀只能出现一次，重复会报语法错误。未知的 @xxx 前缀也会报错。

前缀	值类型	说明
@if=<expression>	布尔表达式	表达式为真时才执行。表达式会先经过占位符解析，再交给条件/表达式系统判断。
@chance=<number>	数值或百分比	按概率执行。支持 0~1 小数，也支持百分号，例如 0.25 与 25% 都表示 25%。
@delay=<time>	TIME	延迟执行。支持纯数字 tick、t、s、ms，例如 20、20t、1s、500ms。
@ignore_failure	无值	该动作失败时不阻断后续动作。直接写 @ignore_failure，不需要 =。

示例：

actions:
  - '@chance=0.1 broadcastmessage text="<gold>%player_name% 触发了稀有奖励！</gold>"'
  - '@chance=25% givemoney amount=100 provider=vault'
  - '@delay=1s sendmessage text="<gray>1 秒后发送的提示"'
  - '@if=%player_world%=="world" sendmessage text="你在主世界"'
  - '@ignore_failure runcommandasconsole command="papi parse %player_name% %some_placeholder%"'

@if 的写法

@if 最终使用 CoreLib 条件/表达式系统求布尔值，常见写法包括：

- '@if=%phase%=="success" sendmessage text="成功阶段"'
- '@if=%player_world%!="world_nether" sendmessage text="不在下界"'
- '@if=1 sendmessage text="数字大于 0 时视为 true"'
- '@if=true sendmessage text="布尔字面量"'

布尔表达式支持 &&、||、!、括号、比较运算符 <、<=、==、!=、>=、>。字符串比较建议给右侧字符串加引号，避免和数字表达式混淆。

内置动作 ID 与参数

下表列出 CoreLib 直接注册的内置动作。标记为“需要玩家上下文”的动作必须由带玩家的业务事件触发；控制台或无玩家上下文中执行会失败。

消息与反馈

sendmessage

向玩家发送 MiniMessage 格式聊天消息。需要玩家上下文。

参数	类型	必填	默认值	说明
text	STRING	是	—	MiniMessage 格式的消息文本。

actions:
  # 基础消息
  - 'sendmessage text="<green>操作成功！</green>"'
  # 带占位符的消息
  - 'sendmessage text="<yellow>欢迎回来，%player_name%！</yellow>"'
  # 复杂 MiniMessage 格式（渐变色 + 悬浮提示）
  - 'sendmessage text="<hover:show_text:''点击查看详情''><click:run_command:/menu><gradient:gold:yellow>打开菜单</gradient></click></hover>"'

sendtitle

向玩家发送 Title（大标题 + 副标题）。需要玩家上下文。

参数	类型	必填	默认值	说明
title	STRING	是	—	主标题（MiniMessage 格式）。
subtitle	STRING	否	""	副标题（MiniMessage 格式）。
fade_in	TIME	否	10t	淡入时间。
stay	TIME	否	40t	停留时间。
fade_out	TIME	否	10t	淡出时间。

actions:
  # 基础 Title
  - 'sendtitle title="<gold>任务完成</gold>" subtitle="<gray>获得经验奖励</gray>"'
  # 自定义时间参数
  - 'sendtitle title="<red>警告</red>" subtitle="<yellow>你即将进入危险区域</yellow>" fade_in=5t stay=60t fade_out=20t'
  # 仅显示主标题（快速闪烁效果）
  - 'sendtitle title="<bold><gold>LEVEL UP!</gold></bold>" fade_in=0t stay=20t fade_out=5t'

sendactionbar

向玩家发送 ActionBar 消息。需要玩家上下文。

参数	类型	必填	默认值	说明
text	STRING	是	—	MiniMessage 格式的 ActionBar 文本。

actions:
  # 基础 ActionBar
  - 'sendactionbar text="<green>+50 经验</green>"'
  # 带图标的状态提示
  - 'sendactionbar text="<yellow>⚔ 战斗模式已激活 ⚔</yellow>"'
  # 进度提示
  - 'sendactionbar text="<gray>烹饪进度：<green>████</green><dark_gray>██████</dark_gray> 40%</gray>"'

broadcastmessage

向全服广播 MiniMessage 消息。不需要玩家上下文。

参数	类型	必填	默认值	说明
text	STRING	是	—	MiniMessage 格式的广播文本。

actions:
  # 全服公告
  - 'broadcastmessage text="<gold>[公告] <white>服务器将在 5 分钟后重启</white></gold>"'
  # 玩家成就广播
  - 'broadcastmessage text="<light_purple>✦ %player_name% 完成了传说级锻造！✦</light_purple>"'

playsound

在玩家当前位置播放声音。需要玩家上下文。

参数	类型	必填	默认值	说明
sound	STRING	是	—	声音键名。可写 Bukkit Sound 枚举名或 minecraft: 风格键。
volume	DOUBLE	否	1	音量（0 以上，大于 1 时增加可听距离）。
pitch	DOUBLE	否	1	音调（0.5–2.0，1 为正常音调）。

actions:
  # 升级音效
  - 'playsound sound=minecraft:entity.player.levelup volume=1 pitch=1'
  # 经验球拾取音效（高音调）
  - 'playsound sound=minecraft:entity.experience_orb.pickup volume=0.8 pitch=1.5'
  # 铁砧使用音效（低音调，大音量远距离可听）
  - 'playsound sound=minecraft:block.anvil.use volume=2 pitch=0.8'
  # 失败音效
  - 'playsound sound=minecraft:entity.villager.no volume=1 pitch=1'

spawnparticle

生成粒子效果。target=player 时需要玩家上下文。

参数	类型	必填	默认值	说明
particle	STRING	是	—	粒子键名（Bukkit Particle 枚举名）。
count	INTEGER	否	1	粒子数量。
target	STRING	否	player	生成位置模式：player（玩家位置）或 location（指定坐标）。
world	STRING	否	""	世界名（仅 target=location 时有效）。
x	STRING	否	""	X 坐标（支持 ~ 相对坐标，仅 target=location）。
y	STRING	否	""	Y 坐标（支持 ~ 相对坐标，仅 target=location）。
z	STRING	否	""	Z 坐标（支持 ~ 相对坐标，仅 target=location）。
offset_x	DOUBLE	否	0	X 轴偏移扩散范围。
offset_y	DOUBLE	否	0	Y 轴偏移扩散范围。
offset_z	DOUBLE	否	0	Z 轴偏移扩散范围。
extra	DOUBLE	否	0	额外参数（速度或数据，依粒子类型而定）。

actions:
  # 玩家位置生成绿色粒子（成功反馈）
  - 'spawnparticle particle=happy_villager count=15 offset_x=0.3 offset_y=0.5 offset_z=0.3'
  # 玩家位置火焰粒子（技能释放）
  - 'spawnparticle particle=flame count=30 offset_x=0.5 offset_y=0.2 offset_z=0.5 extra=0.05'
  # 指定世界坐标生成粒子（不需要玩家上下文）
  - 'spawnparticle particle=end_rod target=location world=world x=100 y=65 z=-30 count=50 offset_x=1 offset_y=2 offset_z=1 extra=0.02'
  # 紧凑爆炸粒子
  - 'spawnparticle particle=explosion count=3 offset_x=0.1 offset_y=0.1 offset_z=0.1'

经济动作

givemoney

给玩家增加余额。需要玩家上下文。

参数	类型	必填	默认值	说明
amount	DOUBLE	是	—	给予金额。
provider	STRING	否	auto	经济提供者。可选：auto、vault、excellenteconomy。
currency	STRING	否	""	货币类型。ExcellentEconomy 多货币时必须指定。

actions:
  # 基础给钱（自动选择经济插件）
  - 'givemoney amount=100'
  # 指定 Vault 经济
  - 'givemoney amount=500 provider=vault'
  # ExcellentEconomy 多货币
  - 'givemoney amount=50 provider=excellenteconomy currency=gems'

takemoney

扣除玩家余额。需要玩家上下文。余额不足时动作失败。

参数	类型	必填	默认值	说明
amount	DOUBLE	是	—	扣除金额。
provider	STRING	否	auto	经济提供者。
currency	STRING	否	""	货币类型。

actions:
  # 扣除金币
  - 'takemoney amount=25.5 provider=vault'
  # 扣除自定义货币
  - 'takemoney amount=10 provider=excellenteconomy currency=coins'
  # 配合 @ignore_failure 避免余额不足阻断后续动作
  - '@ignore_failure takemoney amount=200 provider=auto'

setmoney

设置玩家余额为指定值。需要玩家上下文。

参数	类型	必填	默认值	说明
amount	DOUBLE	是	—	目标余额。
provider	STRING	否	auto	经济提供者。
currency	STRING	否	""	货币类型。

actions:
  # 重置玩家余额
  - 'setmoney amount=0 provider=vault'
  # 设置为固定值
  - 'setmoney amount=1000 provider=auto'

临时物品动作

createitem 会创建一个临时物品并放入当前动作上下文的临时仓库，随后用 senditem 发给玩家。临时物品只在本次动作链上下文中使用，不是持久物品库。

createitem

根据物品来源创建临时物品。不需要玩家上下文。支持动态参数 item、item_source 作为 source 的别名。

参数	类型	必填	默认值	说明
id	STRING	是	—	临时物品 ID（用于后续 senditem 引用）。
source	STRING	是*	""	物品来源（ItemSource 简写格式）。也可用 item= 或 item_source= 替代。
amount	INTEGER	否	1	物品数量（最小为 1）。

*source、item、item_source 三者至少需要一个有效值。

actions:
  # 创建原版钻石
  - 'createitem id=diamond_reward source=minecraft:diamond amount=5'
  # 创建自定义物品（EmakiItem 来源）
  - 'createitem id=special_sword item=emakiitem-flame_sword amount=1'
  # 创建 ItemsAdder 物品
  - 'createitem id=custom_gem item_source=itemsadder-ruby_gem amount=3'

senditem

将临时物品发给玩家。需要玩家上下文。背包满时物品掉落在玩家附近。

参数	类型	必填	默认值	说明
id	STRING	是	—	临时物品 ID（由 createitem 创建）。
keep	BOOLEAN	否	false	发送后是否保留临时存储中的物品。false 则移除。

actions:
  # 创建并发送物品（标准流程）
  - 'createitem id=reward source=minecraft:golden_apple amount=2'
  - 'senditem id=reward'
  # 保留临时物品（可多次发送同一物品）
  - 'createitem id=token source=minecraft:emerald amount=1'
  - 'senditem id=token keep=true'
  - 'senditem id=token keep=false'

clearitem

清空玩家指定槽位的物品。需要玩家上下文。支持动态参数 item、item_source 作为 source 的别名。

参数	类型	必填	默认值	说明
slot	STRING	是	—	背包槽位（见下方槽位说明）。
source	STRING	否	""	期望的物品来源。指定后只有匹配时才清空，不匹配则跳过。

source 使用 CoreLib 物品来源短写，详见 物品来源，例如原版 minecraft:diamond、自定义来源等。

clearitem.slot 支持：

• mainhand、main_hand、hand
• offhand、off_hand
• helmet、chestplate/chest、leggings/legs、boots
• 背包索引 0 到 35，也可写 slot_0、hotbar_0

actions:
  # 清空主手物品（无条件）
  - 'clearitem slot=mainhand'
  # 仅当主手是木棍时才清空
  - 'clearitem slot=mainhand source=minecraft:stick'
  # 清空副手
  - 'clearitem slot=offhand'
  # 清空头盔槽位（仅匹配自定义物品时）
  - 'clearitem slot=helmet item=emakiitem-cursed_helmet'
  # 清空指定背包格子
  - 'clearitem slot=0'

世界物品与方块动作

dropitem

在指定世界坐标掉落一个物品来源创建出的物品。坐标支持 ~ 相对玩家坐标；没有玩家上下文时必须填写 world，且不能使用 ~。

参数	类型	必填	默认值	说明
source	STRING	是*	""	物品来源。也可用 item= 或 item_source= 替代。
x	STRING	是	—	X 坐标。支持 ~ 相对坐标。
y	STRING	是	—	Y 坐标。支持 ~ 相对坐标。
z	STRING	是	—	Z 坐标。支持 ~ 相对坐标。
world	STRING	否	""	世界名。空则使用玩家当前世界。
amount	INTEGER	否	1	掉落数量（最小为 1）。

actions:
  # 在玩家头顶掉落物品
  - 'dropitem source=minecraft:diamond x=~ y=~2 z=~ amount=1'
  # 在固定坐标掉落奖励（不需要玩家上下文）
  - 'dropitem source=minecraft:gold_ingot world=world x=100 y=65 z=-50 amount=5'
  # 掉落自定义物品
  - 'dropitem item=nexo-reward_coin x=~ y=~1 z=~ amount=3'
  # 在玩家前方掉落
  - 'dropitem source=minecraft:emerald x=~3 y=~ z=~ amount=2'

placeblock

在指定方块坐标放置物品来源对应的方块。支持原版方块以及 CraftEngine、ItemsAdder、Nexo 自定义方块。若来源不是可放置方块，动作会跳过而不是中断后续动作。有玩家上下文时会触发 Bukkit 放置事件，保护插件取消时不会放置。

参数	类型	必填	默认值	说明
source	STRING	是*	""	方块物品来源。也可用 item= 或 item_source= 替代。
x	STRING	是	—	X 坐标。支持 ~ 相对坐标。
y	STRING	是	—	Y 坐标。支持 ~ 相对坐标。
z	STRING	是	—	Z 坐标。支持 ~ 相对坐标。
world	STRING	否	""	世界名。空则使用玩家当前世界。

*source、item、item_source 三者至少需要一个有效值。

actions:
  # 放置原版方块（注意使用连字符分隔命名空间和 ID）
  - 'placeblock source=minecraft-stone world=world x=100 y=64 z=-20'
  # 在玩家脚下放置方块
  - 'placeblock source=minecraft-oak_planks x=~ y=~-1 z=~'
  # 放置 CraftEngine 自定义方块
  - 'placeblock source=ce-cutting_board x=~1 y=~ z=~'
  # 放置 ItemsAdder 自定义方块
  - 'placeblock item=itemsadder-decorative_lamp x=~ y=~2 z=~'
  # 在固定坐标放置（无玩家上下文）
  - 'placeblock source=minecraft-chest world=world x=50 y=70 z=100'

玩家状态与传送

teleport

传送玩家到指定坐标。需要玩家上下文。

参数	类型	必填	默认值	说明
x	STRING	是	—	X 坐标。支持 ~ 相对当前坐标（如 ~5 表示当前 X+5）。
y	STRING	是	—	Y 坐标。支持 ~ 相对坐标。
z	STRING	是	—	Z 坐标。支持 ~ 相对坐标。
world	STRING	否	""	目标世界名。空则使用玩家当前世界。
yaw	DOUBLE	否	玩家当前朝向	偏航角（水平朝向，0–360）。缺省时保留玩家当前朝向。
pitch	DOUBLE	否	玩家当前朝向	俯仰角（垂直朝向，-90–90）。缺省时保留玩家当前朝向。

actions:
  # 传送到固定坐标
  - 'teleport world=world x=0 y=100 z=0 yaw=180 pitch=0'
  # 相对传送（向上 10 格）
  - 'teleport x=~ y=~10 z=~'
  # 跨世界传送
  - 'teleport world=world_nether x=50 y=64 z=-100 yaw=90 pitch=0'
  # 传送到出生点附近（面朝南方）
  - 'teleport world=world x=0 y=65 z=0 yaw=0 pitch=0'

heal

治疗玩家。需要玩家上下文。治疗后生命不超过最大生命值。

此动作直接设置生命值，不触发 Bukkit EntityRegainHealthEvent。不受任何治疗加成或减免影响。

参数	类型	必填	默认值	说明
amount	DOUBLE	是	—	治疗量（半心为单位，1 = 半颗心）。

actions:
  # 治疗 4 点（2 颗心）
  - 'heal amount=4'
  # 满血治疗（设置一个很大的值，会自动 clamp 到最大生命）
  - 'heal amount=9999'
  # 少量治疗（配合概率使用）
  - '@chance=30% heal amount=2'

damage

扣除玩家生命。需要玩家上下文。扣除后生命最低为 0。

此动作直接设置生命值，不触发 Bukkit EntityDamageEvent。不受护甲、抗性、附魔等任何减免影响，也不会导致玩家死亡（最低为 0）。

参数	类型	必填	默认值	说明
amount	DOUBLE	是	—	伤害量。

actions:
  # 扣除 2 点生命（1 颗心）
  - 'damage amount=2'
  # 惩罚性伤害
  - 'damage amount=6'
  # 配合条件使用
  - '@if=%player_world%=="world_nether" damage amount=1'

sethealth

设置玩家生命值。需要玩家上下文。自动限制在 0 到最大生命值之间。

参数	类型	必填	默认值	说明
amount	DOUBLE	是	—	目标生命值。

actions:
  # 设置为满血（20 = 10 颗心）
  - 'sethealth amount=20'
  # 设置为半血
  - 'sethealth amount=10'
  # 设置为 1 点（半颗心，濒死状态）
  - 'sethealth amount=1'

经验与药水效果

giveexp

增加玩家经验。需要玩家上下文。

参数	类型	必填	默认值	说明
amount	INTEGER	是	—	增加的经验点数或等级数。
mode	STRING	否	points	模式：points（经验点数）或 levels（等级）。

actions:
  # 给予 100 经验点
  - 'giveexp amount=100 mode=points'
  # 给予 3 个等级
  - 'giveexp amount=3 mode=levels'
  # 默认模式为 points，可省略
  - 'giveexp amount=50'

takeexp

扣除玩家经验。需要玩家上下文。扣除后最低为 0。

参数	类型	必填	默认值	说明
amount	INTEGER	是	—	扣除的经验点数或等级数。
mode	STRING	否	points	模式：points 或 levels。

actions:
  # 扣除 200 经验点
  - 'takeexp amount=200 mode=points'
  # 扣除 1 个等级
  - 'takeexp amount=1 mode=levels'
  # 作为锻造消耗
  - 'takeexp amount=30'

setexp

设置玩家总经验或等级。需要玩家上下文。

参数	类型	必填	默认值	说明
amount	INTEGER	是	—	目标经验点数或等级。
mode	STRING	否	points	模式：points 或 levels。

actions:
  # 设置等级为 30
  - 'setexp amount=30 mode=levels'
  # 清空所有经验
  - 'setexp amount=0 mode=points'
  # 设置为固定经验值
  - 'setexp amount=1000 mode=points'

givepotioneffect

给玩家添加药水效果。需要玩家上下文。

参数	类型	必填	默认值	说明
type	STRING	是	—	药水效果类型。可写 speed、minecraft:strength 等。
level	INTEGER	是	—	效果等级。1 对应 Bukkit amplifier 0（即游戏内"I 级"）。
duration	TIME	是	—	持续时间。如 100t、5s、10000ms。
ambient	BOOLEAN	否	false	是否为环境效果（粒子更稀疏、更透明）。
particles	BOOLEAN	否	true	是否显示粒子。
icon	BOOLEAN	否	true	是否在 HUD 显示效果图标。

actions:
  # 速度 II 持续 30 秒
  - 'givepotioneffect type=speed level=2 duration=30s particles=true icon=true'
  # 力量 I 持续 1 分钟（无粒子，更隐蔽）
  - 'givepotioneffect type=strength level=1 duration=60s particles=false icon=true'
  # 夜视（环境效果，粒子稀疏）
  - 'givepotioneffect type=night_vision level=1 duration=5s ambient=true'
  # 使用 minecraft: 前缀写法
  - 'givepotioneffect type=minecraft:regeneration level=3 duration=10s'
  # 抗性提升（无图标无粒子，完全隐藏）
  - 'givepotioneffect type=resistance level=1 duration=20s particles=false icon=false'

removepotioneffect

移除玩家指定药水效果。需要玩家上下文。

参数	类型	必填	默认值	说明
type	STRING	是	—	药水效果类型。

actions:
  # 移除缓慢效果
  - 'removepotioneffect type=slowness'
  # 移除中毒
  - 'removepotioneffect type=poison'
  # 使用 minecraft: 前缀
  - 'removepotioneffect type=minecraft:weakness'

clearpotioneffects

清除玩家所有当前药水效果。需要玩家上下文。无参数。

actions:
  # 清除所有药水效果（净化）
  - 'clearpotioneffects'
  # 配合延迟使用
  - '@delay=2s clearpotioneffects'
  # 配合条件使用（仅在特定世界清除）
  - '@if=%player_world%=="world_arena" clearpotioneffects'

命令动作

runcommandasplayer

以玩家身份执行命令。需要玩家上下文。受玩家权限限制。

参数	类型	必填	默认值	说明
command	STRING	是	—	要执行的命令（不含开头 /）。

actions:
  # 让玩家执行 /spawn 命令
  - 'runcommandasplayer command="spawn"'
  # 打开菜单
  - 'runcommandasplayer command="menu open main"'
  # 带占位符
  - 'runcommandasplayer command="msg %player_name% 你好"'

runcommandasop

临时给予玩家 OP 执行命令，执行后恢复原 OP 状态。需要玩家上下文。

参数	类型	必填	默认值	说明
command	STRING	是	—	要执行的命令（不含开头 /）。

注意：runcommandasop 会临时赋予 OP 权限，存在安全风险。建议优先使用 runcommandasconsole 或权限插件临时授权。

actions:
  # 临时 OP 执行权限命令
  - 'runcommandasop command="lp user %player_name% permission set example.vip true"'
  # 给予物品（需要 OP 权限的命令）
  - 'runcommandasop command="give %player_name% diamond 1"'

runcommandasconsole

以控制台身份执行命令。不需要玩家上下文（但占位符仍会解析）。

参数	类型	必填	默认值	说明
command	STRING	是	—	要执行的命令（不含开头 /）。

命令参数会自动去掉开头的 /。但为了可读性和兼容性，建议配置中不要写 /。

actions:
  # 全服公告
  - 'runcommandasconsole command="say %player_name% 完成了一次锻造"'
  # 给予权限
  - 'runcommandasconsole command="lp user %player_name% permission set forge.master true"'
  # 执行其他插件命令
  - 'runcommandasconsole command="crate give %player_name% legendary 1"'
  # 踢出玩家（惩罚动作）
  - 'runcommandasconsole command="kick %player_name% 违规操作"'

动作模板

当多个地方都需要执行同一组动作时，建议使用动作模板，再通过 usetemplate 调用。

模板定义在 CoreLib 主配置：

action:
  templates:
    reward_common:
      - 'sendmessage text="<green>领取奖励成功</green>"'
      - 'playsound sound=minecraft:entity.experience_orb.pickup volume=0.8 pitch=1.2'
    level_up_effect:
      - 'sendtitle title="<gold>等级提升！</gold>" subtitle="<gray>当前等级：%template_level%</gray>"'
      - 'playsound sound=minecraft:entity.player.levelup volume=1 pitch=1'
      - 'spawnparticle particle=totem_of_undying count=30 offset_x=0.5 offset_y=1 offset_z=0.5'

调用模板：

actions:
  - 'usetemplate name=reward_common'

usetemplate 参数：

参数	说明
name	必填。模板 ID，不区分大小写。
with.<key>	动态参数。会注入为模板内可用占位符 %template_<key>%。

actions:
  # 基础调用
  - 'usetemplate name=reward_common'
  # 带动态参数
  - 'usetemplate name=level_up_effect with.level=10'
  # 多个动态参数
  - 'usetemplate name=reward_with_amount with.amount=100 with.reason=锻造奖励'

带动态参数的模板定义示例：

action:
  templates:
    reward_with_amount:
      - 'sendmessage text="<green>获得 %template_amount% 金币（%template_reason%）</green>"'
      - 'givemoney amount=%template_amount%'

# 调用
actions:
  - 'usetemplate name=reward_with_amount with.amount=100 with.reason=每日签到'
  - 'usetemplate name=reward_with_amount with.amount=500 with.reason=首次通关'

模板最大嵌套深度为 8，超过会失败，避免循环调用导致无限展开。

MythicMobs 与脚本动作

castmythicskill

通过 MythicMobs API 让玩家释放指定技能。需要玩家上下文。未安装 MythicMobs 时返回失败。

参数	类型	必填	默认值	说明
skill	STRING	是	—	MythicMobs 技能 ID。

actions:
  # 释放火球技能
  - 'castmythicskill skill=FireballSkill'
  # 释放 AOE 技能
  - 'castmythicskill skill=IceStorm'
  # 配合概率触发
  - '@chance=15% castmythicskill skill=LightningStrike'
  # 配合条件触发
  - '@if=%phase%=="critical" castmythicskill skill=BerserkRage'

runjs

执行 CoreLib 脚本目录下的 JavaScript 文件。不强制需要玩家上下文（取决于脚本内容）。异步执行。

参数	类型	必填	默认值	说明
script	STRING	是	—	脚本路径（相对于 plugins/EmakiCoreLib/scripts/）。
function	STRING	否	main	调用的函数名。
timeout	STRING	否	1000（ms）	超时时间。支持 ms/s/t 后缀。受 max_timeout_millis（默认 5000）上限约束。
silent	BOOLEAN	否	false	是否抑制脚本错误日志输出。
arg_<key>	STRING	否	—	传入脚本的自定义参数。脚本内以 key（去掉 arg_ 前缀）访问。

runjs 的别名（可在 config.yml 中配置）：默认包含 runscript、javascript。

actions:
  # 基础脚本调用
  - 'runjs script=examples/hello.js'
  # 指定函数和超时
  - 'runjs script=forge/on_success.js function=onComplete timeout=2s'
  # 传递自定义参数
  - 'runjs script=rewards/calculate.js arg_source=forge arg_quality=%forge_quality% arg_amount=3'
  # 静默模式（不输出错误日志）
  - '@ignore_failure runjs script=optional/analytics.js silent=true'
  # 使用别名
  - 'runscript script=utils/cleanup.js function=run'
  - 'javascript script=custom/handler.js arg_event=craft_complete'

更多脚本 API 见 JavaScript 脚本。

其他模块注册的动作

部分业务模块会在 CoreLib 动作注册表上追加自己的动作：

来源模块	动作 ID	说明
EmakiSkills	castskill	释放 EmakiSkills 技能。
EmakiAttribute	attributedamage、attribute_add、attribute_set、attribute_remove	属性伤害或临时/持久属性变更。
CoreLib 脚本配置	runjs 的别名	默认 runscript、javascript。

这些动作的具体参数请参阅对应模块文档。

动作 ID 速查表

动作 ID	分类	需要玩家	用途
sendmessage	消息	是	发送聊天消息
sendtitle	消息	是	发送 Title
sendactionbar	消息	是	发送 ActionBar
broadcastmessage	消息	否	全服广播
playsound	反馈	是	播放音效
spawnparticle	反馈	视 target	生成粒子
givemoney	经济	是	给予金钱
takemoney	经济	是	扣除金钱
setmoney	经济	是	设置金钱
createitem	物品	否	创建临时物品
senditem	物品	是	发送临时物品
clearitem	物品	是	清除槽位物品
dropitem	物品	视坐标	在指定位置掉落物品
placeblock	世界	视坐标	在指定位置放置方块
teleport	玩家	是	传送
heal	玩家	是	治疗
damage	玩家	是	伤害
sethealth	玩家	是	设置生命
giveexp	玩家	是	给予经验
takeexp	玩家	是	扣除经验
setexp	玩家	是	设置经验
givepotioneffect	玩家	是	添加药水效果
removepotioneffect	玩家	是	移除药水效果
clearpotioneffects	玩家	是	清除所有药水效果
runcommandasplayer	命令	是	以玩家身份执行
runcommandasop	命令	是	以临时 OP 执行
runcommandasconsole	命令	否	以控制台执行
usetemplate	模板	视内容	展开动作模板
castmythicskill	技能	是	释放 MythicMobs 技能
runjs	脚本	否	执行 JavaScript

完整动作链示例

以下是一个锻造成功后的完整动作链配置，展示多种动作的组合使用：

action:
  success:
    # 基础反馈
    - 'sendtitle title="<gold>锻造成功</gold>" subtitle="<gray>品质：%forge_quality%</gray>" fade_in=5t stay=40t fade_out=10t'
    - 'playsound sound=minecraft:block.anvil.use volume=1 pitch=1.2'
    - 'spawnparticle particle=happy_villager count=20 offset_x=0.5 offset_y=0.5 offset_z=0.5'

    # 经济奖励（10% 概率返还部分费用）
    - '@chance=10% givemoney amount=50 provider=vault'
    - '@chance=10% sendmessage text="<yellow>幸运！返还了 50 金币。</yellow>"'

    # 经验奖励
    - 'giveexp amount=30 mode=points'

    # 高品质额外奖励
    - '@if=%forge_quality%=="epic" sendmessage text="<light_purple>史诗品质！额外获得强化石。</light_purple>"'
    - '@if=%forge_quality%=="epic" createitem id=bonus source=emakiitem-strengthen_stone amount=1'
    - '@if=%forge_quality%=="epic" senditem id=bonus'

    # 全服广播（仅传说品质）
    - '@if=%forge_quality%=="legendary" broadcastmessage text="<gold>%player_name% 锻造出了传说品质装备！</gold>"'

    # 延迟提示
    - '@delay=2s sendmessage text="<gray>装备已更新，请查看背包。</gray>"'

    # 脚本处理（复杂逻辑）
    - '@ignore_failure runjs script=forge/success.js arg_quality=%forge_quality% arg_recipe=%forge_recipe_id%'