Getting Started

快速开始

目标：做一个带 /example 命令的插件，构建后放进服务器就能运行。

项目	本例使用
编译目标	Spigot 1.12.2 API、Java 8 字节码
构建环境	JDK 21、Gradle 9.6.1

服务器要求的 Java 版本由服务器自己决定。库编译成 Java 8 字节码，并不代表新版服务器能在 Java 8 上运行。

1. 配置仓库

settings.gradle.kts：

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/")
        maven("https://repo.codemc.io/repository/maven-public/")
    }
}
rootProject.name = "ExamplePlugin"

2. 配置构建

build.gradle.kts：

plugins {
    id("me.kzheart.klib") version "<gradle-plugin-version>"
}
group = "com.example"
version = "1.0.0"

klib {
    libraryVersion.set("<klib-version>")
    name("ExamplePlugin")
    main("com.example.plugin.ExamplePlugin")
    version(project.version.toString())
    targetPackage("com.example.plugin")
    noApiVersion() // 目标 1.12.2 不生成 api-version
    modules {
        command() // 自动带入 core、config、lang
    }
}
dependencies {
    compileOnly("org.spigotmc:spigot-api:1.12.2-R0.1-20180712.012057-156") {
        isTransitive = false
    }
}

• <klib-version> 填 Maven Central 上已发布的版本，见 CHANGELOG。
• noApiVersion() 只用于 1.12.2。面向其他版本时按实际服务器 API 设置，不要调用只在新版本里才有的 Bukkit 方法。
• 更多配置项见 构建与打包。

3. 编写代码

src/main/java/com/example/plugin/ExamplePlugin.java：

package com.example.plugin;

import me.kzheart.klib.KPlugin;
import me.kzheart.klib.command.CommandModule;

public final class ExamplePlugin extends KPlugin {
    @Override
    protected void setup() {
        CommandModule.install(this);
        commands().register(new ExampleCommands());
    }
}

src/main/java/com/example/plugin/ExampleCommands.java：

package com.example.plugin;

import me.kzheart.klib.command.annotation.Command;
import me.kzheart.klib.command.annotation.Permission;
import me.kzheart.klib.command.annotation.Route;
import org.bukkit.command.CommandSender;

@Command("example")
@Permission("exampleplugin.use")
public final class ExampleCommands {
    @Route("")
    public void run(CommandSender sender) {
        sender.sendMessage("Klib 已就绪");
    }
}

要点：

• 覆盖无参 setup()，不要覆盖 onEnable / onDisable，这两个入口由 KPlugin 管理。
• 模块要先安装再使用：Gradle 选了 command() 只是打包进去，还需要调用 CommandModule.install(this)。
• 通过 commands()、configs()、events()、tasks() 注册的资源，会在插件关闭或重建时自动释放。
• 命令在代码里声明，不用写进 plugin.yml。消息默认使用内置文案，自定义方式见 Lang 和 Command。

4. 构建并部署

./gradlew clean shadowJar

新项目还没有 Wrapper 时，先运行：

gradle wrapper --gradle-version 9.6.1

把 build/libs/ExamplePlugin-1.0.0-all.jar 放进服务器的 plugins 目录。要用 -all 这个包，不带依赖的普通 JAR 无法运行。

验证：在控制台执行 example，或让有 exampleplugin.use 权限的玩家执行 /example，会看到 Klib 已就绪。

下一步

想做	看这里
加载 YAML 配置、支持重载	Config：ConfigModule.install(this) + configs().load(Settings.class)
多语言消息	Lang
事件、定时任务、异步	Core
注解写法汇总	组件与注解
遇到报错	故障排查