ue-webui-bridge

UE WebUI Bridge 核心库，提供 Unreal Engine 与 Web UI 之间的双向通信桥梁。

📦 安装

``bash
npm install ue-webui-bridge
`

💡 推荐使用方式

强烈推荐搭配 ue-webui-bridge-vite 插件使用：

`bash
npm install ue-webui-bridge ue-webui-bridge-vite
`

使用 Vite 插件后，无需手动初始化，插件会自动处理所有配置和初始化工作。

⚠️ 重要提示： 如果你的项目使用了路由（如 Vue Router、React Router 等），必须使用哈希模式（Hash Mode），而不是 History 模式。这是因为 UE WebUI 环境的限制。

如果不使用 Vite 或需要手动集成，请继续阅读下面的手动初始化说明。

🚀 快速开始

$3

在 vite.config.ts 中配置插件：

`typescript
import { defineConfig } from 'vite';
import ueWebUiBridge from 'ue-webui-bridge-vite';

export default defineConfig({
plugins: [ueWebUiBridge()],
});
`

然后直接在代码中使用 API，无需调用 initUEBridge()：

`typescript
import { sendToGame, registerGameInterface } from 'ue-webui-bridge';

// 直接使用，无需初始化
sendToGame('PlayerAction', { action: 'jump' });
`

$3

如果不使用 Vite 插件，需要在应用入口处手动初始化：

`typescript
import { initUEBridge } from 'ue-webui-bridge';

// 手动初始化 UE 桥接
initUEBridge();
`

$3

使用 sendToGame 向 Unreal Engine 发送消息：

`typescript
import { sendToGame } from 'ue-webui-bridge';

// 发送简单事件
sendToGame('PlayerAction');

// 发送带数据的事件
sendToGame('UpdateScore', { score: 100, level: 5 });
`

$3

使用 registerGameInterface 注册回调函数来接收 UE 发送的消息：

`typescript
import { registerGameInterface, unregisterGameInterface } from 'ue-webui-bridge';

// 注册接口
registerGameInterface('OnGameStateChanged', (data) => {
console.log('游戏状态改变:', data);
});

// 取消注册
unregisterGameInterface('OnGameStateChanged');
`

📖 API 文档

$3

初始化 UE WebUI 桥接。

注意:

- 使用 ue-webui-bridge-vite 插件时，无需调用此方法，插件会自动处理初始化
- 仅在手动集成时需要调用，且必须在应用启动时调用一次

返回值: void

---

$3

向 Unreal Engine 发送消息。

参数:

- eventName - 事件名称
- payload - 可选的数据负载，会自动序列化为 JSON

示例:

`typescript
sendToGame('PlayerJump');
sendToGame('UpdateInventory', { itemId: 123, count: 5 });
`

---

$3

注册一个接口函数，用于接收来自 UE 的调用。

参数:

- funcName - 函数名称，需要与 UE 端调用的名称一致
- handler - 处理函数，接收来自 UE 的数据

示例:

`typescript
registerGameInterface('OnPlayerDeath', (data) => {
console.log('玩家死亡:', data);
});
`

---

$3

取消注册接口函数。

参数:

- funcName - 要取消注册的函数名称

示例:

`typescript
unregisterGameInterface('OnPlayerDeath');
`

🔧 工作原理

该库通过以下方式实现 Web UI 与 UE 的通信：

1. 初始化阶段: 创建 window.ue 和 window.ueBridge 全局对象
2. 发送消息: 使用 ue.interface.broadcast 或 URL hash 方式向 UE 发送消息
3. 接收消息: UE 通过调用 window.ue.interface 上注册的函数来向 Web UI 发送消息

📝 TypeScript 支持

本库完全使用 TypeScript 编写，提供完整的类型定义：

`typescript
// 全局类型扩展
declare global {
interface Window {
ue: {
interface: {
broadcast: (name: string, data: string) => void;
[key: string]: any;
};
};
ueBridge: (name: string, data?: any) => void;
}
}
``

🔗 相关项目

- ue-webui-bridge-vite - Vite 插件，用于构建时自动集成（推荐）

📄 许可证

GPL-3.0 © kongziming