".NET Minecraft 启动器库,支持所有版本、身份验证、Forge、Java 和跨平台运行"
CmlLib/CmlLib.Core · github.com
想创建自己的 Minecraft 启动器,不再依赖官方启动器?CmlLib.Core 是一个 .NET 库,可以处理身份验证、版本管理、模组加载等各种复杂工作,让你专注于构建真正符合自己需求的启动器。
这个项目能做什么
CmlLib.Core 是一个专为自定义 Minecraft 启动器开发者设计的 .NET 库。如果你曾好奇社区如何分发游戏的模组版本,或者某些服务器如何管理自定义客户端配置,那么这个库正是许多此类基础设施背后的动力。它不是模组,不是客户端补丁,也不是可以直接运行的程序。它是一套负责处理繁琐后端工作的工具,包括下载游戏文件、管理 Microsoft 账户身份验证、使用自定义参数启动游戏,以及支持 Forge 和 Fabric 等模组加载器。
该项目在 GitHub 上拥有 274 个星标,并使用 C# 编写,因此你至少需要具备基本的 .NET 开发能力。说实话,它的目标用户就是启动器开发者,而不是只想更轻松游玩游戏的普通玩家。
什么时候需要构建自定义启动器
关于自定义启动器,有一点需要说明:大多数玩家并不需要它。官方启动器足以正常运行原版 Minecraft,但在一些实际场景中,自定义启动器确实很有价值。
也许你正在运营社区服务器,希望分发一个已经配置好自定义模组和资源包的客户端。新玩家加入后只需下载启动器并点击开始,一切就都准备好了。不再需要讨论“我该安装哪些模组?”,也不会再遇到损坏的配置。让你的服务器出现在我们的 Minecraft 服务器列表中是一回事,确保玩家能够顺畅连接则是另一回事。
或者,你正在开发整合包分发平台,需要严格控制版本管理和模组更新。你也可能正在为特定地区或游戏模式开发专用启动器。在这些场景下,CmlLib.Core 不再是功能过剩,而是会变得非常实用。
入门:安装与第一步
安装 CmlLib.Core,就是通过 NuGet 将它添加到 .NET 项目中。如果你以前使用过 NuGet 软件包,这个过程会非常熟悉。
dotnet add package CmlLib.Core安装完成后,就可以开始编写启动器代码了。README 提供了一个基础示例:获取所有可用版本,然后启动游戏。代码如下:
using CmlLib.Core;
var launcher = new MinecraftLauncher();
var versions = await launcher.GetAllVersionsAsync();
foreach (var version in versions)
{
Console.WriteLine($"{version.Type} {version.Name}");
}仅凭这段代码就能完成很多工作。它会查询 Minecraft 的版本清单,并返回所有可用内容,包括原版正式版、快照版和旧版本。该库负责连接 Microsoft 的服务器、解析清单,并将结果整理为清晰的 C# 对象。
下一步是真正启动游戏,到了这里,事情就开始变得实际了。
using CmlLib.Core;
using CmlLib.Core.ProcessBuilder;
var launcher = new MinecraftLauncher();
var process = await launcher.InstallAndBuildProcessAsync("1.21", new MLaunchOption());
process.Start();这一个调用就能下载 1.21 版本的游戏文件、验证文件,并创建一个可直接执行的 Windows 进程。必要时,该库甚至还能管理 Java 运行时。
值得了解的核心功能
身份验证。现代 Minecraft 要求使用 Microsoft 账户进行身份验证,Mojang 账户已经成为历史。CmlLib.Core 可以处理完整的 OAuth 流程、令牌刷新和会话管理。你无需弄清 Microsoft 身份验证系统背后那些令人头疼的细节。事实上,除非你特别喜欢阅读晦涩的 API 文档,否则我并不建议你自己研究它。
版本管理。原版版本、快照版、模组版本和旧版本,该库可以查询所有内容,并以统一方式呈现。你可以获取全部版本,再筛选出所需内容,也可以直接指定 1.21 等特定版本,让该库自行找到正确的版本。
模组支持。CmlLib.Core 支持 Forge、Fabric 和 LiteLoader 等模组加载器。启动模组版本的方式与启动原版游戏基本相同。该库会分别下载模组加载器安装程序和游戏文件,然后正确组合它们。
跨平台支持。无论是 Windows、Linux 还是 macOS,该库都会帮你处理平台之间的差异。编写一次即可在各个平台运行。对于需要向不同设备用户分发启动器的开发者来说,这一点非常重要。
进度跟踪。已经下载了 2GB 中的 50MB?该库会在下载和验证文件时触发事件,因此你的启动器可以向玩家显示真正的进度条,而不是一个令人绝望的旋转圆圈。README 展示了文件进度和字节进度回调,这确实是一项考虑周到的 API 设计。
构建真正的产品,更困难的部分
创建一个能够下载并启动游戏的基础启动器并不难。真正的复杂性来自自定义功能,例如 GUI、自定义设置、社区模组集成,以及启动器自身的自动更新。

