鹤造工坊

Appearance

扩展脚本 ​

什么是扩展脚本？ ​

扩展脚本位于 scripts/expansions/ 目录下，是比属性脚本更底层的扩展方式。通过扩展脚本，你可以：

  • 注册自定义属性类型（配合触发器 + 处理器）
  • 注册自定义属性源
  • 启动全局服务、注册监听器
  • 在插件启停时执行自定义逻辑

与属性脚本的区别 ​

属性脚本扩展脚本
目的创建属性扩展插件能力
基类GroovyAttribute实现 GroovyScript 接口
加载时机属性管理器初始化时脚本加载阶段
生命周期onEnable / onDisableonEnable / onDisable（全局级别）
典型产出属性实例属性类型、属性源类、监听器等

加载机制 ​

  1. 插件启动或重载时，按 config.yml 中 groovy load sort 的顺序扫描 scripts/ 目录
  2. expansions 目录通常在 libs 之后加载（确保依赖的基类已就绪）
  3. 如果类实现了 GroovyScript 接口，自动调用 onEnable()
  4. 重载或卸载时，自动调用 onDisable()

基本示例：实现 GroovyScript 接口 ​

Groovy
package scripts.expansions

import cn.org.bukkit.craneattribute.api.expansions.GroovyScript
import groovy.transform.CompileStatic

@CompileStatic
class MyExpansion implements GroovyScript {

    MyExpansion() {}

    @Override
    void onEnable() {
        System.out.println("我的扩展脚本已启用！")
        // 在这里可以：
        // - 注册属性类型
        // - 注册监听器
        // - 启动定时任务
    }

    @Override
    void onDisable() {
        System.out.println("我的扩展脚本已禁用！")
        // 在这里可以：
        // - 卸载属性类型
        // - 卸载监听器
        // - 停止定时任务
    }
}

警告

如果代码中有 TaskTimer、监听器等长期持有的对象，一定要在 onDisable() 中清除或关闭，否则会造成内存泄漏。

常见用途 ​

1. 注册命令 ​

Groovy
@CompileStatic
class CommandExpansion implements GroovyScript {

    @Override
    void onEnable() {
        // 注册自定义命令
        ListenerUtils.registerListener("my_listener", SomeEvent.class, ...) { event ->
            // ...
        }
    }

    @Override
    void onDisable() {
        ListenerUtils.unregisterListener("my_listener")
    }
}

2. 注册全局监听器 ​

在扩展脚本中注册的监听器对整个服务器生效，不局限于某个属性。

3. 初始化外部服务 ​

如果你的插件需要连接数据库、读取外部配置、启动 HTTP 服务等，可以在扩展脚本的 onEnable() 中完成。

进阶：注册自定义属性类型 ​

这是扩展脚本最强大的用法——创建全新的属性触发机制。需要配合：

  • 一个属性类型（AttributeType）
  • 一个触发器（AttributeTrigger）——决定何时触发
  • 一个处理器（AttributeHandler）——决定如何处理

完整示例请参考 Groovy 注册插件内容。

内置示例 ​

插件在 scripts/expansions/ 下提供了几个示例：

文件功能
AttributeManager.groovy演示如何注册自定义属性类型
CommandTest.groovy演示如何注册 Bukkit 命令
DHEffect.groovy基于 DecentHolograms 的伤害显示视效

注意事项 ​

  1. 扩展脚本的 onEnable() 在插件启动阶段调用——此时 Bukkit 可能还未完全就绪，不要在此时操作世界或实体
  2. onDisable() 中必须清理所有资源（监听器、定时任务等），否则每次 /ca reload 都会累积残留对象
  3. 保持 @CompileStatic 以获得良好性能
  4. 扩展脚本之间的加载顺序由 groovy load sort 配置决定，如有依赖关系需要注意顺序

参考 ​