后端

核心库不认识任何 Minecraft 类型。所有平台能力都通过 backend 包的接口暴露,由配套的后端 mod 实现——这样核心库能独立编译测试,也能让同一个 jar 适配不同加载器与不同游戏版本。

这一页讲契约。官方实现(独立仓库)是怎么满足它的、踩了哪些平台限制,见 Fabric 后端实现;后端的使用与构建见后端一章。

接口组合

没有”后端对象”这个东西了。后端按职责分别实现下面几个接口,框架只认这些接口,不认”一个实现了全部的后端”:

两组的边界有一条判据:元数据是”进程启动时就可读、且必须无副作用的事实”,工具是”需要一个活着的平台才能执行的操作”。名称、本地化与打开链接都要求平台已经起来,所以它们属于工具而不属于元数据。

接口 职责 归属
DslPlatformMetadata 目录、游戏版本、加载器、运行环境 进程级
DslPlatformUtils 本地化、退出、本地图像加载与强制重载、世界判定 进程级
DslRootUtils 剪贴板、朗读、按钮音效、打开链接、截图、会话调度器 每个根
DslRootRenderer<RP> 绘制原语、裁剪、变换、取字体 每个根
DslRootInput 按键/鼠标状态查询、鼠标位置、IME 候选区 每个根
DslRootScreenFactory<SC> 创建 Screen 每个根

一个对象可以同时实现多个接口(例如 DslPlatformUtils 与 DslRootUtils 用同一个实现),实现者不因”分了接口”就必须拆成多个对象。

DslScreenHolder<SC> 不属于上面任何一个,它是 create() 的返回值,负责持有平台侧 screen 对象并实现 show()。

抽象成员总数为三十余个:渲染接口的绘制成员是四个重载——四边形与三角形列表各有无纹理、带纹理两种形式。纯色矩形、渐变矩形、贴图矩形都是四边形的扩展函数(不额外分配)。它们是扩展而不是接口成员,因此没法被覆写——后端想要平台自己的快速路径(例如原生的实心矩形填充),就在无纹理四边形重载里判断,这样所有调用方一起受益。

启动顺序:DslRuntime

进程级只有元数据与一组平台工具,分两段,框架为这两段各提供一个入口,模组与后端都不再自己拼接顺序:

DslRuntime.install { Metadata }            // 模组初始化:平台事实 + 入口发现
// …客户端构造完成、可以建界面之后…
DslRuntime.start { DefaultUtils }          // 先到先得,返回 false 表示这次没生效
  • install 立刻读一次元数据,并完成入口发现与框架自己的配置读取——这些只需要元数据。
  • start 交出 DslPlatformUtils,只在第一次生效。第二个后端会被拒绝并记一条日志而不抛错:同一个游戏实例只应该装一个后端,而”装了两个”是用户的环境问题,不该升级成客户端崩溃。被拒的那一方从返回值和日志知道自己没有生效,但照常建自己的根、照常服务——是否自动驱动主循环由它自己决定,框架不代管。
  • 两个 provider 变量(元数据、工具)是 internal,后端(独立模块)只能走这两个入口。两者都在锁内执行:单次语义必须在任何线程上都成立。
  • 只依赖元数据的路径(配置读写、版本与环境查询)永远走 dslMetadata;它只来自 install,没有”回退去构造后端”这条路。
  • 运行时的状态只有三件事:installed、元数据 provider、工具 provider。没有任何根——根属于建它的后端。

两条契约:

契约 理由
元数据实现不得有副作用 它在模组初始化阶段就会被读,那时窗口、渲染器、语言数据都还不存在
建根与建界面只能在 start 之后 平台发布之前,界面所需的渲染器、输入、调度器都还不存在;提前建根得到的不是”稍后能用的根”,而是根本不该存在的对象

根:由后端建、由后端驱动

框架不发根。后端在 start 之后自己构造:

