面向 Bukkit、Spigot 与 Paper 插件的模块化 Java / Kotlin 基础库
按需组合公共能力,明确管理生命周期。
使用文档 · 快速接入 · 模块索引 · Gradle 插件 · 更新日志
Kotlin API 直接内置于 Core、Config、Command、UI、Item、Data 与 Script,无需额外 Kotlin 模块。Java API 继续使用同一套引擎;公共运行时保持 Java 8 字节码边界。
Klib 把插件里反复要写的基础能力拆成独立模块:命令、配置、语言、物品、菜单、数据存储、脚本和外部插件集成。按需选用,资源随插件生命周期自动释放。
public final class MyPlugin extends KPlugin {
@Override
protected void setup() {
CommandModule.install(this);
commands().register(new CoinCommands());
}
}
@Command(value = "coins", help = true) // 自动生成分页帮助
@Permission("myplugin.coins")
public final class CoinCommands {
@Route("give <target> <amount>")
@Description("向玩家发放金币")
public void give(CommandSender sender,
@Param("target") Player target,
@Param("amount") int amount) {
// 参数已解析并校验,补全和权限过滤自动完成
}
}- 兼容范围:Bukkit / Spigot / Paper;公共制品为 Java 8 字节码,实际运行所需的 Java 版本由服务端决定。
- 发布方式:Klib Maven 仓库,配套 Gradle 插件 负责选模块、生成
plugin.yml和依赖重定位。
把占位符换成已发布的版本(见上方徽章和 更新日志):
plugins {
id("me.kzheart.klib") version "<gradle-plugin-version>"
}
repositories {
maven("https://maven.kzheart.me/releases") { content { includeGroup("me.kzheart.klib") } }
mavenCentral()
}
klib {
libraryVersion.set("<klib-version>")
name("ExamplePlugin")
main("com.example.plugin.ExamplePlugin")
version(project.version.toString())
targetPackage("com.example.plugin")
modules {
command()
ui()
}
}modules {}只负责打包,代码里还要在KPlugin.setup()中安装所选模块。- 依赖会自动补齐,例如
command()会带入 Core、Config 和 Lang。
完整接入(仓库配置、服务端 API 依赖)和常用模块:
- 开始使用:项目配置、插件入口与模块安装。
- 构建与打包:仓库、依赖闭包、重定位与手工接入。
- 命令模块:命令声明、帮助样式、异常策略与启动注册契约。
- UI 模块:菜单、一次性确认、字段编辑、分组管理面板、业务输出返回、告示牌与聊天输入。
Paper 项目可用 packaging { paper() } 检查宿主边界,以 api { archive(provider); packages("com.example.api") } 声明共享 API;check、正式包和 Maven 发布均经过验证。用法见构建与打包。
不用 Gradle 插件时,直接依赖 me.kzheart.klib:klib-<module>:<klib-version>,自己完成打包和重定位。
按功能选择模块;数据后端和版本适配实现需要单独选择,完整依赖关系见 构建文档。
| 模块 | 主要能力 | 文档 |
|---|---|---|
klib-core |
插件与作用域、代际受管异步结果、组件、事件、调度、冷却与加权随机 | Core |
klib-config |
YAML 严格映射、迁移、原子重载与聚合候选快照 | Config |
klib-lang |
多语言、占位符、富文本与宿主 Adventure 适配 | Lang |
klib-command |
命令树、注解、权限、建议、帮助样式与业务异常策略 | Command |
klib-item |
物品构建、标签、编解码与安全预览适配 | Item |
klib-data |
字节与类型化 KV、迁移与玩家缓存 | Data |
klib-ui |
配置布局与动态绑定、状态差量菜单、页面导航、分页、支持原子交换的投放区与聊天管理面板 | UI |
klib-script |
Kether 动作、词元扩展、编译检查、作用域执行与可选宿主互操作 | Script |
klib-hook |
Vault、PlayerPoints、XConomy、PlaceholderAPI 与消耗奖励 | Hook |
klib-compat |
版本能力发现、实现选择与数据包侧边栏 | Compat |
klib-remote |
插件日志、Incident 与离线交付客户端 | Remote |
数据后端与驱动
klib-data 提供公共契约;根据实际存储方式选择实现。
| 模块 | 存储与运行时依赖 |
|---|---|
klib-data-json |
JSON 文件;使用宿主提供的 Gson |
klib-data-jdbc |
JDBC KV 引擎、受管数据库、挂起 SQL/显式映射、事务与外部迁移门禁;不包含数据库驱动 |
klib-data-pool |
data { pool() } 可选 Apache Commons DBCP 池;依赖隔离,不由其他存储后端自动引入 |
klib-data-sqlite |
SQLite;使用宿主提供的 SQLite JDBC |
klib-data-mysql |
MySQL;包含 MySQL Connector/J |
klib-data-postgresql |
PostgreSQL;包含 pgJDBC、专用 LISTEN 会话(接收/回调线程防关闭自等待)与事务迁移 |
JDBC KV 打开期间关闭提供器时,晚到连接清理完成后打开阶段才会失败;已接受的事务仍按队列排空。PostgreSQL 内部表通过数据库事务锁协调首次初始化,支持独立提供器并发连接空库。存储配置与使用方式见 Data 文档。
| 入口 | 内容 |
|---|---|
| GitHub Wiki | 按模块组织的接入指南与 API 用法 |
| 仓库文档 | 与源码一起维护的模块边界、生命周期与线程约定 |
| 组件与注解 | 声明组件、命令及其他注解入口 |
| 故障排查 | 常见问题与定位方式 |
AI 编程助手接入
仓库提供 Klib 技能,按需读取官方 Wiki。Codex 中可通过 $skill-installer 安装:
$skill-installer 安装 https://github.com/kzheart/klib/tree/main/skills/klib
其他支持 SKILL.md 的工具可按其安装方式使用 skills/klib 目录。
源码按 libraries/、storage/、platform/、runtime/ 归组,职责、依赖方向与源码位置见 模块布局。
Gradle 项目名及 Maven 坐标保持 klib-*;例如 Core 位于 libraries/core/,测试仍运行 :klib-core:test。
从源码构建使用 JDK 21 toolchain;Java 使用 --release 8,Kotlin 使用 JVM 1.8 与 -Xjdk-release=8:
./gradlew clean check --no-configuration-cache
python3 -m unittest discover -s scripts/tests -v欢迎通过 Issues 或 Pull Requests 反馈问题与提交改进。变更应保持公共 Java 8 边界,并同步相关模块文档;参与前请阅读 仓库协作约定。
本仓库只包含公共 Java / Kotlin 模块和最小
klib-guard-api编译契约;Gradle 插件另有仓库,Guard runtime 等私有组件不在此处。
Klib 使用 Apache License 2.0。版权与第三方归属入口见 NOTICE;改编来源与许可全文保留在相关模块及其 JAR 的 META-INF/LICENSE-*.txt 中。
JDBC 后端支持调用方持有的 DataSource,见 Data。驱动可由服务器库加载器提供,Klib 模块仍按插件隔离。
脚本跨加载器互调保留旧容器实际读取的字段 ABI,详见 Script。