Files

rayd1o 4b0be4cb76 release: bump version to 0.31.1

2026-04-21 22:49:39 +08:00

18 KiB

Raw Blame History

智能星球 UE5 客户端一期实施方案（融合版）

版本：v2.0
日期：2026-04-14
目标：把现有 Web Earth 项目，平滑推进到 UE5 可用 MVP 客户端
适用对象：UE 零基础新手
输出结果：一份 能直接照着做 的实施手册
策略：保留原 MVP 方案里适合入门的部分，吸收更稳的工程做法，降低你第一次做 UE 时踩坑概率

一、这份融合版方案解决什么问题

你原来的 MVP 方案是靠谱的，优点很明显：

范围克制
适合新手入门
目标明确
能较快做出“看得见、点得到”的成果

但它也有几个风险：

默认 localhost 一定通，这在 WSL2 + Windows + Docker 环境里不一定成立
默认 UE 蓝图里直接做 HTTP + JSON 解析会很顺，这一步其实很容易卡
默认“一上来就接真实后端”，新手会同时踩 UE、Cesium、网络、JSON、蓝图五个坑
时间估计略乐观

所以这份融合版方案的核心思路是：

核心原则

先做“本地数据可交互地球”，再做“真实后端对接”。

也就是把一期再拆成两个更稳的里程碑：

里程碑 A：本地演示版

先不接后端，只做：

UE5 项目能打开
Cesium 地球能显示
本地 JSON 里的点能正确落到地球
点击点能弹信息卡
HUD 能正常显示假状态

里程碑 B：后端接入版

在 A 的基础上再做：

HTTP 拉取真实后端数据
显示真实 TOP500 数据
显示后端在线状态
为后续扩展海缆/BGP/卫星打基础

这样做的好处是：

把问题拆开
更容易调试
更适合 UE 新手
不会因为后端联调没通就把整个 UE 开发节奏打断

二、一期目标：做什么，不做什么

这次一期一定要做的

做一个 可用的 UE5 客户端 MVP，达到以下 6 项：

能打开 UE 项目并看到 3D 地球
能在地球上显示超算数据点
能点击数据点弹出信息卡
能显示一个基础 HUD
能通过 HTTP 接入后端数据
能打包成 Windows 可执行程序

这次一期先不做的

这些全部放到后续阶段：

海缆路径渲染
卫星轨迹与卫星图层
BGP 图层
WebSocket 实时更新
粒子特效大升级
自动巡航
多屏/3D 偏振/大屏联动

一句话：

一期不是“把 Web Earth 全搬到 UE”，而是“证明 UE 客户端链路能跑通”。

三、UE 专有名词字典（零基础版）

这部分你最好先读一遍。后面所有步骤都围绕这些词。

1. Actor

Actor = 场景里的一个对象

你可以把它理解成：

一个地球控制器
一个超算点
一台相机
一条海缆

这些在 UE 里都可以是 Actor。

2. Component

Component = 挂在 Actor 身上的功能零件

比如一个超算点 Actor，可能有：

一个球形外观
一个碰撞盒
一个标签
一个发光效果

这些零件就是 Component。

一句话：

Actor 是整台机器，Component 是机器上的零件。

3. Blueprint（蓝图）

Blueprint = UE 的可视化编程系统

你不用先写代码，而是把很多“逻辑节点”拖出来，用线连接起来。

你可以把它理解成：

前端里的函数 + 事件监听
只不过不是写文本代码，而是连线

4. Level / Map（关卡）

Level = 一个场景文件

你可以把它理解成 Three.js 的一个 Scene。

本期只需要一个主场景：

Main

Widget = UI 组件 UMG = UE 的 UI 编辑系统

比如：

信息卡
状态栏
右上角连接状态
图例
HUD 面板

这些都用 Widget 做。

6. Material（材质）

Material = 决定物体外观的系统

比如：

球体是什么颜色
是否发光
是否透明
是否随性能大小变亮

这些都由材质控制。

7. Static Mesh

Static Mesh = 不会变形的 3D 模型

比如：

球
立方体
平面
某个固定模型

超算点一期里可以先直接用球体 Static Mesh。

8. Pawn

Pawn = 玩家控制的对象