val root = DslRoot(input, renderer, screenFactory, rootUtils)
val entryOverlay = installEntryOverlays(root) // 在挂载任何页面之前
  • renderer 可空:为空表示这个根不绘制(连字体也没有)。需要绘制的组件会在使用处响亮失败。无 renderer 的 root 仍须显式设置 root.scale,没有单位尺度回退。
  • 根是通用树容器,初始 children 为空。它不引用入口 UI;需要入口 Overlay 的后端在创建根后、挂载页面之前调用 installEntryOverlays(root)。不调用也能正常建根和挂页面,只是没有入口 Overlay(包括 DebugOverlay)。安装器验证空树、打开状态与工厂后才创建 Screen,重复或乱序安装不会产生半截状态;返回的句柄用于卸载,语义见入口。
  • 根不负责渲染。每帧后端先写 root.rect 和 root.scale,然后在 context(renderer, 参数) 里调用 root.component.render()。首次构建前必须初始化尺度;顺序是契约,渲染期会把 rect 复制到每个已挂载的屏。完整规则见输出坐标与尺度。
  • 屏的一生只属于创建它的那个根。root.children.collect(screen) 只接受该根工厂创建、且尚未关闭的 DslScreen;跨根挂载、同一屏同时挂载两次、挂载已关闭的屏都会在改动子列表之前失败。入口 Overlay 由安装器经同一条公开挂载路径加入。remove 只是隐藏,不释放屏,也不改变归属;同一个根可以在屏仍打开时再次挂载它。根的子节点句柄不能 change 成别的组件,挂载检查没有旁路。
  • 同一进程里有多个后端时,各建各的根,互不可见——框架里没有”进程根”这个概念。焦点、悬停、IME 与 session 也都是每根一份。
  • 拆除门:root.close()(幂等)让”继续用这个根”变成响亮失败——访问/挂载/卸载子节点、component.render()、setFocus、创建新屏、处理键盘与指针按下、派发 IME 都会抛,晚到的一帧或输入因此不会改到一个没人看的根。它关闭该根仍拥有的所有屏,包括当前隐藏的屏,释放它们的 stable/local 状态并取消根 session;批量关根不调用每屏的 onClose,关闭后也不再补发导航。已经自行关闭的屏在终止释放完成时就从归属表移除,根不会再次关闭它。它不负责停你的定时器/执行器/录制器:顺序是先 close(),再停你自己的驱动。root.isClosed 报告状态。
  • post 在根关闭后两条分支都不执行:同线程分支先检查状态,异线程分支在 sessionScope 中被取消,且执行前再检查一次。
  • 原生失焦须取消每个活跃身份。逐个提交 root.dispatchPointer(PointerEvent.Cancel(id)),不能伪造 Up;原生表面捕获的丢失同样处理。

预览

预览是工具,不是进程事实:DslPreview.start(root),显式调用,画进你给的那个根。平台发布不会再顺带触发它。

渲染原语与不变量

框架要求后端实现四个绘制重载:四边形与任意多边形的三角形列表,各自分无纹理、带纹理。矩形是绝大多数内容的形状,多边形只有圆、圆角一类需要逼近时才用。

fun renderQuad(rect: Rect, lt: Color, rt: Color, lb: Color, rb: Color)
fun renderQuad(rect: Rect, lt: Color, rt: Color, lb: Color, rb: Color, image: ImageHolder, uv: Rect)
fun renderTriangles(vertices: MeasureArray, colors: ColorArray)
fun renderTriangles(vertices: MeasureArray, colors: ColorArray, image: ImageHolder)

四个角依次是左上、右上、左下、右下,几何上可以分成 (lt, rt, lb) 与 (rt, rb, lb) 两个三角形;颜色却由四角在未变换矩形上定义的同一个双线性场决定,三角分片不能带出独立的颜色模型。四边形要么完全无纹理,要么同时给出非空 image 与 uv;ImageHolder.empty 是合法的“没有图像”输入,不会变成无纹理。uv 给出图像像素空间里的源矩形,九宫格与平铺靠越界 UV 加环绕模式表达,后端不得钳制。

三角形使用 MeasureArray(底层 DoubleArray)与 ColorArray(底层 IntArray),没有逐顶点对象。设 N = colors.size:无纹理每顶点 x, y,要求 vertices.size == 2N;带纹理每顶点 x, y, u, v,要求 vertices.size == 4N;两者都要求 N % 3 == 0,两数组为空是合法空绘制。结构不匹配在查资源、写命令前抛 IllegalArgumentException,即使图片为空也一样。详见图元输入设计。

像素语义见渐变与合成:四边形四角在未变换矩形的局部坐标里定义一个编码 sRGB、预乘浮点的双线性场;三角形按重心权重插值;采样 texel 乘到预乘渐变上;每笔绘制最终对已有目标做一次 source-over,颜色与目标 alpha 都要正确。渐变域与 UV 无关,裁剪只限制覆盖、不重启渐变,正 w 透视保持源局部场。

