ServerPackCreator API 使用指南：如何集成到你的 Java/Kotlin 项目

ServerPackCreator API 使用指南：如何集成到你的 Java/Kotlin 项目

【免费下载链接】ServerPackCreatorCreate a server pack from a Minecraft Forge, NeoForge, Fabric, LegacyFabric or Quilt modpack!项目地址: https://gitcode.com/gh_mirrors/se/ServerPackCreator

ServerPackCreator 是一款开源工具，能把 Minecraft 的 Forge、NeoForge、Fabric、LegacyFabric、Quilt 模组包（modpack）一键转换为可分发的服务器包（server pack）。而它的核心 API 模块（serverpackcreator-api）可以把这套"模组包转服务器包"的完整能力直接嵌入你自己的 Java/Kotlin 项目中——无论是做自动化发布平台、CI 流水线，还是二次开发 GUI，都只需几行代码。

为什么选择 ServerPackCreator API

大多数自研方案都要自己处理：下载模组加载器安装器、解析版本清单、扫描模组是客户端还是双端、过滤客户端专用模组、生成启动脚本……而 ServerPackCreator API 已经把这些全部封装好了：

• 五种模组加载器全覆盖：Forge、NeoForge、Fabric、LegacyFabric、Quilt
• 自动扫描模组侧别（sideness），自动剔除纯客户端模组
• 内置配置校验，避免生成损坏的服务器包
• 插件扩展机制，可在生成流程的每个关键节点插入自定义逻辑

下图是 ServerPackCreator 的主程序界面，API 提供的正是驱动这些功能背后的同一套核心逻辑：

💡 API 模块的完整包说明见 serverpackcreator-api/module.md。

集成前准备：依赖与配置文件

1. 引入依赖：在你的构建脚本（Gradle/Maven）中添加对serverpackcreator-api模块的依赖；若基于源码构建，直接在 settings.gradle.kts 的多模块工程中引用:serverpackcreator-api即可。建议运行环境为 JDK 17 及以上。

2. 准备配置文件：API 初始化需要一个serverpackcreator.properties文件，用于指定主目录、服务器包输出位置等设置，可参考仓库中 Docker 部署使用的默认配置 serverpackcreator.properties。

第一步：初始化 ServerPackCreator API 实例

整个 API 通过单例入口 ApiWrapper 获取：

import de.griefed.serverpackcreator.api.ApiWrapper import java.io.File val api = ApiWrapper.api(File("serverpackcreator.properties"))

ApiWrapper构造时会自动执行三阶段初始化：创建目录结构与默认文件、加载版本元数据（VersionMeta）与配置处理器、初始化插件管理器与模组扫描器。之后你可以通过api.serverPackHandler、api.configurationHandler、api.versionMeta等属性直接访问各功能组件。

第二步：创建服务器包配置 PackConfig

所有生成任务都基于一个配置模型 PackConfig。它支持直接在代码中构建，也可从 TOML 配置文件加载。核心字段包括：

val config = PackConfig() config.modpackDir = "./My Modpack" config.minecraftVersion = "1.20.1" config.modLoader = "Forge" config.modLoaderVersion = "47.2.0"

第三步：用 ConfigurationHandler 校验配置

生成前务必先校验，这是官方推荐工作流的关键一环。ConfigurationHandler 会检查版本兼容性、模组加载器匹配度、文件路径有效性等，并返回一个ConfigCheck结果对象供你逐条判断：

val check = api.configurationHandler.checkConfiguration(config) // 根据 check 的结果决定是否继续生成

⚠️ 官方明确提示：未经校验的配置虽然也能生成，但不提供任何保证与支持。

第四步：调用 ServerPackHandler 生成服务器包

校验通过后，把配置交给 ServerPackHandler 的run方法，即可完成整个生成流程：复制模组与资源文件、下载模组加载器安装器、过滤客户端模组、生成server.properties与启动脚本、打包 ZIP 归档。

api.serverPackHandler.run(config)

ServerPackHandler同样暴露了copyFiles、zipBuilder、createServerRunFiles等细粒度方法，如果你只想复用其中某个步骤（比如仅做 ZIP 打包），完全可以手动编排调用顺序。

进阶：用插件与监听器扩展生成流程

如果你的项目需要深度定制，ServerPackCreator 提供了完善的插件扩展点（ApiPlugins），覆盖生成流水线的关键节点：

• PreGenExtension—— 生成前：在服务器包文件写入磁盘前执行自定义处理
• PreZipExtension—— 压缩前：调整即将打包的文件结构
• PostGenExtension—— 生成后：对成品服务器包做后处理
• ConfigCheckExtension—— 在配置校验阶段注入你自己的检查规则
• TabExtension / ConfigPanelExtension—— 为 Swing GUI 添加自定义标签页与配置面板

更轻量级的集成方式是通过监听器：在 SPCListeners 中定义的SPCConfigCheckListener、SPCPreServerPackGenerationListener、SPCPostGenListener等接口，配合addEventListener即可在对应阶段收到回调。官方示例插件 Example.kt 演示了如何继承ServerPackCreatorPlugin并注册全部监听器，完整工程参考 serverpackcreator-plugin-example。

API 核心组件速查表

学习路径与常见误区

推荐学习顺序：先读 serverpackcreator-api/module.md 了解各包职责 → 跑通"初始化 → 配置 → 校验 → 生成"四步 → 再研究插件扩展与 VersionMeta 的版本解析。

常见误区：

• ❌ 跳过配置校验直接生成——官方明确不对未校验配置的结果负责
• ❌ 频繁创建ApiWrapper实例——它是单例，始终用ApiWrapper.api(...)获取
• ❌ 用模组的项目名过滤客户端模组——clientMods字段需要的是文件名而非 CurseForge/Modrinth 项目名

掌握这四步工作流后，你就可以在自己的 Java/Kotlin 项目中自动化地批量生成 Minecraft 服务器包，把 ServerPackCreator 的强大能力变成你产品的核心竞争力。

【免费下载链接】ServerPackCreatorCreate a server pack from a Minecraft Forge, NeoForge, Fabric, LegacyFabric or Quilt modpack!项目地址: https://gitcode.com/gh_mirrors/se/ServerPackCreator