跳到正文
返回搜尋

DearOreUI

作者 copper-lamp

Powerful client-side front-end, based on oreUI, providing powerful front-end capabilities for your mods

  • 94 次下載
  • 16 個星標
  • 更新於
client · 0.1.2

README0.1.2

DearOreUI

在运行时扩展 Minecraft Bedrock 的 OreUI。

面向 LeviLamina 客户端的原生模组,用于读取、变换和注入 OreUI 资源。

发行版本 · 更新日志 · 项目文档 · 参与贡献 · English

DearOreUI 构建状态 DearOreUI 最新发行版本 CC0-1.0 许可证 DearOreUI 未关闭 Issue 加入QQ群

Note

DearOreUI 已经走过了纯脚手架阶段。下面描述的 Hook、资源快照、多 Mod 注册表、变换、注入、Host/Facet 桥、UI 挂载和 API 门面都已实现,显示链路也在真实客户端、OreUI 技术栈页面上验证过

项目概览

DearOreUI 是面向 LeviLamina 26.10.x 的 Windows x64 客户端原生模组。它在 Minecraft 客户端运行期间读取原版 OreUI 资源,合并多个 Mod 声明的变更,并把校验后的结果注入当前 OreUI 页面。这让你可以专注地编写你的界面,无需操心与其它模组的ui兼容性 DearOreUI 不是独立 UI 替代品,也不会向其他 Mod 直接暴露页面指针、编译后 Bundle 内部变量或任意本地文件访问。

已实现的能力

  • 运行时 Hook。 模组挂钩了 TechStack 选择、SceneProvider 场景创建、Router 导航、OreUI::View::initialize、OnReadyForBindings、triggerEvent 和 ClientInstance::update。
  • 真实显示链路。 捕获 cohtml::View 后,脚本以 OnReadyForBindings 为门控,通过 CoherentHostBridge::sendScript 执行;DOM Overlay 用 CSSOM 构建,不用 innerHTML。这条链路已在世界列表页(/play/all)真实验证过。
  • 资源快照。 FileSystemSourceReader 读取原版 gui/dist/hbui 资源;ResourceUri 和 ResourceIndex 负责路径与访问管理。
  • 多 Mod 注册表。 Mod 注册资源、脚本、样式、UI 和变更;统一注册表做依赖排序、冲突检测,并为每个页面生成一份变更计划。
  • 声明式 UI。 registerMod / registerOverlay 进入 UiPlanner、MountManager 和 UiStateMachine。52 个组件的 showcase 已在真实客户端完整显示。
  • Host 桥。 HostDispatcher 和 HostMethodRegistry 把 JS 请求路由到原生方法并做权限校验。JS→C++ 走游戏原生 Facet 协议:DearOreUI.call → facet:request → OreUIFacetBridge → HostDispatcher → bus.push。
  • 公共 API。 IDearOreUIApi 合并了 Runtime、Resource、Mod、Host、UI、Page、Event、Transform、Diagnostic、Frame、RuntimeReport 等门面。外部 Mod 通过纯 C ABI 桥(DearOreUI_QueryApi)获取实例。
  • JS 命名空间。 页面内注入 window.__DearOreUI__(协议信息、bus、ipc)和 window.DearOreUI(call、report),以及基础的 oreui.* 命名空间。
  • 诊断。 JSONL 事件流、各阶段遥测、注入报告和崩溃探针,全程不修改游戏安装目录。

开发状态

能力状态
LeviLamina 模组生命周期已实现
Windows x64 客户端构建可用(xmake + Clang-CL)
OreUI / Coherent 运行时 Hook已实现,客户端验证通过
原版 OreUI 资源快照已实现
多 Mod 资源注册表已实现
依赖排序与冲突检测已实现
资源与代码变换内部已实现(ChangePlanner)
UI 挂载与页面生命周期已实现,客户端验证通过
C++ 与 JavaScript Host API基础 API 已实现,JS 侧已注入
崩溃隔离实验已实现

尚未覆盖:

能力状态
JsonUI 页面(主菜单、世界内界面)不支持
同一 View 内多次 JS→C++ 调用仅支持一次有效派发
公开事件 / 页面订阅门面未形成
诊断查询门面未形成
版本化变换作为公共 API未开放

渐进式 API 模型

L0  运行时查询
    ↓
L1  资源、脚本和样式注册
    ↓
L2  页面生命周期与 PageContext
    ↓
L3  UI 挂载和页面扩展
    ↓
L4  经过权限校验的 Host API
    ↓
L5  版本化代码和资源变换
    ↓
L6  Facet Provider 与高级兼容适配

大多数 Mod 应停留在 L1。更高层能力需要理解页面生命周期、宿主能力、兼容条件或原版 Bundle 结构,因此采用显式选择。

多 Mod 协作

Mod 不直接修改同一份中间字符串,也不写入游戏安装目录。每个 Mod 向 DearOreUI 注册声明,DearOreUI 以原始资源快照为输入,为当前页面生成统一变更计划。

Mod A 注册
Mod B 注册
Mod C 注册
    ↓
统一注册表
    ↓
页面、版本和能力筛选
    ↓
依赖排序
    ↓
冲突检测
    ↓
资源和代码变换
    ↓
完整性校验
    ↓
一次性提交注入

默认规则:

  • 资源路径按 Mod 命名空间隔离。
  • 相同注册内容按幂等处理。
  • 同一资源的不同内容产生冲突。
  • 资源替换必须声明原始指纹。
  • 同一原始代码区域的多个替换默认冲突。
  • 单个 Mod 失败不会影响无关变更。
  • 不支持版本保留原始页面。
  • 所有冲突、跳过、失败和回退都生成报告。

兼容性

当前目标是 Windows x64 的 LeviLamina 客户端原生模组:

组件目标
Minecraft BedrockWindows x64 客户端
LeviLamina26.10.x
原生入口DearOreUI.dll
C++ 标准C++20
工具链Clang-CL
构建系统xmake
模组版本0.1.0

OreUI Bundle 的兼容性不能只依据 Minecraft 版本判断,还取决于检测到的 OreUI 资源、Coherent 宿主、页面类型、资源指纹和可用能力。

已验证的边界(来自阶段 7.1 和阶段 8-A 的客户端记录):

  • 显示链路在 OreUI 技术栈页面上可用,当前验证目标是世界列表页。
  • 真实客户端上记录到一次完整的 JS→C++ roundtrip。
  • JsonUI 页面(主菜单、世界内界面)走的是另一套技术栈,不在本管线内。
  • 其他 Minecraft / LeviLamina 版本未验证。「未知」绝不能当作「支持」。

快速开始

在 LeviLamina 数据目录(如 BDS 服务器根目录)用 lip 安装最新稳定版:

lip install github.com/copper-lamp/Dear-OreUI

模组会安装到 mods/DearOreUI/。开发构建需要准备 Windows x64 LeviLamina 26.10.x 客户端环境,然后在 DearOreUI/ 目录执行:

xmake repo -u
xmake f -a x64 -m release -p windows --target_type=client -y
xmake -v -y

生成文件位于 bin/。模组元数据位于:

构建成功只证明编译和打包可用,不等于运行时 OreUI 注入已可用。

从源码构建

环境要求

  • Windows x64
  • Git
  • xmake
  • Visual Studio 或提供 Clang-CL 的 LLVM 环境
  • LeviLamina 26.10.x 开发环境

Release 构建

xmake repo -u
xmake f -a x64 -m release -p windows --target_type=client -y
xmake -v -y

Debug 构建

xmake f -a x64 -m debug -p windows --target_type=client -y
xmake -v -y

构建产物位于 bin/。

目标客户端验证

已记录:

  • Hook 发现和页面生命周期事件
  • 真实 cohtml::View 捕获与 OnReadyForBindings 门控
  • C++→JS 脚本执行与 CSSOM Overlay 构建
  • 一次 JS→C++ Facet roundtrip,含 bus.push 响应
  • 52 个组件的 UI showcase 在真实客户端挂载与清理

仍待解决:

  • JsonUI 页面注入(主菜单、世界内界面)
  • 同一 View 内多次 JS→C++ 派发
  • 卸载与生命周期清理回归
  • 目标版本之外的版本矩阵证据

开发路线

里程碑范围状态
M0运行时事实与 Hook 可行性完成
M1公共类型、Manifest 与诊断完成
M2页面生命周期与 PageContext完成
M3资源快照与最小注入完成
M4C++ 到 JavaScript 的 Host 通信完成
M5多 Mod 变更、依赖与冲突完成
M6UI 挂载与页面显示完成
M7版本化变换与 Facet Provider基本完成;变换尚未开放为公共 API
M8App、Web 与示例 Mod 对接进行中:外部 Mod 示例与 ABI 已完成;App/Web 待推进

参与贡献

贡献前请阅读上方列出的开发和 API 文档。贡献应当:

  • 区分已验证事实、设计目标和未解决的运行时问题。
  • 让运行时敏感的改动维持在既有验证记录之内。
  • 为运行时敏感的修改补充测试或目标客户端验证。
  • 修改 API、兼容性、诊断或开发契约时同步更新相关文档。
  • 不提交密钥、个人路径、构建缓存、游戏日志或玩家隐私数据。
  • 保持 libs/ 下的只读参考项目不变。

请阅读贡献指南了解贡献流程,并阅读安全政策了解漏洞私下报告方式。

许可证

DearOreUI 使用 CC0-1.0 许可证发布。

安裝 DearOreUI

執行端
  • 用戶端
平台
  • win-x64

在用戶端上,請透過以下方式安裝: LeviLauncher

從 GitHub 下載