原生脚本系统

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	只使用 MythicMobs 技能（通过 mythic_skill 字段）。
hybrid	both	同时执行 native 脚本和 mythic 技能。

无法识别的 mode 取值会回退到 script_engine.default_mode。

脚本阶段

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

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

阶段键名只接受上表中的写法，不支持 on_cast 这类前缀形式。

script 块还支持 enabled 字段：未显式声明时，只要 actions 中存在任意阶段就视为启用。

配置结构

id: flame_strike
trigger_type: active
display_name: '<red>烈焰斩'
script:
  mode: native
  stop_on_failure: true
  actions:
    cast:
      - 'self | play_sound sound=ENTITY_BLAZE_SHOOT volume=1 pitch=1.5'
      - 'trigger | spawn_particle particle=FLAME count=20'
      - 'trigger | damage amount=%fire_damage%'
    hit:
      - 'trigger | ignite duration=3s'
      - 'self | send_message text="<red>烈焰灼烧！"'
    fail:
      - 'self | send_message text="<gray>技能释放失败。"'

脚本上下文变量

脚本执行时自动注入以下变量，可在动作、条件和文本中通过 %变量名% 引用：

变量	说明
%level%	当前技能等级。
%skill_id%	技能 ID。
%trigger_id%	触发器 ID。
%has_target%	是否有目标（0 或 1）。

同时注入 5 个供 MythicMobs 读取的同义变量：%emaki_skill_id%、%emaki_skill_level%、%emaki_trigger_id%、%emaki_is_passive%、%emaki_has_target%。

variables 块内的表达式还可额外引用以下上下文量（它们只参与变量求值，不作为脚本行占位符注入）：%max_level%、%is_passive%、%player_level%、%player_health%、%player_max_health%、%sneaking%。

脚本动作

技能脚本行由 CoreLib 的动作引擎编译执行，因此可用的动作段就是 CoreLib 注册表里的段，加上 EmakiSkills 自己注册的技能段。EmakiSkills 没有另一套私有动作 ID。

• CoreLib 自带通用段的完整清单与参数见 CoreLib 动作系统。
• EmakiSkills 追加的 cast_skill、cast_mythic_skill、等级/槽位/冷却/解锁段见 CoreLib 动作。

动作 ID 要用注册表里的写法

段 ID 必须与注册名逐字一致，写错的行在编译期就被丢弃并计入诊断，不会在运行期报错。常见误写：

误写	正确写法
message	send_message
sound	play_sound
particle	spawn_particle
mythic	cast_mythic_skill

ray 与 aoe_damage 不是已注册的段，没有对应写法。

目标不通过动作参数指定，而是用管道的 来源 | 段 语法，见 CoreLib 动作系统。

下面只列技能脚本里最常用的几个段，参数以注册表为准。

damage

对目标造成伤害。

参数	必填	默认值	说明
amount	是	—	扣除的生命值。

heal

治疗目标。

参数	必填	默认值	说明
amount	是	—	恢复的生命值。

ignite

点燃目标。

参数	必填	默认值	说明
duration	否	5s	燃烧持续时间，支持 ms、s、t 后缀。

send_message

发送聊天消息（支持 MiniMessage）。

参数	必填	默认值	说明
text	是	—	消息文本。

play_sound

播放音效。

参数	必填	默认值	说明
sound	是	—	Bukkit Sound 名称。
volume	否	—	音量。
pitch	否	—	音调。

spawn_particle

生成粒子。

参数	必填	默认值	说明
particle	是	—	粒子类型。
count	否	—	粒子数量。
offset_x / offset_y / offset_z	否	—	各轴扩散偏移。
extra	否	—	粒子额外参数（多数粒子为速度）。

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（朝向目标）。

目标解析规则

目标写在竖线左侧的来源段里，不是动作参数。技能脚本里常用的来源：

来源	解析为
self	施法者自己。
trigger	触发上下文指定的实体（主动技能的准星目标、被动技能的事件对象）。
looking_at	施法者准星前方的实体，可加 range=。
nearby / nearby_players	周围实体或玩家，可加 radius=、type=。
player_by_name	按名字指定玩家。

完整来源清单与参数见 CoreLib 动作系统。

条件、概率与延迟

条件、概率和延迟是管道里的 gate 段，串在竖线之间，不是行首的 @ 前缀：

actions:
  cast:
    - 'trigger | where %has_target%==1 | damage amount=20'
    - 'trigger | chance 30% | ignite duration=5s'
    - 'self | after 20t | send_message text="<gray>1 秒后触发。"'

gate	说明
where <条件>	条件不成立时清空目标流，后续段不执行。
chance <n>%	按概率放行。
after <时间>	延迟指定时间后再执行后续段。支持 ms、s、t 后缀。

@ 前缀写法已废弃

旧版的 @if=、@chance=、@delay= 行首前缀不再被解析。对应关系是 @chance=25% → chance 25%、@delay=20t → after 20t、@if=<条件> → if <条件> [ ... ] 分支或 where <条件>。@ignore_failure 没有对应写法。完整语法见 CoreLib 动作系统 · 从旧语法迁移。

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
    lines:
      - "<red>燃烧吧！"
      - "<red>烈焰之力！"

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