一期里你可以把它理解成：

带相机的飞行控制器

9. PlayerController

PlayerController = 处理输入的对象

比如：

鼠标点击
拖拽
滚轮缩放

这些都由 PlayerController 或其相关逻辑来处理。

10. GameMode

GameMode = 游戏/场景的主规则配置入口

它决定：

默认用哪个 Pawn
默认用哪个 PlayerController

你可以把它理解成“主入口配置”。

11. Viewport

Viewport = 你看 3D 场景的窗口

就是 UE 编辑器中间那块 3D 视图。

12. Outliner

Outliner = 当前场景对象列表

你可以把它理解成：

Scene 树
DOM 树
资源树

13. Details Panel

Details Panel = 选中对象后的属性面板

相当于“右侧属性编辑器”。

14. Cesium for Unreal

Cesium for Unreal = UE 里的地球插件

它负责：

真实地球
卫星影像
地形
经纬度坐标和 UE 世界坐标的转换

如果没有它，你得自己处理地球和坐标系统，会非常难。

15. Struct（结构体）

Struct = 数据结构定义

你可以把它理解成 TypeScript 里的 interface。

比如：

interface ComputePoint {
  id: string
  name: string
  latitude: number
  longitude: number
  performance: number
}

在 UE 里这类东西叫 Struct。

16. Event Dispatcher

Event Dispatcher = 事件分发器

你可以把它理解成：

EventEmitter
发布订阅

比如：

“数据加载完毕”这个事件，就可以分发给其他蓝图。

17. Spline

Spline = 一条平滑曲线

后面做海缆、轨迹时非常有用。
一期可以先知道这个词，不一定马上用。

18. Niagara

Niagara = UE 粒子特效系统

比如：

流光
光晕
拖尾
火花

一期先不重点碰它。

四、你的真实开发策略：两阶段起步

这是这份融合版和原方案最大的区别。

阶段 A：本地演示版（先脱离后端）

目标

先把下面这些完全打通：

UE 项目启动正常
Cesium 地球正常
相机可操作
本地 JSON 文件能生成地球标记点
点击点能弹信息卡
HUD 能显示假数据

为什么一定要先做这个

因为如果你一上来就接真实后端，你会同时碰到：

WSL2 到 Windows 网络
Docker 端口映射
UE HTTP 请求
蓝图 JSON 解析
Cesium 坐标转换
标记点生成

新手很容易直接乱掉。

阶段 B：后端接入版（再联调）

目标

在 A 的基础上，加上：

HTTP 拉真实后端数据
显示真实 TOP500 点
右上角显示后端在线状态
为后续做更多图层留下数据接入层

五、环境准备

1. 你要安装的软件

Epic Games Launcher

用来下载和启动 UE。

Unreal Engine 5.4

建议直接用 5.4 稳定版。

Visual Studio 2022

虽然一期主要用 Blueprint，但 UE 的很多项目依赖 VS 环境。

安装组件：

Desktop development with C++
Game development with C++

Git

用来管理文档和后续工程。

Cesium for Unreal

用来做地球。

2. 你的环境约束

你现在是：

后端可能跑在 WSL2 / Docker
UE 必须跑在 Windows

所以你的真实运行方式通常会是：

Windows 运行 UE5
WSL2 运行后端
两者通过 HTTP 通信

这里最关键的一条是：

不要默认 localhost 一定能通，必须先在 Windows 浏览器里验证。

六、推荐的项目结构

UE 项目目录内的 Content 结构

Content/
  Blueprints/
  Data/
  Widgets/
  Materials/
  Levels/
  FX/
  Textures/

建议说明：

Blueprints/ 放逻辑蓝图
Data/ 放本地 JSON、DataTable、Struct
Widgets/ 放 UI
Materials/ 放材质
Levels/ 放场景
FX/ 放特效
Textures/ 放贴图

七、一期最小蓝图清单

一期只需要这几个核心蓝图。

1. `BP_GlobeCamera`

作用：相机控制器

负责：

鼠标拖拽旋转
滚轮缩放
初始视角控制

2. `BP_PlanetGameMode`

作用：指定默认的 Pawn 等

3. `BP_DataLoader`

作用：负责读数据

一期建议支持两种来源：

