原生脚本系统

EmakiSkills 除了支持 MythicMobs 执行技能效果外，还内置了原生脚本系统。原生脚本不依赖任何外部插件，直接在技能配置中定义效果逻辑。

全局脚本引擎配置

原生脚本引擎位于 config.yml 的 script_engine 节点：

script_engine:
  enabled: true
  default_mode: "native"
  stop_on_failure: true
  max_lines_per_phase: 64
  max_targets_per_action: 16
  debug: false

字段	说明
enabled	是否启用原生技能脚本。关闭后仅保留非脚本释放流程。
default_mode	技能未声明脚本模式时使用的默认模式。
stop_on_failure	动作失败后是否停止后续动作。
max_lines_per_phase	单个阶段允许的最大动作行数。
max_targets_per_action	单个动作最多处理的目标数量。
debug	是否输出脚本调试信息。

这些限制用于避免单个技能一次释放处理过多动作或目标。大型范围技能建议控制目标数量，并把视觉效果、伤害和消息分开测试。

脚本模式

通过 script.mode 字段选择执行方式：

模式	别名	说明
native	—	只使用内置脚本动作。
mythic	—	只使用 MythicMobs 技能（通过 mythic_skill 字段）。
hybrid	both	同时执行 native 脚本和 mythic 技能。

脚本阶段

每个阶段可独立配置 conditions 和 actions 列表：

阶段	别名	触发时机
cast	on_cast	技能释放时。
hit	on_hit	命中目标时。
miss	on_miss	未命中时。
fail	on_fail	释放失败时（条件不满足、资源不足等）。

配置结构

id: flame_strike
trigger_type: active
display_name: '<red>烈焰斩'
script:
  mode: native
  stop_on_failure: true
  cast:
    actions:
      - 'sound sound=ENTITY_BLAZE_SHOOT volume=1 pitch=1.5'
      - 'particle particle=FLAME at=target count=20 speed=0.1'
      - 'damage amount=%fire_damage% damage_type=spell'
  hit:
    actions:
      - 'ignite ticks=60'
      - 'message text="<red>烈焰灼烧！"'
  fail:
    actions:
      - 'message text="<gray>技能释放失败。"'

脚本上下文变量

脚本执行时自动注入以下变量，可在动作中通过 {变量名} 引用：

变量	说明
%level%	当前技能等级。
%skill_id%	技能 ID。
%trigger_id%	触发器 ID。
%has_target%	是否有目标（0 或 1）。
%target_name%	目标名称（有目标时）。
%target_uuid%	目标 UUID。
%target_world%	目标所在世界。
%target_x%	目标 X 坐标。
%target_y%	目标 Y 坐标。
%target_z%	目标 Z 坐标。

内置脚本动作

damage

对目标造成伤害。

参数	必填	默认值	说明
amount	是	—	伤害量。
target	否	target	目标（target/caster/look/共享状态键名）。
damage_type	否	generic	伤害类型。
element	否	—	元素类型。

heal

治疗目标。

参数	必填	默认值	说明
amount	是	—	治疗量。
target	否	caster	目标。

ignite

点燃目标。

参数	必填	默认值	说明
ticks	是	—	点火持续 tick 数。
target	否	target	目标。

message

发送消息（支持 MiniMessage）。

参数	必填	默认值	说明
text	是	—	消息文本。
target	否	caster	接收者。

sound

播放音效。

参数	必填	默认值	说明
sound	是	—	Bukkit Sound 名称。
volume	否	1	音量。
pitch	否	1	音调。
at	否	caster	播放位置。

particle

生成粒子。

参数	必填	默认值	说明
particle	是	—	粒子类型。
at	否	target	生成位置。
count	否	1	粒子数量。
speed	否	0	粒子速度。

ray

射线追踪选取目标，结果写入共享状态供后续动作使用。

参数	必填	默认值	说明
range	否	16	射线距离。
width	否	1	射线宽度。
save	否	target	结果存储的共享状态键名。

mythic

调用 MythicMobs 技能（需要安装 MythicMobs）。

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

aoe_damage

对范围内实体造成伤害。命中数量写入共享状态 aoe_hit_count。

参数	必填	默认值	说明
amount	是	—	伤害数值。
radius	否	5	范围半径（格）。
center	否	target	中心点：caster、target、look。
shape	否	sphere	范围形状：sphere（球形）、cylinder（圆柱）。
filter	否	hostile	目标过滤：hostile（排除玩家）、all（所有生物）。
max_targets	否	20	最大命中数量。
exclude_caster	否	true	是否排除施法者。

projectile

发射自定义投射物，逐 tick 模拟飞行。命中时设置上下文目标实体。

参数	必填	默认值	说明
speed	否	1.5	每 tick 飞行格数。
gravity	否	0.05	每 tick 重力加速度。
lifetime	否	60	最大存活 tick 数。
hit_radius	否	0.5	命中检测半径。
pierce	否	0	穿透实体数量。
homing	否	false	是否追踪目标。
homing_strength	否	0.1	追踪转向强度。
particle	否	FLAME	尾迹粒子类型。
damage	否	0	命中伤害（0 表示不造成伤害）。
direction	否	look	初始方向：look（视线方向）、target（朝向目标）。

目标解析规则

动作中 target 参数的解析规则：

值	解析为
target	当前目标实体。
caster / self / player	施法者。
look	视线前方 3 格位置（仅位置，无实体）。
其他字符串	从共享状态查找（如 ray 动作存储的实体/位置）。

动作前缀修饰符

脚本动作支持前缀修饰符：

actions:
  - '@if="%has_target% == 1" damage amount=20'
  - '@chance=30% ignite ticks=100'

前缀	说明
@if='%expr%'	条件为真时才执行。
@chance=%n%%	概率执行。

variables 字段

技能定义中的 variables 块定义运行时变量，可在脚本动作中通过 {变量名} 引用：

id: power_strike
variables:
  fire_damage:
    type: expression
    value: "10 + %level% * 5"
  is_enhanced:
    type: boolean
    value: "%level% >= 5"
  battle_cry:
    type: random_text
    values:
      - "<red>燃烧吧！"
      - "<red>烈焰之力！"

变量支持的类型与技能参数类型一致，可引用 %level%、%has_target%、%trigger_id% 等上下文变量。