ue-webui-bridge

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

📦 安装

npm install ue-webui-bridge

💡 推荐使用方式

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

npm install ue-webui-bridge ue-webui-bridge-vite

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

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

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

🚀 快速开始

方式一：使用 Vite 插件（推荐）

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

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

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

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

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

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

方式二：手动初始化

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

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

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

发送消息到 UE

使用 sendToGame 向 Unreal Engine 发送消息：

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

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

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

接收来自 UE 的消息

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

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

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

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

📖 API 文档

initUEBridge()

初始化 UE WebUI 桥接。

注意:

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

返回值: void

sendToGame<T>(eventName: string, payload?: T): void

向 Unreal Engine 发送消息。

参数:

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

示例:

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

registerGameInterface<T>(funcName: string, handler: (data: T) => void): void

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

参数:

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

示例:

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

unregisterGameInterface(funcName: string): void

取消注册接口函数。

参数:

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

示例:

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 编写，提供完整的类型定义：

// 全局类型扩展
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