本地 JSON
HTTP 接口

这样调试更稳。

4. `BP_ComputePoint`

作用：一个超算点的显示对象

负责：

接收一条数据
放到正确经纬度位置
显示外观
处理点击

5. `WBP_InfoCard`

作用：点开后显示详情

显示：

名称
国家
算力
可选显示更多字段

6. `WBP_StatusBar`

作用：右上角状态栏

显示：

后端在线/离线
当前加载条数
当前模式（本地数据 / 真实后端）

八、数据层设计

一期不要一开始就完全照搬后端返回结构。
你要先定义一个 UE 友好的结构。

`S_ComputePoint`

字段建议：

PointId：字符串，唯一 ID
Name：字符串
Latitude：浮点
Longitude：浮点
Performance：浮点
CoreCount：整数
Country：字符串
Source：字符串

这个结构同时适用于：

本地 JSON
后端 API 返回结果转换后的对象

九、最稳的执行路线

下面是整个实施计划最重要的部分。

Phase 0：安装和验证环境

目标

确保你能：

安装 UE5.4
启用 Cesium
能打开一个空项目
能在 Windows 浏览器访问你的后端

验收

满足以下 4 条：

UE 能打开
Cesium 能启用
项目能创建
Windows 浏览器能访问后端 summary 接口

如果第 4 条做不到，不要继续推进真实接口联调。

Phase 1：创建项目并把地球显示出来

目标

打开项目后，能看到一个真实地球。

操作顺序

新建 UE5 Blank Blueprint 项目
创建 Main 场景
启用 Cesium
添加：
- Cesium World Terrain
- Cesium Sun Sky
- CesiumGeoreference
调整视角，让你能看到整个地球

验收

能录一段短视频，里面能看到地球和镜头移动。

Phase 2：做相机控制

目标

让地球可以：

鼠标拖拽旋转
滚轮缩放

说明

这里可以沿用原 MVP 方案的思路：

BP_GlobeCamera 作为 Pawn
Spring Arm + Camera 组成相机结构
用输入控制旋转和缩放

注意

这一版相机只是“一期可用版”，不是最终镜头系统。

验收

按 Play 后：

地球可旋转
可缩放
不会直接飞走或抖动失控

Phase 3：先喂本地 JSON 数据

这是融合版方案里最关键的改动。

目标

不接后端，先验证：

数据结构正常
JSON 能读
点能生成
点击交互正常

为什么先这么做

因为这样可以把问题收缩成 3 件事：

Cesium 坐标转换
点渲染
UI 弹窗

不牵涉后端联调。

本地 JSON 示例格式

建议放在 Content/Data/compute_points.json

[
  {
    "PointId": "top500_1",
    "Name": "Frontier",
    "Latitude": 35.93,
    "Longitude": -84.31,
    "Performance": 1194.0,
    "CoreCount": 8730624,
    "Country": "US",
    "Source": "top500"
  },
  {
    "PointId": "top500_2",
    "Name": "Fugaku",
    "Latitude": 34.69,
    "Longitude": 135.19,
    "Performance": 442.0,
    "CoreCount": 7630848,
    "Country": "JP",
    "Source": "top500"
  }
]

验收

你应该能看到：

多个点出现在地球上
大致位置正确
点击能弹信息卡

Phase 4：做超算点蓝图

目标

完成 BP_ComputePoint

每个点要实现：

接收一条 S_ComputePoint
经度纬度转成 UE 世界坐标
在地球上显示为一个可见的发光球
支持被点击

显示建议

外观

先用最简单的球体 Static Mesh。

材质

做一个发光材质：

红橙色
自发光
不追求复杂效果

大小

球体要足够大，确保在地球尺度下看得见。

高度

不要贴地表太近，建议悬浮在地表上方一个固定高度。

验收

同一批数据点在地球上的位置大体合理。

Phase 5：做信息卡

目标

点击一个点后，弹出一个简单的信息卡。

`WBP_InfoCard` 要显示的内容

建议只显示最关键的 3 个字段：

名称
国家
算力

一期先不要堆太多字段。

验收

点击点 → 卡片出现
点击关闭 → 卡片消失

Phase 6：做基础 HUD

目标

