本文定义了基于 TabooLib (Kotlin) 编写 Bukkit 插件而提供的指导性准则和建议。

开始

通过阅读 TabooLib 来创建基础的项目文件，自 2021/06 月起 TabooLib—SDK 将自带 GitHub Actions 自动构建任务。

Windows 平台:

gradlew clean build

macOS 或 Linux 平台:

./gradlew clean build

构建文件将会保存在 ./build/libs 目录中。

构建文件

本文所使用的代码均在 GitHub 开源，项目中所使用 Kotlin 代码应遵循 Kotlin Coding Conventions 规范。

group = 'io.izzel.example'
version = '1.0.0'

构建文件中所指示的 group 必须重新定义，不允许使用 io.izzel.taboolib 域名。否则将导致插件将无法被 TabooLib 识别。

taboolib {
    tabooLibVersion = '5.7.2'
    loaderVersion = '3.0.4'
    classifier = null
    builtin = true
}

基于 TabooLib 编写的插件将会内置 TabooLib 加载器，约为 40kb 左右。若关闭 builtin 选项不会内置并移除 TabooLib 加载器依赖文件，届时该插件将不会主动加载 TabooLib 但能够使用由其他插件所加载的 TabooLib 库。

主类

基于 TabooLib 的插件中必须存在一个继承自 io.izzel.taboolib.loader.Plugin 的唯一主类，这个类不需要在任何文件中指示。

import io.izzel.taboolib.loader.Plugin

object ExamplePlugin : Plugin() {
    // ...
}

主类必须使用 object 单例，若是 Java 语言则需要使用以下方式，使用全大写的 INSTANCE 作为标识符。

import io.izzel.taboolib.loader.Plugin;

public class ExampleJavaPlugin extends Plugin {
    
    public static final ExampleJavaPlugin INSTANCE = new ExampleJavaPlugin();

    ExampleJavaPlugin() {
    }
}

主类中提供了四种可被继承的生命周期方法，在特定的时间段运行。

object ExamplePlugin : Plugin() {

    override fun onLoad() {
    }

    override fun onEnable() {
    }

    override fun onDisable() {
    }

    override fun onActive() {
    }
}

除了三种 Bukkit 提供的接口外 TabooLib 还提供了一个特殊的 onActive 方法在服务端完全启动后执行。
在绝大多数的情况下基于 TabooLib 的插件支持游戏内热重载，但是这是不稳定的。

object ExamplePlugin : Plugin() {

    override fun allowHotswap(): Boolean {
        return false
    }
}

通过这种方式禁止游戏内热重载，将会跳过对于该插件的所有 TabooLib 侵入式工具加载过程。
在插件主类中，不允许出现任何干涉游戏的逻辑，例如监听器，调度器等。在主类使用监听器也将不会被加载。

配置文件

基于 TabooLib 的插件的所有配置文件使用 TConfig 且必须遵循以下规范。

object ExamplePlugin : Plugin() {

    @TInject("config.yml")
    lateinit var conf: TConfig
        private set
}

该配置文件会在 onEnable 方法内被赋值，任何调用该配置文件的逻辑必须在 onEnable 方法之后（或之内）。
否则将会抛出 kotlin.UninitializedPropertyAccessException: lateinit property int has not been initialized 异常

object ExamplePlugin : Plugin() {

    @TInject("config.yml")
    lateinit var conf: TConfig
        private set

    init {
        // kotlin.UninitializedPropertyAccessException: lateinit property int has not been initialized
        conf.getString("...")
    }

    override fun onLoad() {
        // kotlin.UninitializedPropertyAccessException: lateinit property int has not been initialized
        conf.getString("...")
    }

    override fun onEnable() {
        // 有效的写法
        conf.getString("...")
    }
}