CmlLib.Core 为你提供基础能力,但它并不是官方启动器那样完整的启动器框架。UI、用户体验、品牌设计,以及一切让启动器看起来像成熟产品的内容,都需要由你负责。不过,与 Mojang 服务器通信、管理游戏文件和处理身份验证等困难工作已经得到解决。
该项目还提供了 GitHub 示例启动器的链接,这非常有帮助。与只看文档相比,查看真实代码如何运行实际功能要实用得多。
容易踩坑的地方
Java 运行时的复杂性。Minecraft 需要 Java,而 Java 版本兼容性相当棘手。CmlLib.Core 可以协助安装 Java,但你仍然需要了解哪些 Java 版本适用于哪些 Minecraft 版本。这个库可以封装相关流程,却无法让 Java 的兼容问题凭空变简单。
文件路径和目录。默认情况下,该库会使用操作系统的标准游戏目录。Windows 使用 AppData/Roaming/.minecraft,Linux 使用 ~/.minecraft,macOS 使用 ~/Library/Application Support/minecraft。你可以自定义目录,但如果配置错误,启动器就可能把文件安装到奇怪的位置。如果游戏无法启动,请查看官方文档。
身份验证令牌过期。Microsoft 令牌并不会永久有效。如果你开发的启动器会连续开启数天,就需要处理令牌刷新。该库提供了相关功能,但你必须真正使用它。忽略这一点,用户就可能在会话过程中莫名其妙地退出登录,体验会非常糟糕。
与其他方案的比较
你可以从头编写自己的启动器,直接与 Mojang 的服务器通信,但最好不要这样做。CmlLib.Core 已经处理了 API 变更、边缘情况和协议细节,而这些问题往往要投入数周后才会被发现。没必要把时间浪费在这里。
你也可以基于官方启动器进行修改,但这种方案很脆弱,而且在法律层面存在灰色地带。以 CmlLib.Core 为基础进行开发更加干净,也更容易维护。
在 Modrinth 和类似平台上,你还能找到其他启动器工具,其中不少专门面向整合包。如果你只是要为社区服务器或特定整合包制作一次性启动器,这些工具可能更快捷。但如果你希望拥有完全控制权,并在未来继续添加自定义功能,CmlLib.Core 能为你提供合适的基础。
开始编码之前
CmlLib.Core 目前仍在积极维护并持续更新。最新版本为 v4.0.4,解决了 API 主机变更问题,并增加了对 Quilt 模组加载器的测试。这个项目正处于理想阶段,既足够稳定,可以用于生产环境,又仍在不断改进。
建议阅读官方 wiki,其中提供英语和韩语版本。文档内容很完整,比起只看示例来猜测库的使用方式要好得多。编码之前先花 30 分钟阅读文档,真的很值得。
如果遇到问题,该项目还有 Discord 社区。已经解决过同类问题的真实用户通常很快就会出现并提供帮助。
构建自定义启动器并非易事。但如果你确实需要一个,CmlLib.Core 可以消除最大的痛点,也就是 Minecraft 客户端本身的管理。其余部分只是软件工程,而这本来就是开发者需要完成的工作。