屏幕上始终有一个简单状态栏。

`WBP_StatusBar` 显示内容建议

当前模式：Local / HTTP
已加载数据点数量
后端状态：Unknown / Online / Offline

在本地模式阶段，状态可以先写死或显示 Local Demo。

验收

不点击任何点时，屏幕右上角也有“系统正在工作”的感觉。

Phase 7：再接真实后端

这是第二阶段开始。

目标

把数据源从本地 JSON 切到 HTTP。

正确做法

不要把 BP_DataLoader 重写。
而是让它支持：

LocalJsonLoader
HttpLoader

也就是：

显示层不变，只替换数据来源。

最重要的接口原则

如果后端已有接口字段非常杂，不一定要 UE 直接吃。
可以加一个“更适合 UE 的轻量接口”。

例如：

/api/v1/ue/bootstrap/top500

返回尽量扁平的数据：

[
  {
    "PointId": "top500_1",
    "Name": "Frontier",
    "Latitude": 35.93,
    "Longitude": -84.31,
    "Performance": 1194.0,
    "CoreCount": 8730624,
    "Country": "US",
    "Source": "top500"
  }
]

为什么推荐 UE 轻量接口

因为 UE 不适合像前端 React 那样，层层解包一大堆复杂 JSON。

Phase 8：做连接状态检测

目标

让 HUD 能显示：

在线
离线
本地模式

正确实现思路

建议用一个很小的状态请求，比如：

summary 接口
health 接口
或 UE 专用 ping 接口

不要让状态检测去依赖一个超大的数据接口。

验收

后端关掉时，状态栏能明显变成 Offline。

Phase 9：打包发布

目标

把项目打包成 Windows 可执行程序。

注意

打包是一期必须尝试的，但不要让它阻塞前面所有开发。

也就是说：

编辑器里没稳定跑通前，不要反复纠结打包
等 LocalJson 版和 HTTP 版都能在编辑器 Play 模式稳定运行后，再打包

验收

双击 exe 可以运行，进入地球场景并正常展示数据。

十、建议的 14 天执行计划

这版比原 MVP 的时间估计更保守，也更适合新手。

第 1 天

安装 UE5.4
安装 Cesium
创建空项目
创建 Main 场景

第 2 天

启用 Cesium
把地球跑起来
保存项目结构

第 3 天

做 BP_GlobeCamera
跑通旋转和缩放

第 4 天

建 S_ComputePoint
准备本地 JSON 文件
做 BP_DataLoader 的本地模式

第 5 天

做 BP_ComputePoint
本地 JSON 批量生成点

第 6 天

调整点大小、颜色、高度
检查经纬度位置是否大致正确

第 7 天

做 WBP_InfoCard
跑通点击点弹卡片

第 8 天

做 WBP_StatusBar
显示本地模式状态和点数量

第 9 天

Windows 浏览器验证后端接口
准备 HTTP 版加载逻辑

第 10 天

实现 HTTP 拉真实数据
先在日志里确认数据到了

第 11 天

把 HTTP 数据接到点渲染
切换 Local / HTTP 两种模式

第 12 天

做连接状态 Online / Offline
补错误提示

第 13 天

测试完整链路
修点选、缩放、HUD 细节

第 14 天

进行第一次打包
在 Windows 下运行 exe 验证

十一、这份方案和原 MVP 方案怎么融合

下面是合并关系。

保留原 MVP 方案的部分

这些内容很好，建议继续用：

术语表
Phase 结构化写法
BP_GlobeCamera
BP_ComputePoint
WBP_InfoCard
WBP_StatusBar
相机、点、信息卡、状态栏这 4 个核心对象
“先别做海缆、卫星、BGP”的范围控制

用融合版修正的部分

这些是这份新文档加进去的：

两阶段起步：先本地 JSON，再真实后端
不默认 localhost 一定通
推荐做 UE 轻量接口，而不是死扛原始接口
把打包放到后段，而不是过早纠结
时间预估更保守
明确“一期只是证明链路跑通”

十二、验收清单

环境

UE5.4 安装成功
Cesium 插件启用成功
Windows 能访问后端接口

本地演示版

