🚀 让你的 Minecraft 服务器拥抱现代化与工程化！
本仓库是一个采用 Kotlin + Gradle 的多模块插件生态系统，面向 Paper 1.20.1， 提供统一的核心框架与一组高质量、可组合的插件与功能模块。
🏗️ 现代化架构 BasePlugin + BaseModule + Terminable 自动资源管理，严谨的生命周期绑定
⚡ 高性能与可维护性 四层单向依赖结构，高内聚低耦合，避免内存/资源泄漏
🛠️ 统一开发体验 多模块共享版本管理与构建约定（Convention Plugin + Shadow 打包 + RunPaper）
🎯 一体化能力 配置（Jackson 多格式）、国际化（i18n + MiniMessage）、GUI 框架、任务调度器（ITaskHandler）
📝 命令系统 基于 Cloud 2.x 注解驱动命令，深度集成 i18n 与 Adventure
🚀 生产可用 支持 JDK21 编译、JDK17 运行时兼容；Paper API 1.20.1；禁用阻塞式用法的最佳实践
📦 NewNan-Plugins
├── 🏛️ core/ # 核心框架与基础设施
├── 🧩 modules/ # 可选功能模块
├── 🔌 plugins/ # 独立插件项目
├── 📚 docs/ # 完整的框架与模块文档中心
└── 🔧 buildSrc/ # 统一的版本与依赖管理
| 目录 | 说明 |
|---|---|
core |
生命周期、调度器、事件、消息、缓存、工具等 |
modules |
config、gui、i18n、network |
plugins |
tpa、railarea、feefly、external-book 等 |
docs |
完整的框架与模块文档中心 |
buildSrc |
统一的版本与依赖管理、构建约定插件 |
📋 详情参见
project-tree.md
| 模块 | 功能描述 | 状态 |
|---|---|---|
| 🔧 config | Jackson 多格式配置支持 | ✅ 稳定 |
| 🖥️ gui | 现代 GUI 系统 | ✅ 稳定 |
| 🌐 i18n | 多语言模板系统 | ✅ 稳定 |
| 🌐 network | Ktor 客户端工具 | ✅ 稳定 |
- 🔧 config: Jackson 多格式配置（YAML/TOML/JSON/XML/Properties/HOCON）、类型安全解析、缓存与合并（touchWithMerge）
- 🖥️ gui: 现代 GUI 系统（Session/Page/Component），原生 i18n 集成，20+ 容器与 8 类组件，异步渲染与自动资源释放
- 🌐 i18n: 多语言模板系统（MiniMessage/Legacy 自动识别），统一 LanguageKeys 规范，printf/sprintf API
- 🌐 network: Ktor 客户端工具、可终止网络请求、链式任务处理
📖 文档入口：
docs/README.md
| 插件 | 描述 | 状态 |
|---|---|---|
| 📚 external-book | 外部书籍管理与发布 | ✅ 生产就绪 |
| 🏗️ foundation | 基础设施与经济系统集成 | ✅ 生产就绪 |
| 🚄 railarea | 铁路区域/站点机制 | ✅ 生产就绪 |
| 📦 rail-express | 铁路物流/快递玩法 | ✅ 生产就绪 |
| ⏰ mcron | 基于 Cron 的调度系统 | ✅ 生产就绪 |
| 🚀 tpa | 玩家传送请求 | ✅ 生产就绪 |
| 付费飞行系统 | ✅ 生产就绪 | |
| 💀 deathcost | 死亡经济惩罚 | ✅ 生产就绪 |
🔍 点击展开查看所有插件
- 📚 external-book: 外部书籍管理与发布，现代 GUI、权限与缓存，i18n 完整支持
- 🏗️ foundation: 基础设施与经济系统集成（含 XConomy 监听集成）
- 🚄 railarea: 铁路区域/站点机制（仅加载已加载世界，动态管理；空间检测优化）
- 📦 rail-express: 铁路物流/快递玩法
- ⏰ mcron: 基于 Cron 的调度系统
- 🚀 tpa: 玩家传送请求
✈️ feefly: 付费飞行（定时扣费、事件可扩展）- 💀 deathcost: 死亡经济惩罚（最佳配置实践示例）
- 🎛️ better-command-block: 增强命令方块功能
- 🔧 mc-patch: Minecraft 修补工具
- ⚡ powertools: 强力工具集
- 🏗️ createarea: 区域创建管理
- 🛡️ guardian: 安全守护系统
- 🏙️ newnanmain: 主城管理
- 💰 dynamiceconomy: 动态经济系统
📋 完整清单以
settings.gradle.kts与project-tree.md为准
graph TD
A[🎯 主插件层<br/>协调与整合] --> B[⚡ 事务层<br/>命令/事件处理]
B --> C[🧠 逻辑层<br/>模块/服务]
C --> D[🔧 基础层<br/>配置/数据/工具]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
🧩 BaseModule 规范 子类须在 init 块内显式调用 init()；onInit 做最小初始化，onReload 负责配置加载
🔄 资源与任务管理 事件、调度器、协程均绑定到 BasePlugin 或 BaseModule 自动释放；推荐使用非阻塞式 ITaskHandler API
⚙️ 配置管理模式 configManager.touchWithMerge + parse 模式在 getPluginConfig() 内执行；reload 时先 clearCache 与重建语言管理器
📝 命令系统集成 Cloud 注解 + 统一错误处理 + i18n 描述映射；所有插件在 plugin.yml 中正确声明依赖
🖥️ GUI 生命周期 会话栈、组件生命周期随页面自动回收；禁止非存储组件被玩家拖拽修改
📖 延伸阅读：
docs/core/best-practices.md
☕ 安装 JDK 21 仓库使用 Gradle Wrapper（无需本地安装 Gradle）
| 操作 | 命令 | 说明 |
|---|---|---|
| 🏗️ 构建所有插件 | ./gradlew buildAllPlugins |
包含 shadowJar |
| 📦 打包所有插件 | ./gradlew shadowJarAll |
仅打包 shadowJar |
| 🔧 构建单个插件 | ./gradlew :plugins:external-book:build |
示例：external-book |
| 📦 打包单个插件 | ./gradlew :plugins:external-book:shadowJar |
示例：external-book |
| 🖥️ 启动测试服务器 | ./gradlew :plugins:external-book:runServer |
示例：external-book |
构建产物位置：各插件子项目的 build/libs/ 目录下（-all/-shadow 变体按配置）
- 将目标插件的 JAR 文件放入服务端
plugins/目录 - 确保服务器运行在 Java 17+ 环境
- 确保服务器为 Paper 1.20.1 版本
flowchart LR
A[📝 注册项目] --> B[🏗️ 创建结构]
B --> C[🧩 继承框架]
C --> D[⚙️ 配置模块]
D --> E[📝 实现命令]
E --> F[📚 参考文档]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#fce4ec
style F fill:#e0f2f1
-
📝 项目注册 在
settings.gradle.kts注册新插件子项目 -
🏗️ 创建结构 新建插件目录与
build.gradle.kts，应用约定插件（newnancity-plugin） -
🧩 继承框架 主类继承
BasePlugin，并实现reloadPlugin() -
⚙️ 配置模块 以
BaseModule方式拆分业务（子模块在onPluginEnable初始化、在onReload加载配置） -
📦 引入依赖 按需引入 modules（config/i18n/gui/network）并遵循 i18n 与消息规范
-
📝 实现命令 命令采用 Cloud 注解风格，注册于
CommandRegistry（模块化实现） -
📚 参考示例 使用
docs/与plugins/external-book/作为最佳实践参考
| 类别 | 链接 | 描述 |
|---|---|---|
| 🏠 文档中心 | docs/README.md |
总览与导航 |
| 🏛️ Core 框架 | docs/core/README.md |
BasePlugin、BaseModule、调度器等 |
| 🖥️ GUI 模块 | modules/gui/README.md |
GUI 系统文档 |
docs/gui/ |
详细指南与示例 | |
| ⚙️ 配置与国际化 | docs/config/ |
配置管理 |
docs/i18n/ |
国际化支持 | |
| 🔧 故障排查 | docs/troubleshooting/ |
常见问题与解决方案 |
📝 代码风格 遵循 Kotlin 官方代码风格与本仓库约定（版本统一于
buildSrc/Versions.kt）
🏗️ 架构原则 坚持模块化与开闭原则，禁用阻塞调用，优先非阻塞任务链（getNow/thenRun…）
🆕 新功能 新功能优先放入独立模块或插件；文档与示例随代码一并提交
✅ 质量保证 提交前请在本地构建通过；必要时补充/更新 docs 与示例
graph LR
A[🍴 Fork 项目] --> B[🌿 创建分支]
B --> C[💻 开发功能]
C --> D[🧪 测试验证]
D --> E[📝 完善文档]
E --> F[📤 提交 PR]
F --> G[🔄 代码审查]
G --> H[✅ 合并主分支]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#fce4ec
style F fill:#e0f2f1
style G fill:#f1f8e9
style H fill:#e8eaf6
