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 且必须遵循以下规范。
被指定的配置文件会从插件文件中自动释放，而不需要手动执行 saveResource 方法。

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 开放了修改及写入方法。因为二次写入会打乱注释及配置文件结构，这对用户是极不友好的。若要使用文件储存则参考本地数据储存章节。

在 Windows 以及特定的 Linux 环境下，基于 TConfig 的配置文件允许创建文件变动监听。
通过该方法可以更加便捷的控制配置文件进行重载而不需要通过命令的形式。

同理，这个方法也需要在 TConfig 被赋值之后才可以调用。
不过这个功能已经很少使用了，用命令的方式可以更加稳定且有效的控制配置文件重载。

 1 object ExamplePlugin : Plugin() {
 2 
 3     @TInject("config.yml")
 4     lateinit var conf: TConfig
 5         private set
 6 
 7     override fun onEnable() {
 8         conf.listener { 
 9             // 配置文件发生变动
10         }.runListener()
11     }
12 
13     fun reload() {
14         // 手动重载配置文件会触发 listener 方法
15         conf.reload()
16     }
17 }

语言文件

基于 TabooLib 的插件的所有语言文件使用 TLocale 工具，只需要按照规范在 resources 目录中创建文件不需要提前声明。
被指定的语言文件会从插件文件中自动释放，而不需要手动执行 saveResource 方法。

├── resources ·························· 资源文件目录
|   ├── lang ··························· 语言文件目录
|   |   └── zh_CN.yml ·················· 简体中文（中国）
|   |   └── zh_TW.yml ·················· 繁体中文（中国台湾、中国香港）
|   |   └── en_US.yml ·················· English（Australia、Canada、United Kingdom、New Zealand、US）
|   |   └── ...

发送 TLocale 语言文件信息时 TabooLib 将根据玩家的客户端语言选择对应的语言文件，无需任何手动适配。
使用 Kotlin 提供的扩展方法：

1 player.sendLocale("test")
2 player.sendLocale("test", "参数 1")

或是 Java 原生方法：

1 TLocale.sendTo(player, "test", "参数 1", "参数 2")

详细的语言文件编写规范请参考 TLocale 使用文档 页面。