无界面后端

官方后端另有一个不画任何东西的产物:它处理入口点、元数据与协程,其余一律是静默空转。装在专用服务端上时,核心库的入口系统照常工作(只有声明里含 server 的入口会被加载,其余在过滤阶段就出局),而绘制与输入查询不会发生——那一侧本来就不该有这些路径。

它沿用后端本体那个 mod id,因此它是同一个 mod 的一种构建,不是额外的 mod:核心库的元数据硬依赖 kotlinmcuibackend,装哪一份、装在哪一侧由你决定。产物名形如 KotlinMCUI-backend-<版本>+headless+<加载器>。

该装哪一份

场景 装什么
专用服务端 无界面版
客户端,配自带窗口的后端 无界面版 + kotlinmcuiwindow
客户端,要用游戏内界面 带界面的那份(分支清单见概览)

无界面版发现 kotlinmcuiwindow 已经装了时会保持沉默,把发布权让给那个 mod。带界面的那份会加载客户端类,专用服务端上应该改用无界面版。

它不引用 Minecraft,也不要求某一个游戏版本

无界面版不引用任何 Minecraft 类:它只用加载器自身的 API。元数据因此不声明游戏版本上限,一个加载器一份 jar 覆盖整条线;构建仍钉在一个具体版本上,但产物里没有任何指向它的引用。同理,它的字节码目标是 Java 8,才能在 1.14 与 26.3 上都加载。

运行期依赖由谁提供

这是唯一一处各线不同的地方,取决于该平台有没有现成的 Kotlin 提供者:

分支 Kotlin 与框架运行期 slf4j
Fabric(headless-fabric) 由 fabric-language-kotlin 提供,需自行安装 打包进 jar(约 50 KB)
Forge 1.13 起(headless-forge) 打包进 jar,不需要 kotlinforforge 由游戏提供(1.17 起),不打进 jar
NeoForge(headless-neoforge) 打包进 jar,不需要 kotlinforforge 由游戏提供,不打进 jar
老 Forge 1.7.10–1.12.2(headless-forge-legacy) 打包进 jar(那个年代没有 Kotlin 提供者) 打包进 jar

Fabric 的 slf4j 必须自带:游戏直到 1.17 前后才提供它,而更早的版本上框架的日志器根本初始化不了。Forge 相反——1.17 起 slf4j 在模块路径上,打进 jar 反而会让游戏在加载任何 mod 之前就因模块冲突停下,所以那边交给游戏。

已实测的覆盖范围

均使用未改动的核心库,均为真实服务端或客户端:

分支 覆盖
headless-fabric 1.14.4、1.16.5、1.18.2、1.20.1、1.21.1、26.3
headless-forge 1.20.1
headless-forge-legacy 1.7.10、1.8.9、1.12.2
headless-neoforge 1.21.1(入口构造已验证,打包实跑待补)

Fabric 最早支持的版本就是 1.14,所以那条线一份 jar 已经从头覆盖到尾。与语言提供者同时安装的情况只实测过 Fabric + fabric-language-kotlin(正常);Forge/NeoForge 与 kotlinforforge、kotlinlangforge 共用尚未验证。

能做什么、不能做什么

能:入口发现(按真实环境,服务端上会跑服务端钩子)、元数据(id、版本、配置目录)、协程调度(一个自有的单线程执行器)、配置读写。

不能:任何绘制、任何输入查询、任何界面。这类调用是静默空转而不是抛异常——刻意的选择:它们在那一侧本来就不可达,空转是兜底。translate 返回 null,所以翻译会回落成键名。

预览(-Dkotlinmcui.preview)在它上面只会有”打开”这一步:它没有可截的窗口(capture 返回 null),也不会自己退出(quit 是空转),而需要截图的模式要求写出文件,因此不会成功。想验证无界面版,用 runServer 看日志更直接:入口被发现、无界面后端已发布、服务端正常起世界,就是通过。


This site uses Just the Docs, a documentation theme for Jekyll.