四边形重载必须保持零分配,这是设计约束而不是巧合。 参数全是 value class 或已有引用,所以框架侧的矩形与贴图方法自身不产生垃圾。四边形最初用“顶点列表 List<Pair<Position, Color>>”:Position 是普通类、Color 与 Measure 是 value class,装进泛型集合就会逐个装箱,实测每次纯色矩形分配 648 B、每次贴图矩形 1056 B(约 25 个对象)。九宫格一次绘制要发 9 个贴图矩形、可编辑文本的选区是每个选中字符一个矩形,这些调用点会把单次成本成倍放大。因此不要再引入用集合表达顶点的图元。

三角形列表同样不应在框架侧逐帧重建数组。延迟绘制必须把调用方借用的数据拷一份;renderQuad 的顶点数固定,可以放进字段,而三角形个数不固定。数值无效时整笔跳过;带纹理重载的空/待就绪与确认失败分支见图元输入设计。

由此带来几条必须遵守的契约:

  • 坐标空间统一:无额外几何变换时,Measure、Position、Rect、PointerEvent.position、根节点的 rect 处于同一输出像素空间,原点左上、Y 轴向下。root.scale 提供默认 .scaled / .unscaled 换算尺度,不再由 renderer 提供,也不能被重复乘到已计算的绘制坐标上。
  • UV 处于图像像素空间,且允许越界。平铺(repeat)与九宫格策略依赖越界 UV 加纹理环绕模式,后端不得在这里做钳制。
  • root.scale 在同一渲染帧内保持稳定,后端可在下一帧前更新。组件持有的局部 scale 是声明时的快照;withScale 替换它并在退出时恢复,不是几何变换。所有尺度必须有限且大于零。
  • withScissor 按进入时的局部矩形精确求交,withTransform 嵌套复合。矩形按当前局部坐标解释;进入时快照四边与完整局部到输出变换,映射四个角后与已有输出裁剪求精确交集,包围盒只可用于轴对齐加速。空/无效矩形、奇异变换与跨视平面失败关闭,且 block 仍执行一次;两个作用域都在 finally 恢复并原样传播异常,录制型后端即使 block 抛出也必须保持配对的 push/pop 与绘制时状态。完整契约见裁剪与变换作用域。裁剪是提交期的栅格状态:后端进入/退出裁剪作用域前必须把自己排队的顶点先交出去,否则那些顶点会被错误的区域裁掉。变换不是提交期状态——顶点在绘制时就已经烤进了矩阵。
  • HUD 与覆盖层必须等平台就绪后再画。平台在首次加载完成前,它自己的管线/shader 缓存可能还没建好;这时提交一次绘制会让平台编出一个无效管线并缓存整个进程——OpenGL 常常宽容,Vulkan 会直接崩。判断”就绪”是平台知识(Fabric 上是 Minecraft.isGameLoadFinished()),所以这一条由后端在自己的每帧入口把关。
  • getFont(name) 必须对同一名称返回同一实例。文本行在布局期与渲染期分别取字体,并用引用比较判断”字体是否被换掉了”。
  • 帧末必须有兜底提交。框架不再提供 flush():绘制只保证”按调用顺序发起”,什么时候真正提交是后端的事;但一帧结束前,之前排队的顶点必须全部出去。
  • 顺序契约是唯一的硬要求:每个绘制按调用顺序生效。后端可以批处理、延迟、甚至重排,只要保证”相交的保持先后、不相交可任意换位”——不相交的两笔交换顺序不改变任何像素,这是可证明的。mc 后端因此改成先记录再重放:每笔绘制记下屏幕空间顶点与包围盒,用重叠偏序求”批次最少”的顺序后重放。实测 TestLayoutPage:提交 41→5、类型交替 38→3、UI 帧耗时中位数 6186→3058 µs,画面逐像素一致;排序后默认开启断言,用从顶点重算的包围盒(而非排序器缓存的盒)独立复核,任何相交对被反序就抛异常。-Dkotlinmcui.order.reorder=false 可关掉重排回到即时绘制。

