planet/unreal/Content/Levels/Scene_Setup_Guide.md

UE5 3D 大屏场景搭建完整指南

目录

1. 项目初始化
2. 安装 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: 测试后端服务

# 在 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. 优化性能 - 根据实际运行调整