Skip to Content
Guide设计原则

设计原则

DearOreUI 的核心设计是 9 条原则。它们决定了你写 Mod 时拿到的是什么样的 API：简单、安全、可预测。读完这页，你会明白为什么 API 长这样。

1. 声明式优先：说”要什么”，不说”怎么做”

你描述”我想要一个居中的提示框”，注入、渲染、生命周期都由 DearOreUI 接管。

// ✅ 声明式：描述"要什么"
UiManifest ui;
ui.kind       = UiKind::Overlay;
ui.anchor     = UiAnchor::Center;
ui.pageScopes = {PageScope::Any};
 
oreui->registerOverlay(modId, ui, "<div>Hello, DearOreUI!</div>");

命令式要自己拿到 view、自己执行脚本，还要懂引擎内部，容易崩：

// ❌ 命令式：自己动手"怎么做"
auto* view = captureView();
view->ExecuteScript("document.createElement('div')...");

2. 零侵入：你的 Mod 不会弄坏游戏

DearOreUI 不修改游戏安装目录、不替换原版资源、不改原版页面。Mod 失败时，游戏保持原样。

特性说明
不修改游戏文件注入在运行时内存里完成，磁盘上的原版文件原封不动
失败自动回退页面加载失败零副作用，游戏照常运行
失败隔离一个 Mod 失败不影响其他 Mod；一个页面失败不影响其他页面

最坏情况是你的 UI 没显示，游戏不会崩。在正式环境试错是安全的。

3. 难度递进：从简单开始，按需升级

普通 Mod 只需要声明式注册；需要页面生命周期、游戏能力或原版代码变换时才往上层走：

L0 查询运行时        —— 只读，零副作用（isReady / capabilities）
L1 注册资源与 UI     —— 声明式，普通 Mod 停在这里
L3 挂载 UI           —— Overlay / Panel / Button / Page
L6 高级兼容          —— vtable 指纹、多版本 ABI 适配

没必要一上来理解整个架构。先停在 L1，需要时再学下一层。

4. 语义化变体：说”主操作”，不说”蓝色按钮”

变体用语义命名（primary / secondary / neutral / destructive），不用视觉描述（solid / flat / bordered）。代码表达意图，换主题时不用跟着改代码。

// ✅ 语义化：表达意图
button.variant = "primary";      // 主操作，推进流程
button.variant = "secondary";    // 次要操作
button.variant = "destructive";  // 危险操作（删除等）
变体用途建议
primary主操作，推进流程每个上下文 1 个
secondary次要操作可多个
neutral中性操作默认
destructive危险操作（删除、清空）按需

换主题时变体含义不变，UI 自动跟随，代码不用动。

5. 规则统一：所有组件同一套规格

组件共享同一个 ComponentSpec：同样的字段、状态、渲染链路。学会一个，就会全部。

// 所有组件共用一套字段
ComponentSpec spec;
spec.kind     = ComponentKind::Button;  // 或 Panel / Text / Card / Input ...
spec.label    = "OK";
spec.variant  = "primary";
spec.disabled = false;
spec.state    = "default";              // default / hovered / focused / pressed / disabled

不用为每个组件重学一套 API；组件之间可以自由嵌套。

6. 可诊断：出问题不用猜

注册、注入、失败事件都会写进诊断文件，带时间戳、严重级别、所属 Mod 和错误码。排查先看诊断。

{"id":"...","timestamp":"...","severity":"error","category":"mount",
 "modId":"my-first-ui","pageId":"/play/all","errorCode":"CONFLICT", ...}

7. 冲突显式：不静默覆盖

多个 Mod 改同一页面时，冲突显式报错，而不是静默覆盖。每个注册返回 Result，错误可以处理。

auto result = oreui->registerOverlay(modId, ui, html);
if (result.isErr()) {
    // 冲突、校验失败、无效参数——都有明确的错误码
    log(result.error());
}

多 Mod 协作时冲突当场暴露，不会等上线后才发现 UI 被顶掉了。

8. 原版风格：观感与原版一致

组件直接复用原版主题变量和纹理，你的 UI 和原版界面看起来一样，而不是”像网页”。

// 按钮直接用原版 pressable 纹理，而非近似 CSS
button.variant = "primary";
// → border-image: url(/hbui/assets/...) 9-slice 渲染

组件库内置，开箱即用，不需要自己”模仿”原版。

9. AI 友好：能力矩阵机器可读

运行时公开能力矩阵，AI 可以查询”运行时支持什么”，只生成可用的代码：

capabilities: {
  "ui.mount":        "supported",
  "host.call":       "experimental",
  "transform.bundle":"unsupported"
}

文档示例与源码契约逐一对应，AI 生成的代码不会用到运行时没有的 API。

下一步

安装与构建在你的模组中使用