Fabric 后端实现
这一页讲官方后端的 Fabric 实现(独立仓库 KotlinMCUI-backend,Fabric 侧维护 fabric-26.3、fabric-1.21.1 与 fabric-1.20.1 三条分支)为什么这么做;Forge / NeoForge 侧的差异见移植。契约本身见后端接口,使用与构建见后端一章;下文除 1.20.1 分支的差异一节外,描述的都是当前这一支(26.3)。
组装方式
后端要填的是四个互相独立的职责接口:渲染、环境元数据、平台工具、输入。实现上是一个薄聚合对象 + 接口委托:
- 每个职责各自是一个单例实现(渲染器、元数据、工具、输入),互不引用,也不引用聚合对象本身;
- 聚合对象只做委托,并把对外暴露的类型固定成该版本的图形对象与屏幕类型。
好处是每个职责可以单独替换、单独推理;代价是聚合对象本身没有逻辑,读代码时要在几个文件之间跳。
“互不引用”是约束而不是风格。 聚合对象的类初始化会立刻读取四个单例的 INSTANCE,如果某个单例在自己的静态初始化里反过来读聚合对象,先被初始化的那一侧就会看到 null(另一侧的 INSTANCE 还没赋值),结果是 ExceptionInInitializerError,而且只在这两个类的初始化顺序反过来时才出现。输入的调度器因此取自”工具”这一职责,而不是聚合对象。
三处 Mixin,三种不同的理由
后端的适配难点都在”核心库不该知道平台类型”这条线上,凡是必须插进游戏内部时机的地方就只能用 Mixin。
注册输入回调:GLFW 的回调必须在窗口存在之后安装,而窗口是在游戏主类构造时创建的。因此在主类构造器返回处注入一次,立刻安装全部回调。回调里统一遵守一条规则——先给框架,框架没消费才调用被替换掉的上一版回调,这样原版界面(例如原版文本框、聊天栏)仍然可用。
把界面插进 GUI:从 26.x 起,GUI 渲染分成”提取渲染状态”和”统一绘制”两步。后端在 HUD 的提取阶段插入,把 DSL 界面作为新的绘制层追加进去,并在调用前把位姿缩放 1/guiScale。这里的 guiScale 是游戏原版的 GUI 倍率,用于把 GUI 位姿空间换回输出目标像素;它不再是核心 renderer 的成员。后端另外在构建前显式设置 root.scale,完整契约见输出坐标与尺度。
选择 HUD 阶段而不是某个 Screen,是因为这个后端只建一个根,Screen 与 Overlay 全挂在它下面;HUD 每帧都会跑,天然覆盖两种界面。根不是进程单例,换成多个输出时各根仍互相隔离。
给位姿矩阵补第三行:二维仿射矩阵无法表达透视。后端直接给 JOML 的二维矩阵类补了一行(第三行),并在顶点变换的入口处做投影除法,于是不需要自定义着色器就能支持 perspective。
代价要说清楚:这是对库类的全局改动,所有使用该矩阵的代码都跟着被改(虽然默认值下行为与原来完全一致)。栈的压栈/出栈恰好是”从另一个矩阵赋值”实现的,所以只要赋值与拷贝构造器都带走第三行,嵌套就是安全的——这也解释了为什么这类改动看起来”只差一行”却容易漏。
为什么需要访问扩大器
Mixin 解决”插进去”,访问扩大器解决”看得见”。后端需要访问的私有成员分四类:
| 类别 | 用途 |
|---|---|
| 渲染状态与裁剪栈 | 提交几何时要带上当前的裁剪区域 |
| 字形来源 | 按字体描述取字形,否则只能用默认字体 |
| 构造器 | 需要构造带完整样式的字形与物品栈 |
| 管线注册 | 注册自定义图元拓扑的渲染管线 |
代价是这些签名会随游戏版本变化,且报错发生在运行期。长参数构造器(样式、物品栈)与参数具体的方法(内部 blit)最容易失效,移植时要优先核对,见移植。
渲染模型带来的约束
- 绘制是延迟的:调用绘制原语时只是把”渲染状态”入队,真正的绘制发生在帧末。因此提交时必须快照位姿矩阵(按值拷贝),不能把位姿栈的引用存进队列。
- 几何由核心算好:核心交来的是一个四边形的四个角、四个角的颜色,以及(带纹理时)图像像素空间里的源矩形。后端把它们塞进自己注册的管线;带纹理时把 UV 按图像声明的像素尺寸归一化。因为绘制是延迟的,六个顶点只能存在绘制元素的字段里——不能共用暂存数组,否则先入队的元素会在提交时读到后来者的数据。
- 裁剪坐标系:裁剪矩形以物理像素给出,游戏会按当前位姿把它变换到屏幕空间,所以裁剪必须在变换之后的坐标系里提交——这也是核心把裁剪做成装饰器(而不是父容器属性)的原因。
- 没有固有尺寸的绘制:矩形、图像、物品都由核心算好尺寸再交下来,后端不做布局推断。
输入与输入法
- 所有事件统一经主线程调度器派发(游戏自身就是一个
Executor),保证处理时机落在确定的帧内位置,而不是在 GLFW 回调的调用栈里直接改 UI 状态。 - 未消费的事件回落到上一版回调,原版行为得以保留。
- 字符输入按 UTF-16 单元投递:补充平面字符是一个事件但两个单元,后端把它拆成代理对;否则会被截断成私用区字符。
- 输入法分两条路:有焦点组件上报预编辑区域时,组合文本由框架(或组件自己)绘制,此时不透传给平台;没有时说明框架没在用输入法,要透传,否则原版输入会失效。
- 鼠标位置由光标回调维护,按键/滚轮/拖放/按键走同一套”先框架后平台”的判定,返回值决定是否继续传播。
自检页为什么在框架里
时序在框架里,平台只提供两个动作。 框架的预览会话(io.github.u2894638479.kotlinmcui.backend.DslPreview)负责解析页面引用、等首帧、按帧等待、判定、截图与退出码;后端只需实现 DslRootUtils 的 capture(把当前帧写成文件并返回路径——MC 是在 IO 线程写完才回调的,所以它是 suspend)与 DslPlatformUtils 的 quit(退出码为 0 走游戏自己的关闭,非零则直接离开,因为游戏关闭总是报成功,而不可门禁的运行没有意义)。页面本身是框架里公开的顶层 context(DslContext) 函数,用引用指定,不需要注册。
框架里没有”屏幕背景”这个概念,所以预览也不补背景。 背景就是一个组件:DefaultBackground() / defaultBackground() 铺的是它所在容器的矩形,放在哪里、与子组件的绘制先后都由页面自己决定。于是”页面打开了”和”页面有背景”是两件独立的事——自检页要背景就自己挂,框架不做隐式补全,预览会话也就只调用页面本身。
解析失败时预览画的是错误页,而不是只写日志。 错误页用的是框架自己的 DSL(Column/TextAutoFold 那一套),内容就是”你要的引用 + 试过哪些候选 + 每个为什么被否”,所以它同样要等平台渲染首帧之后才建——否则会被平台的加载画面顶掉,截到的就是加载画面而不是原因。失败路径的三种信号各管一段:屏幕上的错误页给人看,日志里的 ERROR 行给翻日志的人,非零退出码给机器;capture 打开时截的是错误页,因此那张图同时也是失败报告。
预览不会应答原版的无障碍引导屏。 那个引导屏在第一次进入某个游戏目录时出现并自己朗读(原版为了让需要朗读的玩家能开启朗读而设计),而 options.txt 的 onboardAccessibility 只在玩家回应它之后才会被写成 false。预览的做法是等平台渲染首帧后直接换成自己的页面,因此既不应答也不写回该标记——同一个游戏目录每次启动都会再听到一次,直到有人手动关掉。这是原版行为,不是后端在朗读。
这么分是为了移植:换一个加载器时时序与判定不用重写。同理,判定依据必须来自框架自己:
- 等帧,不等秒:根统计帧数(
DslRootState.frameIndex),而后端在游戏加载完成前不渲染,所以帧数保持 0——”平台真的渲染了一帧”同时说明加载已完成(这时开屏才不会被顶掉)。用秒数会在慢机器上截到还没加载完的页面,而且运行照样通过。26.x上”加载完成”要看两件事:isGameLoadFinished在游戏自己的加载画面开始淡出时就为真,只看它会让首帧落在淡出期间,于是页面与截图背后都留着启动画面;Gui.overlay()是公开的,要求它也为 null 才算就绪(1.20.1/1.21.1用的是mc.overlay == null,语义相同)。 - 渲染异常:页面在渲染期间抛出的异常记录在根的
renderFailure上,随后继续抛出(不改变平台行为),由会话转成非零退出码。 - 判定靠肉眼与日志,不做像素比对:截图里的背景取自会转动的全景图,逐像素差异既可能来自真实的渲染改动,也可能只是采样时刻不同,拿它判断”改动是否生效”会得出错误结论。
DslFunction 只在参数位置存在。 框架里所有需要它的地方都把它当形参(create(title, dslFunction)、showScreen(title, function)、tooltip(function)),由调用方用尾随 lambda 填,框架在自己的上下文里调用它。不要在无 context 的函数里试图构造一个 DslFunction 值:Kotlin 只对参数位置与初始化器传播 context 类型,when 分支不会,函数引用也不行。预览会话按引用解析出来的页面正是这么调用的——在 create(name) { page.draw() } 的尾随 lambda 里,context 由那个形参自带。
为什么 HUD 要等游戏加载完成
后端的每帧入口(DefaultBackend.render)在 Minecraft.isGameLoadFinished() 之前直接返回。这不是保守,而是必须的:
框架的文字与贴图都走游戏自己的 GUI 管线(字体、文字管线等)。首次资源重载应用之前,ShaderManager 的 shader 源码缓存还是空的,此时向它要一个 shader 会拿到 null——VulkanDevice.compileShader 于是编出一个 shader 无效的管线,而这个无效结果会被缓存整个进程。OpenGL 对此宽容(管线懒编译,首次真正使用发生在缓存就绪之后),Vulkan 严格:真正要画文本时 VulkanRenderPass.setPipeline 直接抛 Pipeline is not valid (may contain invalid shaders?),表现就是”切到 Vulkan 立刻崩”,日志里是 Couldn't find source for VERTEX shader (minecraft:core/text)。
HUD 从第一帧就画(加载界面上也会画覆盖层),所以它正是那个”过早的调用者”。把 HUD 推迟到游戏加载完成之后,问题根除;这个顺序约束对每个后端都成立,见后端接口的契约列表。
复现与验收:JAVA_TOOL_OPTIONS="-Dkotlinmcui.preview=<任一页面引用>" ./gradlew runClient --args="--graphicsBackend vulkan"(--graphicsBackend 是原版启动参数,取值 default/opengl/vulkan,强制后游戏忽略选项里的 preferredGraphicsBackend)。
fabric-1.20.1 分支的差异
同一套契约在两个 Minecraft 版本上的落地方式不同。这里只列必须按版本改写的部分:
- HUD 就绪门控:1.20.1 没有
isGameLoadFinished,用Minecraft.getOverlay() != null(加载覆盖层在场)等价表达。 - 绘制原语:1.20.1 的
RenderType既没有三角形类型、create也不公开(NO_CULL/NO_DEPTH_TEST等还是 protected),所以热路径用原版批处理——未贴图走RenderType.gui()的一个四边形,贴图且四角同色走innerBlit;只有”贴图 + 逐顶点颜色”和三角形列表renderTriangles走公开的Tesselator+BufferBuilder立即模式。立即模式不是RenderType,必须自己disableCull()/disableDepthTest(),否则一个图形都画不出来(多边形自检页曾经只剩文字,就是这个原因)。 - 四边形的对角线:
RenderType.gui()是 QUADS,用哪条对角线切开由平台决定;框架产生的四角颜色都是轴仿射的(滑块轨道的(c0,c1,c0,c1)、装饰器的单色),所以看不出来,但四角颜色完全任意的调用会看到差异。 - 透视:1.20.1 的位姿矩阵是
Matrix4f,后端直接用九参构造把m20/m21/m22带进去,不需要 26.2 那种给 JOML 二维矩阵补第三行的 mixin。 - HUD 注入点:
GameRendererMixin重定向GuiGraphics.flush()(26.2 是在Gui.extractRenderState里重定向applyCursor);注入时把位姿按原版 GUI 倍率的倒数缩放,框架的坐标因此仍是输出目标像素。root 的范围与指针也须按实际 framebuffer 与窗口尺寸对齐。 - 截图:
Screenshot.grab(gameDirectory, name, target, consumer)的第一个参数是游戏目录,平台自己会拼screenshots/并创建它。 - 输入法:GLFW 3.3(1.20.1)没有预编辑光标 API,
setPreeditArea是空实现(26.2 会调glfwSetPreeditCursorRectangle);键盘事件、字符输入与文件拖放的行为一致。 - 未知键码:GLFW 键码到框架
Key的映射是一张”码 → 码”的表,未列出的码原样透传,再用Key(code)构造——Key(code)不校验,而Key.custom(code)只接受框架自己的 custom 区间(CUSTOM_RANGE_START起)。不要用Key.custom(Key.A.code + i)这类写法:它的参数应是平台码,传框架自己的键码既错又会抛。另外别把这张表的构造放进会被输入回调触发的顶层初始化器里:一旦它抛异常,InputKt.<clinit>失败,任何一次输入都会崩(表现为ExceptionInInitializerError+custom key codes must be in the extension range)。1.20.1 后端在register里主动构造并记录映射条数,正是为了让这种表在启动时就暴露问题。 - 类初始化顺序:
Input的调度器取自Utils而不是聚合对象DefaultBackend,否则两个类会互相初始化并留下半个对象。
发布
发布由标签驱动:publishMods 只在目标标签尚不存在于 origin 时启用,标签名是 v<版本号>(+ 换成 -),发布类型由版本号里的关键字决定(alpha / beta / 其它视为正式)。Modrinth、CurseForge 与 GitHub Release 各需要一份环境变量里的 token;没有 token 时不要执行发布任务。
“哪些参数有默认值”只有 Kotlin 反射说得出来。 Java 反射能看到的唯一痕迹,是编译器为带默认值的参数生成的 name$default 方法——而它只要有一个参数带默认值就存在,所以说不出是哪几个:(ctx, required: Int, optional: String = "d") 与全默认的页面在 Java 反射下无法区分,按”有 $default 就是页面”的规则,前者会被静默传入 0/null。判定因此改走 Kotlin 反射:KFunction.parameters 里 kind 为 VALUE 的那些就是页面自己的参数(上下文参数有独立的 CONTEXT kind),逐个问 isOptional,全为真才接受,否则拒绝并点名。isOptional 的定义还带出第二个坑:成员函数覆写时,超类声明有默认值也算 optional,可这种类自己没有 name$default 可调,所以”全都 optional”之后还要确认 name$default 确实存在于这个类上。
Kotlin 反射是编译期依赖:核心库只写 compileOnly(kotlin("reflect")),发布 jar 里没有它。运行期由平台提供——Fabric 的语言加载器已经把 kotlin-reflect 打进 META-INF/jars/,版本跟着它钉的 Kotlin 版本走。环境里没有 kotlin-reflect 时,带额外参数的页面一律被拒绝并写明原因,而不是退回”假定全默认”。
同一套分工适用于核心库的其它平台依赖:slf4j-api 与 fastutil 由 Minecraft 自带(它们是启动器库,不在 merged jar 里),kotlin-stdlib、kotlinx-coroutines-core 与 kotlinx-serialization-{core,json} 由 FLK 的 META-INF/jars/ 内嵌。所以核心库对它们只声明编译期依赖,compileOnlyApi(公开签名里出现过的)或 compileOnly(只在实现里用到的),不写进发布元数据的运行期依赖——否则消费者会被拖进第二份 coroutines/serialization,和 FLK 内嵌的那份撞在一起。后端不需要为这些做任何事:FLK 已经把库带进游戏进程。
调用仍然走 $default:掩码位把 context 参数也算进去,页面自己的参数从第 1 位起;零值永远不会被读到,这正是”参数全部有默认值”换来的。返回值类型不参与判断,页面返回 DslChild 还是 Unit 都一样。
已知问题
- 字体只支持默认字体:取字体接口忽略名称参数,同一实例服务所有名称(满足核心的”同名同实例”要求,但不能按
FontDescription切换)。 - 本地图片通过自定义标识注册进纹理管理器,没有卸载路径;”强制重新加载”只是把缓存项删掉再走一遍加载流程。
- 变换的最小粒度是整个子树:核心的变换语义是一棵子树共用一个矩阵,因此无法让同一容器内的不同子节点使用不同的透视中心。