地球渲染正常
鼠标可旋转和缩放
本地 JSON 数据能生成点
点的位置大体正确
点击点能弹信息卡
HUD 可显示本地模式和点数量

后端接入版

HTTP 能拉取真实数据
HTTP 数据能生成点
HUD 能显示 Online/Offline
切换 Local / HTTP 模式不崩
exe 能打包并运行

十三、后续路线（MVP 之后）

当这一期做完后，下一步顺序建议是：

海缆路径
卫星点或轨迹
更稳的相机与巡航
WebSocket 增量更新
BGP 区域态势
BGP 事件点
更强的粒子和视觉风格

也就是说：

先补“静态层和镜头层”，再补“高频实时层”。

十四、一句话总结

这份融合版方案的核心就是：

保留原 MVP 的入门友好度，但改成“先本地 JSON、再真实后端”的两阶段实施路线，让你第一次做 UE 时更稳、更容易成功。

如果你按这份方案推进，一期最现实的目标不是“立刻做出完整 UE 大屏”，而是：

在 14 天左右，做出一个能显示真实地球、能显示超算点、能点击看详情、能接后端的可用 UE 客户端 MVP。

附录：来自 sisyphus 草案的补充

这部分吸收自一个 sisyphus-created draft，原始草案已归档，不再单独维护为主计划。

1. 项目骨架建议

原草案给过一个更偏“工程初始化”的目录示意，适合拿来做一期的命名参考：

Levels/
Blueprints/
Materials/
Widgets/
Source/PlanetAPI/
Source/CesiumIntegration/
Source/Visualization/

这不是强制结构，但对 UE 初期整理目录很有帮助。

2. API 契约意识

原草案有一个很对的提醒：

一期虽然可以先走 HTTP
但数据模型命名不应只服务于一次性演示
后续 WebSocket 接入时，字段设计最好能沿用

所以当前主计划继续建议：

先做 HTTP 拉取
尽量把 UE 侧数据模型定义清楚
不要在蓝图各处散写临时 JSON 字段解析

18 KiB Raw Blame History Unescape Escape

智能星球 UE5 客户端一期实施方案（融合版）

一、这份融合版方案解决什么问题

核心原则

里程碑 A：本地演示版

里程碑 B：后端接入版

二、一期目标：做什么，不做什么

这次一期一定要做的

这次一期先不做的

三、UE 专有名词字典（零基础版）

1. Actor

2. Component

3. Blueprint（蓝图）

4. Level / Map（关卡）

5. Widget / UMG

6. Material（材质）

7. Static Mesh

8. Pawn

9. PlayerController

10. GameMode

11. Viewport

12. Outliner

13. Details Panel

14. Cesium for Unreal

15. Struct（结构体）

16. Event Dispatcher

17. Spline

18. Niagara

四、你的真实开发策略：两阶段起步

阶段 A：本地演示版（先脱离后端）

目标

为什么一定要先做这个

阶段 B：后端接入版（再联调）

目标

五、环境准备

1. 你要安装的软件

Epic Games Launcher

Unreal Engine 5.4

Visual Studio 2022

Git

Cesium for Unreal

2. 你的环境约束

六、推荐的项目结构

UE 项目目录内的 Content 结构

七、一期最小蓝图清单

1. BP_GlobeCamera

2. BP_PlanetGameMode

3. BP_DataLoader

4. BP_ComputePoint

5. WBP_InfoCard

6. WBP_StatusBar

八、数据层设计

S_ComputePoint

九、最稳的执行路线

Phase 0：安装和验证环境

目标

验收

Phase 1：创建项目并把地球显示出来

目标

操作顺序

验收

Phase 2：做相机控制

目标

说明

注意

验收

Phase 3：先喂本地 JSON 数据

目标

为什么先这么做

本地 JSON 示例格式

推荐做法

验收

Phase 4：做超算点蓝图

目标

显示建议

外观

材质

大小

高度

验收

18 KiB

Raw Blame History

1. `BP_GlobeCamera`

2. `BP_PlanetGameMode`

3. `BP_DataLoader`

4. `BP_ComputePoint`

5. `WBP_InfoCard`

6. `WBP_StatusBar`

`S_ComputePoint`

`WBP_InfoCard` 要显示的内容

`WBP_StatusBar` 显示内容建议