变换与裁剪栈由后端自行用平台原生能力实现,只要满足上述语义。具体裁剪机制属于后端私有实现:窗口与 Web 可用当前变换映射的形状裁剪,MC 的原生裁剪或硬件裁剪由后端处理;核心不暴露精度或能力查询,轴对齐 scissor 只能作为加速,不能替代精确投影覆盖。

生命周期

showScreen(title) { /* DSL */ }
// 等价于
root.screenFactory.create(title) { /* DSL */ }.show()

create() 构造 DslDataStore(utils, root, …),其中又构造 DslScreen;这个 store 从此归该根所有,即使以后一直隐藏。create() 不能有后端可见的副作用:入口安装器会调用一次 create("Dsl Overlay") { ... } 来建立 Overlay 层,并且只取其中的 dslScreen、从不 show()。如果 create() 顺手做了注册、着色器初始化之类的可见副作用,就会在安装器执行时发生;后端应把可见动作放在 show() 或自己的界面生命周期里。内部把 store 记入根的归属表不算后端副作用,后端无需自己做。

每帧后端要做两件事:

  1. 把 root.rect 设为整屏尺寸;
  2. 在 context(renderer, renderParam) 里调用 root.component.render(),并在帧末把自己排队的顶点提交出去。

root.component.render() 会把整屏矩形分发给 Overlay 层子节点,然后按逆序渲染。它内部会重算悬停状态,所以输入与渲染不需要各自维护一套坐标判定。

输入由后端采集

框架不采集原生输入。后端调用 Root 的 dispatchPointer、dispatchKeyDown/Up、dispatchCharTyped、dispatchPreedit、dispatchScrollVertical/Horizontal 和 dispatchDropFiles,不经 root.component 广播。键盘修饰键参数必填;按钮变化后的完整快照与压力由后端正规化。详见多点输入。

指针接受路径决定焦点:鼠标/PEN主键接受后取最近可聚焦祖先,TOUCH 点击确认或可聚焦控件认领后取焦点;父滚动不抢子控件焦点。

屏的终止路径是 dslScreen.close(),DSL 的 closeScreen() 走同一个入口。它先清空 stable/local 的每个条目并取消各自的作用域,再调用 dataStore.onClose();即使某个清理回调抛错,剩余清理和 onClose 仍会执行,首个异常原样抛出、后续异常作为 suppressed 附上。关闭是终态的:isClosed 在清理开始后即为真,重入关闭不会重复通知,清理或导航回调抛错也不会留下归属;终止释放完成时屏从根的归属表移除。仍打开但隐藏的屏继续归创建它的根所有,直到 root.close()。关闭后 build()/render() 失败,之后不会再创建属性。

root.close() 批量释放它仍拥有的屏时使用“只清状态、不导航”的内部关闭:不会调用任何屏的 onClose。如果屏对应的界面确实要关闭,由后端自己的界面生命周期调用 dslScreen.close();根已经关闭后再调用它不会补发导航。已经显式关闭并从归属表移除的屏不会被根再次关闭。

dataStore.pauseGame 默认为 true,是否使用由后端决定。

后端注册与入口

后端通过 DslRuntime.start 交出平台工具,之后读 dslUtils / dslMetadata:

DslRuntime.install { Metadata }
DslRuntime.start { DefaultUtils }

两个 provider 是 internal 的 var,且带 @Volatile:写方在 DslRuntime 的锁内,读方(dslUtils、dslMetadata)不取锁,没有 volatile 就没有 happens-before 边,读者可以合法地一直读到 null。这不是可选的优化,是发布语义的一部分。

读口 dslUtils 每次访问都会调一次 provider,所以 provider 必须返回稳定的单例。

加载器侧的入口发现见 入口。

线程与调度

UI 构建状态是线程受限的:DslContext 记录创建它的线程,所有上下文槽位读写都做线程校验。

由于每帧都会新建一个 DslContext,而组件对象会跨帧留存(它们持有创建时的上下文引用),实际约束是:create / build / render / 输入转发 / 关闭回调必须全部发生在同一个线程上。

调度器属于根:DslRootUtils.sessionDispatcher 是会话级的主线程调度器,供 local/stable/session 属性协程使用(clickable { launch { } } 就跑在它上面),预览会话也把建屏与截图派发到它。它必须是串行调度器:UI 构建状态是线程受限的。static 使用独立的 Dispatchers.Default,不会继承首次创建它的 Root 的调度器。

根还持有 DslRoot.sessionScope:SupervisorJob + sessionDispatcher,随 root.close() 取消。要挂并发的协程用它,这样它不会活得比它操作的树更久。

