Home

Klib 使用文档

Klib 是面向 Bukkit、Spigot 与 Paper 插件的模块化 Java / Kotlin 基础库。以 KPlugin 与 Scope 管理生命周期，按需组合命令、配置、物品、界面、数据与脚本能力。

本 Wiki 提供接入指南与模块用法；项目概览见 仓库 README，版本记录见 更新日志。公共制品保持 Java 8 API 与字节码边界，实际运行所需的 Java 版本由目标服务端决定。

public final class MyPlugin extends KPlugin {
    @Override
    protected void setup() {
        CommandModule.install(this);
        commands().register(new MyCommands());          // 命令
        events().register(new MyListener());            // 事件
        tasks().every(Ticks.seconds(30), () -> save()); // 定时任务
    }
}

从这里开始

入口	内容
开始使用	项目配置、插件入口、模块安装与首次构建
构建与打包	Gradle 插件、模块选择、依赖闭包与重定位
组件与注解	作用域、功能组件与各模块声明入口
故障排查	依赖解析、启动、重载与线程问题

模块索引

模块	主要能力
Core	插件与作用域、代际受管异步结果、组件、事件、调度、冷却与加权随机
Config	YAML 严格映射、迁移、原子重载与聚合候选快照
Lang	多语言、占位符、富文本与宿主 Adventure 适配
Command	命令树、注解、权限、建议、帮助样式与业务异常策略
Item	物品构建、标签、编解码与安全预览适配
Data	类型化 KV、受管 SQL、可选连接池、迁移门禁、PostgreSQL LISTEN 与存储后端
UI	配置布局、状态菜单、页面导航、分页、投放区与聊天面板
Script	Kether 动作、编译检查、作用域执行与可选宿主互操作
Hook	Vault、PlayerPoints、XConomy、PlaceholderAPI 与消耗奖励
Compat	版本能力发现、实现选择与数据包侧边栏
Remote	插件日志、Incident 与离线交付客户端

核心概念

• 先选模块，再安装：Gradle 插件 的 modules {} 负责选模块、生成 plugin.yml 和打包重定位；代码里还要显式安装，例如 CommandModule.install(this)。数据后端和版本适配实现需单独选择，见 构建与打包。
• KPlugin + setup()：继承 KPlugin，覆盖无参 setup()，不要覆盖 onEnable / onDisable。底层作用域用 context().scope()。
• 资源自动释放：commands()、configs()、events()、tasks()、components() 注册的资源随所属作用域关闭统一释放。
• 不自动切线程：异步结果访问 Bukkit 状态前，通过 scope.submitSync(...) 或 AsyncTasks.thenSync(...) 回到主线程；这些受管结果随所属作用域关闭或重建终结，见 Core。
• 命令只在启动时声明：配置重载只更新业务状态，见 Command。

常用交互能力

• 命令帮助：注解路由、用途说明、权限过滤与自动分页。
• 命令模块：帮助预设、自定义布局、命令预填与业务异常策略。
• UI 模块：物品栏菜单、字段编辑、分组管理面板与聊天输入。

源码与反馈

• Klib 仓库
• Klib Gradle 插件
• 问题与建议
• 与源码同步维护的文档

公共仓库使用 Apache License 2.0，维护公共 Java / Kotlin 模块及最小 Guard API；Guard runtime、Native、Collector 与生产部署配置属于私有仓库。