TabooLib Style Guide

本文定义了基于 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 规范。

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

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

1 taboolib {
2     tabooLibVersion = '5.7.2'
3     loaderVersion = '3.0.4'
4     classifier = null
5     builtin = true
6 }

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

主类

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

1 import io.izzel.taboolib.loader.Plugin
2 
3 object ExamplePlugin : Plugin() {
4     // ...
5 }

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

1 import io.izzel.taboolib.loader.Plugin;
2 
3 public class ExampleJavaPlugin extends Plugin {
4     
5     public static final ExampleJavaPlugin INSTANCE = new ExampleJavaPlugin();
6 
7     ExampleJavaPlugin() {
8     }
9 }

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

 1 object ExamplePlugin : Plugin() {
 2 
 3     override fun onLoad() {
 4     }
 5 
 6     override fun onEnable() {
 7     }
 8 
 9     override fun onDisable() {
10     }
11 
12     override fun onActive() {
13     }
14 }

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

1 object ExamplePlugin : Plugin() {
2 
3     override fun allowHotswap(): Boolean {
4         return false
5     }
6 }

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

配置文件

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

1 object ExamplePlugin : Plugin() {
2 
3     @TInject("config.yml")
4     lateinit var conf: TConfig
5         private set
6 }

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

 1 object ExamplePlugin : Plugin() {
 2 
 3     @TInject("config.yml")
 4     lateinit var conf: TConfig
 5         private set
 6 
 7     init {
 8         // kotlin.UninitializedPropertyAccessException: lateinit property int has not been initialized
 9         conf.getString("...")
10     }
11 
12     override fun onLoad() {
13         // kotlin.UninitializedPropertyAccessException: lateinit property int has not been initialized
14         conf.getString("...")
15     }
16 
17     override fun onEnable() {
18         // 有效的写法
19         conf.getString("...")
20     }
21 }

基于 TConfig 的配置文件不允许在插件运行过程中二次修改或写入，尽管 TConfig 开放了修改及写入方法。因为二次写入会打乱注释及配置文件结构，这对用户是极不友好的。若要使用文件储存则参考本地数据储存章节。