planet/unreal/UE57_WebSocket_Integration.md

UE5.7 连接 ue_scene 数据接口实操

目标

把当前后端的 ue_scene WebSocket 数据接到 UE5.7 工程里。

当前后端入口：

• backend/app/api/v1/websocket.py
• backend/app/core/websocket/ue_scene.py

本次补的 UE 侧最小 C++ 文件：

• Planet.Build.cs
• UeSceneWebSocketClient.h
• UeSceneWebSocketClient.cpp

这一步先做什么

先做最小闭环：

1. UE 登录后端拿 token
2. UE 连接 /ws
3. UE 订阅 ue_scene
4. UE 发送 sync_request
5. UE 收到原始 JSON

先不急着做完整场景生成。

第 1 步：把代码放进你的 UE5.7 工程

你的真实 UE 工程里应该有：

YourProject/
  Source/
    YourProject/

把这里的示例代码内容按模块名改进去：

• Planet.Build.cs
• UeSceneWebSocketClient.h
• UeSceneWebSocketClient.cpp

如果你的工程模块名不是 Planet，要把：

• PLANET_API

改成你自己的模块导出宏。

第 2 步：启用插件

在 UE5.7 编辑器里启用：

• WebSockets
• HTTP
• Json Blueprint Utilities（可选）

启用后重启编辑器。

第 3 步：重新生成并编译工程

如果你是 Visual Studio 工作流：

1. 右键 .uproject
2. 选择“生成 Visual Studio 项目文件”
3. 打开 .sln
4. 编译 Development Editor

第 4 步：把组件挂到 BP_GlobeController

编译成功后：

1. 打开 BP_GlobeController
2. 点击 添加
3. 搜索：
   • Ue Scene Web Socket Client
4. 把这个组件挂进去

第 5 步：填写后端参数

选中这个组件，在 细节 面板里填写：

• Backend Base Url：http://127.0.0.1:8000
• Username：你的后端用户名
• Password：你的后端密码

默认频道已经是：

• ue_scene

第 6 步：在蓝图里接事件

在 BP_GlobeController 里接这几个事件：

On Connected Changed

连接成功后：

1. 调 Send Subscribe
2. 再调 Send Initial Sync Request

On Raw Message

先不要急着解析全部结构。

第一步只做：

1. 把原始 JSON 打印出来
2. 或保存到字符串变量

这样先确认 UE 确实收到后端消息。

On Error

把错误字符串打印到屏幕和日志里。

蓝图推荐连法

开始游戏时

1. 开始游戏时
2. 调组件的 Connect To Backend

连接成功后

1. On Connected Changed
2. 分支
3. 如果 bConnected = true
4. 调 Send Subscribe
5. 调 Send Initial Sync Request

收消息后

1. On Raw Message
2. 打印字符串

第 7 步：先验证消息类型

你应该先在屏幕或输出日志里确认这些消息已经进来了：

1. connection_established
2. subscription_confirmed
3. data_frame

其中 data_frame 的第一条应是：

• channel = ue_scene
• update_type = full

第 8 步：再接 JSON 解析

当前这一步不建议纯蓝图手搓整个 JSON 结构。

更稳的是：

1. 先在 C++ 里加一个简单解析层
2. 只抽出 type
3. 只抽出 data.update_type
4. 只抽出 payload.layers.gpu_clusters.items

先把 gpu_clusters 画出来，再扩到别的层。

当前阶段建议

先完成这 3 件事就够了：

1. UE 能成功连接后端
2. UE 能收到 full 快照
3. UE 能把原始 JSON 打印出来

做到这一步，我们再继续补：

• JSON 结构体
• ApplyFullScene
• ApplyIncrementalScene
• GeoToWorld

一句最重要的提醒

现在先别在 UE 里同时做：

• WebSocket 连接
• 全量 JSON 解析
• 点位生成
• 海缆生成

一步一步来，先确认“连通”，再做“可视化”。这样最不容易卡死。