API

EmakiSkills 对外提供脚本动作注册和技能施法能力。第三方插件可以注册自定义脚本动作来扩展技能效果。

EmakiSkillsApi

通过 Bukkit ServicesManager 获取：

RegisteredServiceProvider<EmakiSkillsApi> provider =
    Bukkit.getServicesManager().getRegistration(EmakiSkillsApi.class);
if (provider != null) {
    EmakiSkillsApi api = provider.getProvider();
}

方法	返回值	说明
scriptActionRegistry()	SkillScriptActionRegistry	获取脚本动作注册表。
scriptCastService()	SkillScriptCastService	获取脚本施法服务。

SkillScriptActionRegistry

脚本动作注册表，用于注册和管理自定义脚本动作。

方法	说明
register(Plugin owner, SkillScriptAction action)	注册自定义脚本动作。
unregister(String actionId)	注销指定动作。
unregisterAll(Plugin owner)	注销某插件注册的所有动作。
get(String actionId)	获取动作实例。
ownerOf(String actionId)	获取动作所属插件。
all()	获取所有已注册动作。
byOwner(Plugin owner)	获取某插件的所有动作。

SkillScriptAction 接口

第三方插件实现此接口来定义自定义脚本动作：

public interface SkillScriptAction {
    // 必须实现
    String id();
    ActionStepResult execute(SkillScriptContext context, Map<String, String> arguments);

    // 可选覆盖
    default String category() { return "custom"; }
    default String description() { return ""; }
    default List<ActionParameter> parameters() { return List.of(); }
    default boolean acceptsDynamicParameter() { return false; }
    default ActionExecutionMode executionMode() { return ActionExecutionMode.SYNC; }
    default long timeoutMillis() { return 30000; }
    default void validate() throws ActionSyntaxException {}
}

执行模式

模式	说明
SYNC	在主线程同步执行。适合需要调用 Bukkit API 的动作。
ASYNC	在异步线程执行。适合 IO 操作或耗时计算。默认超时 30 秒。

注册示例

@Override
public void onEnable() {
    EmakiSkillsApi api = /* 获取 API */;
    api.scriptActionRegistry().register(this, new MyCustomAction());
}

注册后，技能配置中即可使用自定义动作 ID：

script:
  cast:
    actions:
      - 'my_custom_action param1=value1 param2=value2'

接入建议

• 在 plugin.yml 中声明 softdepend: [EmakiSkills]。
• 插件禁用时会自动注销所有已注册动作（unregisterAll）。
• 动作 ID 建议使用插件前缀避免冲突，如 myplugin_lightning。
• 异步动作中不要直接调用 Bukkit API，需要通过 Bukkit.getScheduler().runTask() 切换到主线程。