写 local / stable 只允许发生在该根的渲染线程上;从别处改,走 DslRoot.post。 那两个存储是普通映射、不是并发容器,跨线程写就是数据竞态——post 只是把块交给根线程,并不把错误的写法变安全。DslRootUtils.isOnSessionThread 回答”我是不是已经在那个线程上”,post(block) 已经在则内联执行(否则会等自己),否则投到 sessionScope;两条路径都不吞异常。跨线程投递除调度器队列外没有顺序保证,不要拿它和帧循环排顺序。post 与 sessionScope 都不是接口成员——接口只有后端必须提供的两个事实。

写一个最小后端

必须实现的成员分布大致是:渲染接口十余个(缩放、四个图元重载、原版风格的按钮/槽位/容器/提示底纹/物品/默认背景、裁剪、变换、取字体)、输入状态接口两个、元数据五个、平台工具四五个、根工具七八个、以及 Screen 工厂一个。

最低限度可以这样:

  1. 选一个渲染参数类型 RP 与 screen 类型 SC(测试后端两者都是 Unit);
  2. 实现四个图元重载;只画矩形时可以先在四边形里判断无纹理与四角同色,再补纹理和三角形;
  3. 字体需要实现行高、字形度量、字形绘制;字形需要提供字宽、粗体偏移、阴影偏移;
  4. create() 返回一个 holder,show() 里交给平台打开界面;
  5. 帧循环里按上面的三件事驱动根节点。

测试用的假后端是这方面最可靠的样本:它把各接口分别委托给独立的小实现类,create 直接构造 DslDataStore 与 DslScreen,并提供一个”跑一帧”的辅助函数(设置鼠标、设置根矩形、渲染、帧后清理)。它也展示了如何用固定的字体度量(字宽与行高)让文本布局可断言。

未使用的接口成员

“框架没有调用”与”没有消费者”是两件事,这条清单按后者才成立:

  • reloadLocalImage 不是死成员:它是公开的用户 API,docs/components/image.md 明确教用户在本地文件变化后刷新缓存。DSL 层有一个同名的、要求 DslExecuteContext 的包装,就是给用户的事件处理器用的入口;平台层的这个方法没有框架内部调用点,但框架不调用不等于没有消费者。
  • localImage / remoteImage / translate 在帧线程上调用,不允许等待 io(读文件、解码、开 socket、等待被这类工作持有的锁)。非 suspend 的函数本来就隐含这个承诺,而 window / web 两个实现都做成了同步 ImageIO.read——所以这条写进了接口注释。正确做法是先把工作丢给别的 dispatcher,这一帧返回 empty。
  • remoteImage / reloadRemoteImage 没有默认实现:没有 http 能力的后端也要给出实现——返回 empty / 空操作即可(页面照常渲染,网络图片不显示),不要抛。加一个默认实现会让”所有后端都必须有 http”或”所有后端都可以不管网络图片”这两种隐含契约二选一,所以交给实现方决定。
  • start 之前框架用 UnpublishedUtils 回答:translate 返回 null(调用方回退到 key)、isInWorld 为 false、图片一律 empty、两个 reload 都是空操作、quit 直接退出进程。全部良性,没有任何会抛异常的成员;调度器不在这里——它属于根(DslRootUtils.sessionDispatcher),所以入口的 initialize() 可以安全地翻译文本、读元数据。
  • 图片缓存淘汰是可选项:后端可以永不淘汰。若要做,一种可行做法是——命中即刷新 lastUsed、每帧 sweep、按墙钟 TTL 淘汰、淘汰时释放纹理(mc 的 TextureManager.release),否则 reloadLocalImage 会不断留下 minecraft:dynamic/dslimageid_N 这类永不释放的纹理。这是建议,不是接口约束。
  • isInWorld 确无消费者:跨四个仓库的 src 都没有调用点,也没有任何文档使用它。而且它与下面的约定重复——”是否就绪”是平台知识、由后端在自己的每帧入口把关,框架再暴露一个世界判定没有额外信息。
  • openUri 确无消费者:同样跨四仓零调用,文档里也没有会出现链接的组件。要用它,得先有一个真的会打开链接的组件。

后两条是删除候选,前两条应当留下。改动接口前请以这份清单为准,不要按”框架没调”一刀切。


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