DearOreUI

Extend Minecraft Bedrock's OreUI at runtime.

A native LeviLamina client mod for reading, transforming, and injecting OreUI resources.

Releases · Changelog · Documentation · Designer · Example mod · Contributing · 简体中文

Note

DearOreUI has moved past the pure scaffold stage. The hooks, resource snapshot, multi-mod registry, transforms, injection, Host/Facet bridge, UI mounting, and API facades described below are implemented, and the display chain has been verified against a real client on OreUI-stack pages.

Overview

DearOreUI is a native Windows x64 client mod for LeviLamina 26.10.x. It reads the OreUI resources loaded by the original Minecraft client, combines changes declared by multiple mods, and injects the verified result back into the active OreUI page. This lets you focus on writing your own UI without worrying about UI compatibility with other mods. DearOreUI is not a replacement UI and does not directly expose page pointers, compiled bundle internals, or arbitrary local file access to other mods.

Ecosystem

DearOreUI is the runtime core of a full toolchain for building Minecraft Bedrock user interfaces:

Project	Repository	Role
DearOreUI	copper-lamp/Dear-OreUI	Native LeviLamina runtime (this repo) — hook, snapshot, transform, inject OreUI
DearOreUI Designer	copper-lamp/DearOreUI-dev-tools	Offline visual designer (Tauri) — auto-detect and preview mod UI without launching the game
DearOreUI Docs	copper-lamp/dearoreui-docs	Official documentation and learning site (https://copper-lamp.github.io/dearoreui-docs/)
dearoreui-ExampleMod	magicobs0z/dearoreui-ExampleMod	Progressive tutorial mod (calendar theme) built on DearOreUI
dearoreui-repo	copper-lamp/dearoreui-repo	Self-hosted xmake package repo for the header-only public API

What Works

• Runtime hooks. The mod hooks TechStack selection, SceneProvider scene creation, Router navigation, OreUI::View::initialize, OnReadyForBindings, triggerEvent, and ClientInstance::update.
• Real display chain. A cohtml::View is captured, scripts are gated on OnReadyForBindings, and CoherentHostBridge::sendScript executes them. The DOM overlay is built through CSSOM, not innerHTML. This chain was verified on the world list page (/play/all).
• Resource snapshot. FileSystemSourceReader reads the original gui/dist/hbui resources; ResourceUri and ResourceIndex manage paths and access.
• Multi-mod registry. Mods register resources, scripts, styles, UI, and transforms. The central registry sorts dependencies, detects conflicts, and builds one change plan per page.
• Declarative UI. registerMod / registerOverlay feed UiPlanner, MountManager, and UiStateMachine. A 52-component showcase renders end to end on the real client.
• Host bridge. HostDispatcher and HostMethodRegistry route JS requests to native methods with permission checks. JS to native runs over the game's native facet protocol: DearOreUI.call → facet:request → OreUIFacetBridge → HostDispatcher → bus.push.
• Public API. IDearOreUIApi merges Runtime, Resource, Mod, Host, UI, Page, Event, Transform, Diagnostic, Frame, and RuntimeReport facets. External mods obtain it through the pure C ABI bridge (DearOreUI_QueryApi).
• JS namespace. window.__DearOreUI__ (protocol info, bus, ipc) and window.DearOreUI (call, report) are injected, plus base oreui.* namespaces.
• Diagnostics. JSONL event stream, per-stage telemetry, injection reports, and crash probes are written without touching the game installation.

Development Status

Capability	Status
LeviLamina mod lifecycle	Implemented
Windows x64 client build	Working via xmake + Clang-CL
OreUI / Coherent runtime hook	Implemented, client-verified
Original OreUI resource snapshot	Implemented
Multi-mod resource registry	Implemented
Dependency ordering and conflict detection	Implemented
Resource and code transformation	Implemented internally (ChangePlanner)
UI mounting and page lifecycle	Implemented, client-verified
C++ and JavaScript Host API	Basic API implemented, JS side injected
Crash isolation experiment	Implemented

Not covered yet:

Capability	Status
JsonUI pages (main menu, in-game screens)	Not supported
Multiple JS→C++ calls per View	Limited to one effective dispatch
Public event/page subscription facade	Not formed
Diagnostic query facade	Not formed
Versioned transform as public API	Not exposed

Progressive API Model

L0  Runtime queries
    ↓
L1  Resource, script, and stylesheet registration
    ↓
L2  Page lifecycle and PageContext
    ↓
L3  UI mounting and page extensions
    ↓
L4  Permission-checked Host API
    ↓
L5  Versioned code and resource transforms
    ↓
L6  Facet providers and advanced compatibility adapters

Most mods should remain at L1. Higher levels are opt-in because they require more knowledge of page lifecycle, host capabilities, compatibility constraints, or original bundle structure.

Multi-Mod Collaboration

Mods do not directly mutate the same intermediate string or write to the game installation. They register declarations with DearOreUI, which creates one page-scoped change plan from the original resource snapshot.

Mod A registration
Mod B registration
Mod C registration
    ↓
Central registry
    ↓
Page, version, and capability filtering
    ↓
Dependency ordering
    ↓
Conflict detection
    ↓
Resource and code transformation
    ↓
Integrity validation
    ↓
One injection submission

The default rules are:

• Resource paths are isolated by mod namespace.
• Identical registrations are idempotent.
• Different contents targeting the same owned resource produce a conflict.
• Replacements require an expected original fingerprint.
• Multiple replacements of the same original code region conflict by default.
• A failed mod change is isolated from unrelated changes.
• An unsupported version preserves the original page.
• Every conflict, skip, failure, and fallback produces a report.

Compatibility

The current target is a client-only LeviLamina mod for Windows x64:

Component	Target
Minecraft Bedrock	Client on Windows x64
LeviLamina	26.10.x
Native entry	DearOreUI.dll
C++ standard	C++20
Toolchain	Clang-CL
Build system	xmake
Mod version	0.1.2

OreUI bundle compatibility cannot be inferred from the Minecraft version alone. Runtime support depends on the detected OreUI resources, Coherent host, page type, resource fingerprint, and available capabilities.

Verified boundary, from the stage 7.1 and stage 8-A client records:

• The display chain works on OreUI-stack pages, currently the world list page.
• One JS→C++ roundtrip has been recorded against the real client.
• JsonUI pages (main menu, in-game screens) run on a different stack and are outside this pipeline.
• Other Minecraft / LeviLamina versions are unverified. "Unknown" must never be treated as "Supported".

Quick Start

Install the latest stable release with lip (run inside your LeviLamina data directory, e.g. the Bedrock Server root):

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

The mod is placed under mods/DearOreUI/. For development builds, prepare a Windows x64 LeviLamina 26.10.x client environment and build from the DearOreUI/ directory.

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

The generated files are placed under bin/. The package metadata is defined in:

• manifest.json
• tooth.json
• xmake.lua

A successful build validates compilation and packaging. It does not prove runtime OreUI injection.

Build From Source

Requirements

• Windows x64
• Git
• xmake
• Visual Studio or an LLVM installation providing Clang-CL
• A LeviLamina 26.10.x development environment

Release build

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

Debug build

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

Build artifacts are written to bin/.

Target-client validation

Recorded:

• Hook discovery and page lifecycle events
• Real cohtml::View capture and OnReadyForBindings gating
• C++→JS script execution and CSSOM overlay build
• One JS→C++ Facet roundtrip with bus.push response
• A 52-component UI showcase mount and cleanup on the real client

Still open:

• JsonUI page injection (main menu, in-game screens)
• Multiple JS→C++ dispatches per View
• Uninstall and lifecycle cleanup regression
• Version matrix evidence beyond the recorded target

Roadmap

Milestone	Scope	Status
M0	Runtime facts and Hook feasibility	Done
M1	Public types, Manifest, and diagnostics	Done
M2	Page lifecycle and PageContext	Done
M3	Resource snapshot and minimal injection	Done
M4	C++ to JavaScript Host communication	Done
M5	Multi-mod changes, dependencies, and conflicts	Done
M6	UI mounting and page display	Done
M7	Versioned transforms and Facet providers	Mostly done; transform not yet a public API
M8	App, Web, and example-mod integration	In progress: external mod example and ABI done; App/Web pending

Contributing

Before contributing, read the development and API documents listed above. Contributions should:

• Distinguish verified facts, design targets, and unresolved runtime questions.
• Keep runtime-sensitive changes behind the existing validation records.
• Include tests or target-client validation for runtime-sensitive changes.
• Update the relevant API, compatibility, diagnostic, and development documents when contracts change.
• Avoid committing secrets, personal paths, build caches, game logs, or private player data.
• Leave the read-only reference project under libs/ unchanged.

See CONTRIBUTING.md for the contribution workflow and SECURITY.md for private vulnerability reporting.

License

DearOreUI is released under the CC0-1.0 license.