RFC5:新 UI 自定义技术方案

Mahiru
2026-11-15

正如在 RFC4 提到的,我们将采用更加灵活的新 UI 自定义方案。对于这样的方案,需要对 WebGAL 的整个 UI 架构彻底地革新。接下来介绍新 UI 自定义的技术方案。

独立界面化 UI

在先前的版本中,UI 和许多引擎的交互逻辑是耦合的,一些逻辑直接写在 UI 界面中,这对于后续的自定义乃至动态导入界面,都造成了很大的障碍。新的独立界面化 UI 将只处理 UI 展示,并全面采用 CSS in JS 方案以更加灵活地控制样式。所有的数据和回调,都通过参数的方式传入,这样用于展示的 UI 就和逻辑无关。

存档、读档、设置、流程图将各自拆成独立的顶层界面槽位,连同用于切换不同界面的 MenuPanel,以及标题、文本框、分支选择、鉴赏、历史记录、底部快捷栏、全局弹窗一起交由 template.json 分别指定(需在文档中提示用户,编写存读档、设置、流程图界面时预留好底部的 padding 给 MenuPanel 浮层使用)。存读档也不再写死每页 10 个档位、共 20 页,内核原本就只按序号存取,具体显示多少档位由界面通过传入的函数向宿主调用即可;至于目前使用 ReactDOM.render 挂载的部分,暂维持现状不作迁移。此外,文字描边也将启用 paint-order: stroke fill,不再像以前那样拆成多层重叠节点。

除了用于“兜底”的默认 UI 外,新的版本将支持通过原生 import() 动态加载 JS 的方式,来加载自定义界面,然后将默认 UI 取而代之。新的模板结构改为一个顶层界面(Screen)一个目录,同一界面对应的不同预制界面或自定义界面各自存放在独立的子目录中,把作为出厂基准的 .js、用于动态细调的 .scss 以及该界面专用的贴图和图标都放进去。自定义界面分发给其他用户时直接将该子目录打成压缩包即可,切换不同界面也不存在覆盖和丢弃原有样式的问题。至于引擎使用哪个界面,交给 template.json 来指定。

为了保证动态加载 JS 的兼容性,引擎将和编辑器一样升级使用 React 18(不再往更高版本升)。引擎会在全局注入 SDK(提供宿主一致的 React、@emotion/css、资源路径解析以及台词富文本和注音渲染能力),自定义界面对 React 等依赖做 External 外部化。配套的 npm 脚手架会附带类型描述,并锁定 React 版本与引擎一致,导出脚本如果检查到用户擅自修改了 React 版本号则直接停止导出。同时,每个顶层界面外层包裹 ErrorBoundary 以便出错时回退到默认 UI,桌面端环境下也会注意限制宿主接口权限。

模板与调试

由于自定义界面功能提供了更大的灵活度,现在在 Terre 项目内通过配置表写死的部件类将难以支撑这样的需求。更何况对于存读档、设置等界面,我们提供的多种预制界面,在布局方面都可能有很大变化,更不是原先的写死的类列表可以支撑的。

新的用于模板编辑器进一步细化编辑的部件类表,直接复用并扩展现有的编辑器预览协议(@webgal/editor-preview-protocol),由自定义界面(或预制界面)提供,并发送给 WebGAL Terre。当用户开始对某个界面进行更加细节的,基于模板系统的调整时,就采用该界面提供的可自定义部件。

调试时,布局统一使用基于 2560 × 1440 逻辑画布的 px 单位(禁用 vw / vh),由引擎上报部件包围盒,拖拽编辑框留在 Terre 外层复用 react-moveable 绘制。拖拽过程中走 preview 阶段直接更新引擎内存样式,松手 commit 时再写入 .scss 文件,保证拖拽流畅;同时通过协议支持部件状态锁定(默认 / 悬停 / 按下 / 禁用)与存读档、鉴赏、历史记录等界面的预览假数据注入。

布局编辑与样式编辑

正如 RFC4 中所述,每一个界面(比如存读档界面)拥有一个 UI 描述文件,包含多个部件的描述。对于任何部件,描述都分为两部分:布局和样式。

这里我们让每个独立界面的 .js 自带完整的默认样式表和部件描述,作为出厂基准向引擎提供,并通过调试协议发送到编辑器;同目录下的 .scss 则用于动态细调,编辑器在完整默认样式副本上做字段级增改。

界面调整

界面方面,我们需要大幅调整 UI 编辑界面。左侧基本不变,仍然是模板配置相关、界面与部件选择器和资源管理器。选择器顶层显示“独立 UI 界面”(类似于“标题”),展开处列出该界面下的各个部件,并与预览画布中的点击选中联动。同时也需要添加“更换界面”的按钮,以在我们提供的预制界面和用户导入的自定义界面间切换。自定义界面需要被导入到当前模板对应界面的目录下,才能在这里被选择。

相比于原先放在下面的实际编辑区,新的编辑区被放在右侧,以实现两段式结构。当某个部件被选择后,右边分别展示:

  1. 上栏:布局编辑器,用于编辑部件的相对位置、宽高、内外边距等,与左边的预览中可以拖拽的部件联动,设定后会更新多个 CSS 字段。
  2. 下栏,Tab 简易模式(在下栏通过 Tab 切换,顶部带状态锁定切换):我们精心设计好的,由多个 CSS 字段联动的简易字段,设定后会更新多个 CSS 字段。
  3. 下栏,Tab 完全 CSS 定义(在下栏通过 Tab 切换):分为图形编辑器和代码编辑器,逻辑基本上完全继承于当前的下方编辑区的实现,是最原始的编辑方式,可收起不用。

对于简易模式,不设单独字段,全部使用类似于 Terre 脚本图形编辑器中的解析-组装模式。比如,对于字体颜色,如果要设置渐变色这样的复杂样式,需要先将字体颜色设为透明,然后设置 background-clip,然后设置 background。那么解析的过程中,就会通过多个字段的组合,解析并分析出对应简易模式中的“渐变色字体”,并直接合并为一项编辑字段也就是字体颜色。而对合并字段的编辑,则是在编辑后,直接写入相关字段。在 RFC4 中,已经有相关讲解。解析与写入将改用轻量 CSS AST(如 css-tree 或 stylis)代替原先按行切分字符串的方式,以支持多行属性与伪类嵌套,并处理好简写属性冲突。

由于左侧顶层界面展开处已经可以选择当前编辑的部件(对应到旧方案的一个“类”),右侧的布局编辑器、简易模式和完全 CSS 定义中的“图形编辑器”都直接作用于当前选中的部件;进入代码编辑器时,则直接编辑当前界面子目录下的 .scss 文件。

只支持样式编辑的部件,预制界面

如果是存读档、设置、鉴赏界面中的列表项部件,涉及列表渲染等,如 RFC4 所述,不能支持所有布局的编辑。因此,在自定义界面(和我们的预制界面)通过预览协议通知编辑器时,也允许告知“某个部件”是否支持布局编辑,如果不支持,可以直接隐藏布局编辑器中的一些字段(width, height, position, left, top 等涉及定位、尺寸的),甚至完全禁用布局编辑区,只支持编辑样式。

由于即将开放基于 .js 的动态界面导入,后续也会提供 npm 脚手架,因此用户使用 AI 工具自定义界面应不难。这里只需要给用户提供一些直观的细调方式即可。我认为这是合理的,与其费劲研究一套布局描述 DSL,像 renpy 一样死磕,不如利用 AI 四两拨千斤。

兼容性

全局的 userStyleSheet.css 仍然作为历史保留,只是保留加载进去的功能,怎么用由用户自行决定。

存量模板继续走默认机制:如果 template 里面没有任何自定义界面,也没有在 template.json 中启用新模板,就还是使用保留的默认界面,样式类也保持一致,旧模板可以正常工作;一旦启用了新界面机制,就不再要求兼容旧类名。

applyStyle 指令仅作为旧的模板行为保留。只要启用了新模板,该指令全局静默失效,对实际游玩的玩家透明;在控制台会打印一条 warning,并在连接编辑器时通过调试协议通知编辑器告知该指令在新版本已不生效。