webui-dev

WebUI Development

本项目的游戏内 UI 运行在 UE5 内嵌 CEF 浏览器中，通过 JSON 与游戏引擎双向通信。

通信模式

UE → JS（游戏推数据到页面）：

window.onXxx = function(jsonStr) {
    var data = JSON.parse(jsonStr);
    // 渲染界面
};

JS → UE（页面发操作给游戏）：

// 每个页面顶部必须定义此函数
function sendToUE(action, data) {
    if (window.ue && window.ue.bridge) {
        window.ue.bridge.postmessage(action, JSON.stringify(data || {}));
    }
}

// 使用
sendToUE("shop.buyItem", { itemId: "rope", count: 1 });

注意：CEF 将 UObject 方法绑定到 JS 时，方法名会转为全小写。C++ 侧是 PostMessage，JS 侧必须写 postmessage。写成 PostMessage 会静默失败（不报错，但消息不会到达 C++）。

规则

1. 每个界面是独立的单 HTML 文件，内联 CSS 和 JS，不依赖外部框架或其他页面
2. 数据接收用 window.onXxx(jsonStr)，操作发送用 sendToUE(action, data)
3. 动作名加页面前缀："页面名.动作"（如 shop.buyItem、pharmacy.purchase）
4. 关闭界面统一用 sendToUE("close")，所有页面一样
5. UE 未实现的数据用 MOCK 占位，让页面能在浏览器中独立运行：

   // MOCK：独立调试用，UE接入后删除
   window.onXxx(JSON.stringify({ mock data here }));
   

   MOCK 清理规则：功能接入 UE 并验收通过后，必须删除所有 MOCK 代码（尤其是 setTimeout 触发的 MOCK 回调）。残留的 MOCK 会在运行时产生虚假行为，且难以排查——因为日志中不会有对应的 C++ 调用记录。
6. 文件放在 Content/WebUI/ 下按功能分目录，命名用小写中划线
7. C++ 侧函数名是 PostMessage，但绑定到 JS 后调用名会映射为小写；因此 JS 必须使用 window.ue.bridge.postmessage(...)（全小写），禁止写 PostMessage

接口清单

每个页面代码末尾必须输出 @INTERFACE_LIST HTML 注释，格式：

<!--
@INTERFACE_LIST
页面文件：目录/xxx.html
页面说明：一句话描述

[打开方式]
- 游戏内触发条件：{什么时候打开}
- 打开时传入数据：window.onXxx(jsonStr)，格式：{ 字段: 类型 }
- 关闭方式：sendToUE("close")

[UE → JS]
- window.onXxx(jsonStr)
  触发时机：{何时调用}
  数据格式：{ 字段: 类型 }

[JS → UE]
- sendToUE("页面名.动作", { 字段: 类型 })
  触发时机：{用户做了什么}
  期望UE响应：{UE做什么，完成后调哪个 window.onXxx}
-->

C++ 桥接层架构

UE5 WebUI 桥接层的标准实现：

C++ 侧（发送数据到 JS）：

// 在 WebUIWidget 子类中
void UMyWidget::SendDataToPage(const FMyData& Data)
{
    FString JsonStr = /* 序列化 Data 为 JSON */;
    SendToJS(TEXT("onDataReceived"), JsonStr);
}

C++ 侧（接收 JS 消息）：

void UMyWidget::OnWebAction(const FString& Action, const FString& JsonData)
{
    if (Action == TEXT("shop.buyItem"))
    {
        // 解析 JsonData，执行游戏逻辑
    }
}