项目总览¶
本章从整体上说明 Silica 由哪些部分组成、一份 .sil 文档如何变成屏幕上的控件,以及文档中反复出现的关键术语。
它解决什么问题¶
在基岩版客户端模组里手写界面,通常意味着直接调用游戏的 UI 渲染接口:自己计算每个按钮的坐标、自己处理悬停与点击、自己维护“数据变了要重画哪一块”。界面越复杂,C++ 代码越难读,改一个间距都要重新编译。
Silica 把这件事拆成两层:
| 层 | 负责 | 典型修改者 |
|---|---|---|
界面描述(.sil) |
结构、布局、文字、颜色、绑定、交互逻辑 | 界面作者 |
| 集成逻辑(C++) | 加载文档、提供数据、注册回调、接入渲染与输入 | 模组开发者 |
.sil 描述“界面长什么样、数据变化时哪里跟着变”;C++ 负责“界面在什么时候出现、数据从哪里来、游戏事件如何送进来”。两者通过数据键和回调名称解耦:界面里写 text: @player_name 与 onClick: "open_settings",C++ 只负责写入 player_name、注册名为 open_settings 的函数。
分层架构¶
ui/main.sil
│ 语法解析
▼
文档模型:节点、Var、Style、Component、@keyframes
│ 样式展开、$变量替换、组件实例化、绑定/脚本解析
▼
控件树:SilicaWidget(Container / Label / Button / ...)
│ 宿主每帧驱动
▼
Tick(动画) → Update(布局) → 输入路由 → Render → FlushDraws
│
▼
MinecraftUIRenderContext(游戏的 UI 绘制接口)
各层的职责:
- 文档模型:保留每个节点的类型、参数、属性文本、子节点与源码位置。属性值在这一层仍是文本,只有具体控件知道
font-size或layout的含义。 - 编译:把
Style与class展开成属性,替换$变量,实例化Component,把@key值登记为绑定、把{{ ... }}登记为模板、把{ ... }登记为事件脚本。未知属性记为警告,未知控件记为错误,整份文档不会因一个拼写错误而崩溃。 - 控件树:每个控件持有自己的几何、样式、绑定与脚本。布局由容器计算;控件本身只负责绘制自己并响应输入。
- 宿主:Silica 不主动挂钩游戏。模组在合适的渲染事件里调用
TickTree、Update、PointerRouter、Render与FlushDraws,并把键鼠事件换算成 GUI 坐标后送入路由器。
Silica 不接管游戏界面
Silica 绘制到模组提供的渲染上下文里。它不替换 OreUI / JSON-UI,也不修改游戏自带的界面文件。示例模组 SilicaTest 会临时压入一个空的原生界面来获得光标与焦点,这只是宿主的一种接入方式,不是框架的硬性要求。
一次加载发生了什么¶
以 Silica::CompileFile(path, fallback) 为例:
- 解析:读取文件,生成节点树与文档级定义(
Var、Style、Component、@keyframes)。语法错误带行号、列号进入诊断列表。 - 展开:对每个节点应用
class/style指定的样式链(基样式在前、派生样式在后、内联属性最后覆盖),再把$变量替换成文本。 - 构建:按节点类型创建控件;设置属性;登记绑定、模板与脚本;递归构建子节点。
ForEach记录模板,稍后按数组元素重建;Component用实参建立子作用域后构建函数体。 - 打包图片:
imagepack::Warmup(root)扫描树中的file:图片与Part贴图,把它们复制到模组目录下的resource_packs/silica_images,让游戏在构建资源包栈时就能看到。 - 挂载:宿主保存根控件,设置位置与尺寸,调用一次
Update()完成首帧布局。
Silica::CompileFile 会把编译结果记录在内部注册表中,因此之后可以对同一路径调用 Silica::ReloadUI(path):
- 文件重新编译成功:替换为新树。
- 文件读取或编译失败:记录诊断,保留上一棵树,界面不会消失。
如果直接使用 UICompiler::CompileFile(path, fallback),主文档失败时会编译内嵌的 fallback 文档,保证模组至少有一个可用界面。
每帧需要做什么¶
宿主每帧的顺序通常如下(SilicaTest 即按此顺序):
| 步骤 | 调用 | 作用 |
|---|---|---|
| 1 | TickTree(root, deltaTime) |
推进关键帧、过渡、条件值重算 |
| 2 | root->Update() |
重新布局,写入子控件的绝对坐标 |
| 3 | PointerRouter::Update / Wheel |
悬停、按下、释放、滚轮与拖拽 |
| 4 | root->Render(context) |
依次绘制背景、边框、文字、子控件、装饰层 |
| 5 | FlushDraws(context) |
提交本帧累计的填充与文字批次 |
键盘输入交给当前焦点控件:FocusManager::Get().Current(),再调用它的 OnKeyDown(key)。焦点环 FocusRing 负责 Tab/方向键顺序与回车激活,是否使用由宿主决定。
先 Tick 再布局
关键帧的缩放是纯渲染变换,但过渡与条件值会改变颜色、透明度等属性。先 Tick 再 Update,可以保证同一帧内布局看到的是最新状态。
核心概念¶
| 概念 | 说明 | 详见 |
|---|---|---|
| 界面文档 | 一个 .sil 文件;顶层可含定义,之后是一个或多个界面节点 |
基础语法 |
| 节点 / 控件 | Button { ... } 这样的一层界面;节点类型对应一个控件实现 |
控件参考 |
| 属性 | 键: 值;,例如 width: 120;、background: #202428; |
基础语法 |
Var |
文档内的编译期常量,用 $name 引用 |
样式 |
Style |
可复用的属性集合,可 extends,用 class: / style: 套用 |
样式 |
Component |
带参数的可复用子树,Slot 接收调用方子节点 |
组件 |
| 绑定 | 以 @ 开头的值,读取 DataStore 或控件状态,数据变化时自动重算 |
响应式绑定 |
| 模板 | 字面文本中的 {{ expression }},用于拼接 |
响应式绑定 |
| 事件脚本 | { ... } 形式的交互逻辑,可赋值、做加减、写 if/else |
事件脚本 |
| 数据键 | DataStore 中的名字,如 health、settings.theme 的根 settings |
C++ 集成 |
| 回调名称 | .sil 里写的字符串,由 C++ 用同名函数实现 |
C++ 集成 |
ForEach |
按数组生成行,数组替换时整段重建 | 列表 |
Part |
附着在任意控件上的装饰层,可按状态显示 | 控件参考 |
| 关键帧 / 过渡 | @keyframes 与 transition,用于动画 |
动画与过渡 |
数据如何流动¶
C++ DataStore::Set("health", 80)
│
├─ 读取 health 的绑定立即重新求值(同步,写入线程上)
│ text: @health → Label.text = "80"
│ color: @health > 50 ? … → 重新应用颜色
│
└─ 下一帧 Render 绘制出新状态
.sil 脚本:@health += 10
│
└─ 同样经过 DataStore,触发上面的通知链
表达式解析名字时按以下顺序查找:
- 事件载荷
event.*(仅在事件脚本执行期间存在,优先级最高)。 - 局部作用域:
ForEach注入的item/index,Component注入的参数名。 DataStore:全局数据键。- 控件状态:
hovered、pressed、focused、disabled,以及具体控件的状态(checked、expanded、editing等)。
同名的数据键会遮住同名的控件状态,因此数据键命名时最好避开 checked、visible 这类状态名。
有意不做的部分¶
- 不支持 HTML、CSS、JavaScript,也不解析网页。
- 不绘制 3D 内容,只画二维控件。
- 不提供可视化编辑器;
.sil是纯文本。 - 不自动接管游戏的菜单、输入法或光标;这些由宿主模组决定。
- 不公开解析器与编译器的内部数据结构;文档只描述对外可见的语法与接口。