Skip to content
kzheartPublic

About

Modular Java 8 library for Bukkit and Paper plugins

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Klib 标识

Klib

面向 Bukkit、Spigot 与 Paper 插件的模块化 Java / Kotlin 基础库
按需组合公共能力,明确管理生命周期。

持续集成状态 Klib Maven 仓库 Java 8 API 与字节码 Apache License 2.0

使用文档 · 快速接入 · 模块索引 · 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。

已受理操作的取消隔离见 Core,标准命令面板见 UI,共享 PostgreSQL 业务库预设见 Data。

About

Modular Java 8 library for Bukkit and Paper plugins

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages