UE WebUI Bridge - A bidirectional communication bridge between Unreal Engine and Web UI
npm install ue-webui-bridgeUE 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 或需要手动集成,请继续阅读下面的手动初始化说明。
在 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' });
`
如果不使用 Vite 插件,需要在应用入口处手动初始化:
`typescript
import { initUEBridge } from 'ue-webui-bridge';
// 手动初始化 UE 桥接
initUEBridge();
`
使用 sendToGame 向 Unreal Engine 发送消息:
`typescript
import { sendToGame } from 'ue-webui-bridge';
// 发送简单事件
sendToGame('PlayerAction');
// 发送带数据的事件
sendToGame('UpdateScore', { score: 100, level: 5 });
`
使用 registerGameInterface 注册回调函数来接收 UE 发送的消息:
`typescript
import { registerGameInterface, unregisterGameInterface } from 'ue-webui-bridge';
// 注册接口
registerGameInterface('OnGameStateChanged', (data) => {
console.log('游戏状态改变:', data);
});
// 取消注册
unregisterGameInterface('OnGameStateChanged');
`
初始化 UE WebUI 桥接。
注意:
- 使用 ue-webui-bridge-vite 插件时,无需调用此方法,插件会自动处理初始化
- 仅在手动集成时需要调用,且必须在应用启动时调用一次
返回值: void
---
向 Unreal Engine 发送消息。
参数:
- eventName - 事件名称payload
- - 可选的数据负载,会自动序列化为 JSON
示例:
`typescript`
sendToGame('PlayerJump');
sendToGame('UpdateInventory', { itemId: 123, count: 5 });
---
注册一个接口函数,用于接收来自 UE 的调用。
参数:
- funcName - 函数名称,需要与 UE 端调用的名称一致handler
- - 处理函数,接收来自 UE 的数据
示例:
`typescript`
registerGameInterface('OnPlayerDeath', (data) => {
console.log('玩家死亡:', data);
});
---
取消注册接口函数。
参数:
- funcName - 要取消注册的函数名称
示例:
`typescript`
unregisterGameInterface('OnPlayerDeath');
该库通过以下方式实现 Web UI 与 UE 的通信:
1. 初始化阶段: 创建 window.ue 和 window.ueBridge 全局对象ue.interface.broadcast
2. 发送消息: 使用 或 URL hash 方式向 UE 发送消息window.ue.interface
3. 接收消息: UE 通过调用 上注册的函数来向 Web UI 发送消息
本库完全使用 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