461 lines
8.3 KiB
Markdown
461 lines
8.3 KiB
Markdown
# UE5 3D 大屏场景搭建完整指南
|
||
|
||
## 目录
|
||
|
||
1. [项目初始化](#项目初始化)
|
||
2. [安装 Cesium 插件](#安装-cesium-插件)
|
||
3. [创建主场景](#创建主场景)
|
||
4. [配置光照](#配置光照)
|
||
5. [设置相机](#设置相机)
|
||
6. [添加蓝图组件](#添加蓝图组件)
|
||
7. [配置后端连接](#配置后端连接)
|
||
8. [测试运行](#测试运行)
|
||
|
||
---
|
||
|
||
## 项目初始化
|
||
|
||
### 步骤 1: 创建 UE5 项目
|
||
|
||
```
|
||
1. 打开 Epic Games Launcher
|
||
2. 选择 Unreal Engine 5.3+ (推荐 5.4)
|
||
3. 点击 "New Project" → "Games"
|
||
4. 选择 "Blank" 模板
|
||
5. 设置:
|
||
├─ 项目名: Planet
|
||
├─ 位置: D:\games\Planet\
|
||
├─ 目标: Desktop / Console
|
||
├─ 质量: Maximum
|
||
├─ -starter content: false
|
||
└─ raytracing: false
|
||
6. 点击 "Create Project"
|
||
```
|
||
|
||
### 步骤 2: 项目设置
|
||
|
||
```
|
||
Edit → Project Settings:
|
||
|
||
显示设置:
|
||
├─ Render → Default Viewport:
|
||
│ ├─ Fullscreen Mode: Windowed
|
||
│ ├─ Resolution: 3840×2160 (4K)
|
||
│ └─ Custom Near Clip Plane: 100
|
||
├─ Input:
|
||
│ ├─ Capture Mouse on Launch: true
|
||
│ └─ Enable Click Events: true
|
||
└─ Quality:
|
||
└─ Shadow Quality: High
|
||
```
|
||
|
||
---
|
||
|
||
## 安装 Cesium 插件
|
||
|
||
### 方法 1: 通过 Marketplace (推荐)
|
||
|
||
```
|
||
1. 打开 UE5 编辑器
|
||
2. Edit → Plugins
|
||
3. 搜索 "Cesium for Unreal"
|
||
4. 点击 "Enable"
|
||
5. 重启编辑器
|
||
```
|
||
|
||
### 方法 2: 手动安装
|
||
|
||
```
|
||
1. 从 GitHub 下载:
|
||
https://github.com/CesiumGS/cesium-unreal/releases
|
||
|
||
2. 解压到:
|
||
D:\games\Planet\unreal\Plugins\Cesium
|
||
|
||
3. 编辑uproject文件:
|
||
{
|
||
"Plugins": [
|
||
{
|
||
"Name": "Cesium",
|
||
"Enabled": true
|
||
}
|
||
]
|
||
}
|
||
|
||
4. 右键 Planet.uproject → "Generate Visual Studio project files"
|
||
5. 重新打开项目
|
||
```
|
||
|
||
### 配置 Cesium ion Token
|
||
|
||
```
|
||
Edit → Project Settings → Cesium:
|
||
|
||
1. Cesium ion:
|
||
├─ Default Access Token: 粘贴你的 token
|
||
│ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||
└─ Default Server: https://ion.cesium.com
|
||
|
||
2. Cesium World Terrain:
|
||
├─ Enable: true
|
||
├─ Ellipsoid: WGS84
|
||
└─ Terrain Exaggeration: 1.0
|
||
|
||
3. Cesium OSM Buildings:
|
||
├─ Enable: true
|
||
└─ Style: Gray
|
||
```
|
||
|
||
---
|
||
|
||
## 创建主场景
|
||
|
||
### 步骤 1: 创建新关卡
|
||
|
||
```
|
||
1. File → New Level → Default
|
||
2. 删除默认的:
|
||
├─ Floor
|
||
├─ Wall_400
|
||
├─ Wall_400x400
|
||
└─ PlayerStart
|
||
3. 保存为: Content/Levels/Main.umap
|
||
4. 设置为启动关卡:
|
||
Edit → Project Settings → Maps & Modes
|
||
└─ Default Level Name: Main
|
||
```
|
||
|
||
### 步骤 2: 添加 Cesium 组件
|
||
|
||
从 "Cesium" 面板拖入:
|
||
|
||
```
|
||
1. CesiumGeoreference
|
||
└─ 位置: (0, 0, 0)
|
||
└─ 属性: 自动设置
|
||
|
||
2. CesiumWorldTerrain
|
||
└─ 位置: (0, 0, 0)
|
||
└─ 属性:
|
||
├─ Enable Collision: false
|
||
└─ Create Pawns: false
|
||
|
||
3. CesiumSunSky
|
||
└─ 位置: (0, 0, 0)
|
||
└─ 属性:
|
||
├─ Use Solar Time: true
|
||
└─ Solar Time: 2024-01-01 12:00:00
|
||
```
|
||
|
||
### 步骤 3: 配置地球位置
|
||
|
||
```
|
||
选中 CesiumGeoreference:
|
||
|
||
├─ Origin Location:
|
||
│ ├─ Latitude: 0
|
||
│ ├─ Longitude: 0
|
||
│ └─ Height: 0
|
||
│
|
||
├─ Target Viewport:
|
||
│ ├─ Width: 3840
|
||
│ └─ Height: 2160
|
||
│
|
||
└─ Camera:
|
||
└─ Default Camera Class: None
|
||
```
|
||
|
||
---
|
||
|
||
## 配置光照
|
||
|
||
### 步骤 1: 设置太阳光照
|
||
|
||
```
|
||
选中 CesiumSunSky:
|
||
|
||
├─ Atmospheric Sun Light:
|
||
│ └─ 指向 DirectionalLight_Sun
|
||
│
|
||
├─ Direction:
|
||
│ ├─ Azimuth: 180
|
||
│ └─ Altitude: 45
|
||
│
|
||
├─ Sky Light:
|
||
│ └─ Sky Light Actor → SkyLight
|
||
│
|
||
└─ Atmospheric Fog:
|
||
├─ Fog Density: 0.02
|
||
├─ Fog Falloff: 0.2
|
||
└─ Volumetric Fog: true
|
||
```
|
||
|
||
### 步骤 2: 添加辅助光照
|
||
|
||
```
|
||
1. 添加 DirectionalLight_Sun:
|
||
├─ Intensity: 10 lux
|
||
├─ Light Color: (1, 0.95, 0.8)
|
||
└─ Cast Shadows: true
|
||
|
||
2. 添加 Skylight:
|
||
├─ Intensity: 1.0
|
||
├─ Color: (0.5, 0.7, 1.0)
|
||
└─ Real-time Capture: false
|
||
```
|
||
|
||
### 步骤 3: 后处理
|
||
|
||
```
|
||
添加 PostProcessVolume (Unbound):
|
||
|
||
├─ Exposure:
|
||
│ ├─ Min EV100: 10
|
||
│ ├─ Max EV100: 20
|
||
│ ├─ Speed Up: 2
|
||
│ ├─ Speed Down: 2
|
||
│ └─ Target EV100: 12
|
||
│
|
||
├─ Bloom:
|
||
│ ├─ Intensity: 1.0
|
||
│ ├─ Threshold: 1.0
|
||
│ └─ Method: Convolution
|
||
│
|
||
├─ Color Grading:
|
||
│ ├─ Saturation: (1, 1, 1)
|
||
│ ├─ Contrast: 1.0
|
||
│ └─ Gamma: 1.0
|
||
│
|
||
└─ Vignette:
|
||
└─ Intensity: 0.5
|
||
```
|
||
|
||
---
|
||
|
||
## 设置相机
|
||
|
||
### 步骤 1: 创建相机控制器
|
||
|
||
```
|
||
创建 Blueprint: BP_CameraController (父类: Actor)
|
||
|
||
组件:
|
||
├─ SceneRoot
|
||
│ └─ SpringArm
|
||
│ └─ Camera
|
||
│
|
||
变量:
|
||
├─ TargetRadius: Float = 500000
|
||
├─ ZoomSpeed: Float = 50000
|
||
├─ RotateSpeed: Float = 1.0
|
||
└─ bIsRotating: Boolean = false
|
||
```
|
||
|
||
### 步骤 2: 配置相机移动
|
||
|
||
```
|
||
输入绑定 (Edit → Project Settings → Input):
|
||
|
||
├─ Mouse X:
|
||
│ └─ Event: Rotate Yaw
|
||
│ └─ Add Controller Yaw Input × -1
|
||
│
|
||
├─ Mouse Y:
|
||
│ └─ Event: Rotate Pitch
|
||
│ └─ Add Controller Pitch Input × -1
|
||
│
|
||
├─ Mouse Wheel:
|
||
│ └─ Event: Zoom
|
||
│ ├─ Add Controller Zoom In (放大)
|
||
│ └─ Add Controller Zoom Out (缩小)
|
||
│
|
||
└─ Right Mouse Button:
|
||
├─ Event: 按下 → bIsRotating = true
|
||
└─ Event: 松开 → bIsRotating = false
|
||
```
|
||
|
||
### 步骤 3: 自动巡航
|
||
|
||
```
|
||
创建 Timeline: AutoRotate
|
||
|
||
├─ 持续时间: 60秒
|
||
├─ 循环: true
|
||
└─ 曲线:
|
||
0%: 0
|
||
100%: 360
|
||
|
||
Tick Event:
|
||
├─ 分支: bAutoRotate == true
|
||
│ ├─ Play Timeline
|
||
│ └─ Add Controller Yaw Output
|
||
└─ 否则: 跳过
|
||
```
|
||
|
||
---
|
||
|
||
## 添加蓝图组件
|
||
|
||
### 步骤 1: 放置 GlobeController
|
||
|
||
```
|
||
1. 从 Content Browser 拖入 BP_GlobeController
|
||
2. 位置: (0, 0, 0)
|
||
3. 确保 CesiumGeoreference 在其下
|
||
```
|
||
|
||
### 步骤 2: 设置初始相机
|
||
|
||
```
|
||
1. 在 World Outliner 中选择 Camera
|
||
2. 设置位置:
|
||
├─ X: 0
|
||
├─ Y: -2000000
|
||
└─ Z: 1000000
|
||
3. 设置旋转:
|
||
├─ Pitch: -30
|
||
└─ Yaw: 0
|
||
```
|
||
|
||
### 步骤 3: 配置数据管理器
|
||
|
||
```
|
||
选中 BP_GlobeController:
|
||
|
||
├─ API_URL: http://localhost:8000
|
||
├─ WS_URL: ws://localhost:8000/ws
|
||
├─ UpdateInterval: 30.0
|
||
├─ bAutoRotate: true
|
||
└─ RotateSpeed: 0.5
|
||
```
|
||
|
||
---
|
||
|
||
## 配置后端连接
|
||
|
||
### 步骤 1: 测试后端服务
|
||
|
||
```bash
|
||
# 在 WSL 中启动后端
|
||
cd /home/ray/dev/linkong/planet
|
||
docker restart planet_backend_new
|
||
|
||
# 测试 API
|
||
curl http://localhost:8000/api/v1/collected/summary
|
||
```
|
||
|
||
### 步骤 2: 配置 CORS (如果需要)
|
||
|
||
```
|
||
后端已配置 CORS:
|
||
├─ http://localhost:3000
|
||
├─ http://0.0.0.0:3000
|
||
└─ http://frontend:3000
|
||
```
|
||
|
||
### 步骤 3: 测试 WebSocket
|
||
|
||
```
|
||
在 UE5 蓝图中:
|
||
|
||
1. 创建 WebSocket 连接
|
||
└─ URL: ws://localhost:8000/ws
|
||
|
||
2. 发送订阅消息:
|
||
{
|
||
"action": "subscribe",
|
||
"channels": ["updates", "alarms"]
|
||
}
|
||
|
||
3. 监听消息并处理
|
||
```
|
||
|
||
---
|
||
|
||
## 测试运行
|
||
|
||
### 步骤 1: 编译蓝图
|
||
|
||
```
|
||
1. 点击工具栏 "Compile" 按钮
|
||
2. 检查错误日志
|
||
3. 修复任何错误
|
||
```
|
||
|
||
### 步骤 2: 运行测试
|
||
|
||
```
|
||
1. 点击 "Play" 按钮
|
||
2. 检查:
|
||
├─ 地球是否正常显示
|
||
├─ Cesium 地形是否加载
|
||
├─ 太阳光照是否正确
|
||
└─ 相机控制是否工作
|
||
|
||
3. 打开输出日志检查错误
|
||
```
|
||
|
||
### 步骤 3: 打包发布
|
||
|
||
```
|
||
1. File → Package Project → Windows (64-bit)
|
||
2. 选择输出目录: D:\games\Planet\Dist\
|
||
3. 等待打包完成
|
||
4. 测试打包后的可执行文件
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: Cesium 地形不显示
|
||
|
||
```
|
||
解决方案:
|
||
1. 检查 Cesium ion Token 是否正确
|
||
2. 检查网络连接
|
||
3. 确认 CesiumWorldTerrain 已启用
|
||
4. 查看输出日志错误信息
|
||
```
|
||
|
||
### Q2: 相机控制不工作
|
||
|
||
```
|
||
解决方案:
|
||
1. 确保 PlayerController 启用输入
|
||
2. 检查输入绑定是否正确
|
||
3. 确认相机组件已附加
|
||
4. 检查是否有其他 Actor 捕获输入
|
||
```
|
||
|
||
### Q3: WebSocket 连接失败
|
||
|
||
```
|
||
解决方案:
|
||
1. 检查后端服务是否运行
|
||
2. 确认 CORS 配置正确
|
||
3. 检查防火墙设置
|
||
4. 验证 URL 格式正确
|
||
```
|
||
|
||
### Q4: 性能问题
|
||
|
||
```
|
||
解决方案:
|
||
1. 降低渲染分辨率
|
||
2. 禁用不必要的特效
|
||
3. 减少粒子数量
|
||
4. 使用 LOD
|
||
5. 启用虚拟纹理
|
||
```
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
1. **添加数据点** - 创建 BP_Supercomputer 实例
|
||
2. **添加海缆** - 创建 BP_SubmarineCable 实例
|
||
3. **添加数据流** - 创建 BP_DataFlow 实例
|
||
4. **配置 UI** - 添加 W_MainHUD 等界面
|
||
5. **优化性能** - 根据实际运行调整
|