C++ 集成¶
这一章面向在 LeviLamina 客户端模组里接入 Silica 的开发者。假设你已经能让模组加载 .dll,并且能在游戏 UI 渲染阶段拿到 MinecraftUIRenderContext。
分工先明确:
| 部分 | 职责 |
|---|---|
| 你的模组 | 生命周期、渲染/输入事件、数据来源、业务处理器 |
| Silica | 解析 .sil、构建控件树、布局、绘制、输入路由、绑定与动画 |
Silica 不接管屏幕栈,也不注册自己的窗口。它只把一棵控件树画进你提供的渲染上下文里。
一、接入构建¶
Silica 以静态库 Silica.lib 的形式提供,头文件在仓库的 include/ 目录。
<你的模组>/
├── src/
├── ui/ # .sil 文档
├── build.bat
└── ...
构建要求:
| 项 | 值 |
|---|---|
| 编译器 | clang-cl(MSVC ABI) |
| C++ 标准 | C++20 |
| 运行库 | /MD |
| 链接 | Silica.lib + LeviLamina.lib |
编译和链接参数参考:
-I<Silica>/include
clang-cl ... /LD /MD /std:c++20 /I<Silica>/include ...
/link <Silica>/dist/Silica.lib LeviLamina.lib ...
Silica.lib 里包含 Bedrock 渲染与符号解析调用;它和你的模组必须使用同一套 LeviLamina SDK 头文件与 ABI。
二、初始化¶
在模组加载阶段完成三件事:设置日志出口、设置文档根目录、编译文档。
#include "silica/Silica.h"
silica::Silica::SetLogSink([](std::string_view line) {
myModLog("%.*s", static_cast<int>(line.size()), line.data());
});
silica::Silica::SetRootPath(modDirectory); // 相对路径都从这里开始
silica::WidgetPtr root = silica::Silica::CompileFile(
"ui/main.sil",
R"(
Panel {
width: 200; height: 80;
background: #2C2F33;
radius: 6;
Label { text: "UI 编译失败,请查看日志"; width: 200; height: 20; }
}
)"
);
CompileFile(filepath, fallbackSource) 的行为:
- 读取并编译文件;失败时改用
fallbackSource再编译一次。 - 两次尝试的诊断都写入日志出口。
- 返回值总是一棵可用的树(除非回退源码也编译失败)。
- 记录在这次调用下,
ReloadUI才能找到对应条目。
先设置日志出口
SetLogSink 应在任何编译之前调用,否则诊断只会写到 stderr 和调试输出,模组日志里看不到。
资源预导入¶
带图片的文档需要在客户端资源包栈建立前把图片导入:
#include "silica/ImagePack.h"
if (root) silica::imagepack::Warmup(root);
模组加载阶段是合适的时机。渲染时也会惰性解析,但没有预导入时首帧可能先显示占位框。
三、编译与诊断¶
需要逐条检查诊断时,使用 UICompiler:
#include "silica/UICompiler.h"
silica::SilCompileResult result = silica::UICompiler::CompileDetailed(source, "ui/main.sil");
for (auto const& d : result.diagnostics) {
log("%s", silica::FormatDiagnostic(d, result.origin).c_str());
}
if (!result.ok()) {
// result.ok() 要求有根节点且没有 Error
}
| 字段 | 说明 |
|---|---|
root |
构建出的控件树;出现阻止构建的错误时为空 |
diagnostics |
错误与警告 |
origin |
诊断里显示的文件名 |
ok() |
有根节点且无 Error |
Report() |
每条诊断一行,已格式化 |
设计原则:未知属性、未知样式、缺少参数等产生警告,尽量保留可用的控件树;语法错误、循环继承、递归组件等产生错误。
四、数据与绑定¶
DataStore 是全局响应式状态:
#include "silica/DataStore.h"
#include "silica/Variant.h"
silica::DataStore::Set("playerCount", silica::Variant{42});
auto count = silica::DataStore::Get("playerCount"); // Variant
bool has = silica::DataStore::Has("playerCount");
Set只有在值真正变化(深比较)时才通知观察者。- 通知是同步的,发生在写入线程上;处理器里可以再次读写
DataStore。 - 控件以弱引用订阅,控件树析构后订阅自动失效。
数组与对象¶
Variant 支持 Null / Bool / Number / String / Array / Object:
using silica::Variant;
VariantArray rows;
for (auto const& entry : entries) {
rows.push_back(Variant::Object({
{"name", Variant{entry.name}},
{"count", Variant{entry.count}},
}));
}
silica::DataStore::Set("rows", Variant::Array(std::move(rows)));
容器是不可变的
Variant 的数组和对象没有修改接口。改一个元素时,请构造新的数组/对象再 Set。只有整体替换才会触发 ForEach 重建和绑定刷新。
五、事件处理器¶
.sil 里写处理器名,C++ 里按名字注册:
#include "silica/Handlers.h"
silica::SilicaHandlers::Register("save", [] {
// Button { onClick: "save"; }
});
silica::SilicaHandlers::Register("set_volume", [](std::string_view value) {
// Slider { onChange: "set_volume"; }
double v = std::stod(std::string(value));
});
| 重载 | 适用 | 收到的值 |
|---|---|---|
ActionHandler |
onClick |
无 |
ValueHandler |
onChange/onSubmit |
"true"/"false"、数字文本、输入文本或选中索引 |
Invoke(name)会回退到值处理器并传空串。Unregister(name)、Has(name)、Clear()用于生命周期管理。.sil里写了事件脚本时,脚本优先执行,命名处理器不会被调用。
六、挂载到一帧¶
每帧顺序固定:推进时间 → 布局 → 指针 → 渲染 → 刷新绘制。
MinecraftUIRenderContext& context = /* 你的渲染回调 */;
silica::WidgetPtr const& root = /* 已编译的树 */;
static double last = -1.0;
double const now = frameSeconds();
float const dt = last < 0.0 ? 0.f : static_cast<float>(std::min(now - last, 0.1));
last = now;
silica::TickTree(*root, dt); // 绑定、动态规则、过渡、关键帧
root->Update(); // 自动尺寸与布局
// 指针按下/抬起边沿先回放,再处理悬停位置
silica::PointerState down;
down.x = px; down.y = py; down.down = true; down.pressed = true;
pointerRouter.Update(root, down);
silica::PointerState up;
up.x = px; up.y = py; up.released = true;
pointerRouter.Update(root, up);
silica::PointerState hover;
hover.x = px; hover.y = py;
pointerRouter.Update(root, hover);
root->Render(context);
silica::FlushDraws(context); // 帧末提交所有延迟绘制
TickTree 会遍历整棵树(包括 ScrollView 的内部内容)。帧间隔内部限制在 0.25 秒以内,卡顿后不会跳变。
坐标必须是 GUI 单位
PointerState、控件几何和 MinecraftUIRenderContext 都使用 GUI 单位。Windows 像素坐标需要乘以 1 / GuiScale。混淆单位会导致命中偏移和图片错位。
输入路由¶
| 对象 | 用途 |
|---|---|
PointerRouter::Update(root, state) |
悬停、按下、抬起、拖动捕获 |
PointerRouter::Wheel(root, state, delta) |
每格滚轮;滚轮事件需要单独调用 |
PointerRouter::Hovered() / Captured() |
当前悬停/捕获控件 |
FocusManager::Get().Current() |
当前键盘焦点 |
FocusRing |
收集可聚焦控件,Tab/方向键切换,激活 |
键盘处理建议:
if (auto* focused = silica::FocusManager::Get().Current()) {
if (focused->OnKeyDown(keyCode)) return;
}
控件消费掉的按键不要继续传给宿主快捷键,否则输入框里的空格会变成开关界面之类的行为。
Esc 建议同时做两件事:清空焦点(FocusManager::Get().Clear())和关闭你的覆盖层。
七、查找与操作控件¶
#include "silica/Tree.h"
if (auto node = silica::FindByName(root, "volume_slider")) {
if (auto slider = std::dynamic_pointer_cast<silica::SilicaSlider>(node)) {
slider->SetValue(0.6f);
}
}
FindByName深度优先,匹配.sil里的name:。HitTest(root, x, y)返回该点最深的可见控件。- 也可以通过
DataStore驱动 UI,通常比直接改控件属性更稳。
八、重载文档¶
silica::WidgetPtr fresh = silica::Silica::ReloadUI("ui/main.sil");
if (fresh) {
root = fresh;
silica::imagepack::Warmup(root);
focus.Clear();
focusRing.Collect(root);
}
- 重载失败时保留旧树,并记录失败诊断。
- 新树的控件是全新对象,旧的焦点、拖动捕获和外部指针都应重置。
- 重新执行
Warmup,让新引用的图片进入资源包。
九、自定义控件¶
控件通过 WidgetFactory 按类型名创建,可以在编译文档之前注册:
#include "silica/WidgetFactory.h"
class HealthBar : public silica::SilicaWidget {
public:
void Render(MinecraftUIRenderContext& context) override {
silica::FillRect(context, x, y, width, height, silica::Color{.2f, .2f, .2f, 1.f});
silica::FillRect(context, x, y, width * fraction, height, silica::Color{.8f, .2f, .2f, 1.f});
}
bool ApplyProperty(std::string_view key, std::string_view value) override {
if (key == "fraction") {
// 解析数字……
return true;
}
return silica::SilicaWidget::ApplyProperty(key, value);
}
float fraction = 1.f;
};
silica::WidgetFactory::Register("HealthBar", [] {
return std::make_shared<HealthBar>();
});
注意:
- 返回
false的ApplyProperty会产生unknown property警告。 - 继承
SilicaContainer才能容纳任意子控件;继承SilicaWidget/SilicaPanel时AddChild只接受Part。 - 绘制时使用
PaintAlpha()作为透明度,让opacity、禁用变暗和关键帧透明度自动生效。 - 自定义控件需要自己调用
PaintParts才能显示Part(容器和内置控件已处理)。
十、线程与所有权¶
| 规则 | 说明 |
|---|---|
| 控件树只在渲染线程访问 | 不要在后台线程调用 Update/Render/控件 setter |
DataStore 通知同步发生 |
写入线程会立即回调观察者;跨线程写数据请先切回主线程 |
根用 WidgetPtr 持有 |
控件之间父子是 shared_ptr 子 + 裸指针父,不要形成环 |
| 订阅是弱引用 | 不需要手动退订,但控件树必须存活 |
| 处理器注册是进程级 | 卸载模组时 Clear() 或逐个 Unregister |
常见问题¶
| 现象 | 原因 | 处理 |
|---|---|---|
| 点击位置偏移 | 像素坐标未除以 GuiScale | 统一换算成 GUI 单位 |
| 输入框收不到字符 | 按键未先交给 FocusManager::Current() |
先调用焦点的 OnKeyDown |
| 数据更新 UI 不刷新 | 绑定的不是同一根键,或写入了相等值 | 检查键名;容器要整体替换 |
| 图片首帧是占位框 | 资源包尚未就绪 | 在加载阶段 Warmup,渲染时会自动重试 |
| 重载后点击错乱 | 旧焦点/捕获仍指向已销毁控件 | 重载后 Reset()/Clear() 并重新收集焦点 |
| 自定义控件没有背景 | 没有调用 PaintSelf |
在 Render 里先调用 PaintSelf |