# 啊啊会展展厅 · Unreal 导入与碰撞交付说明

本包提供可编辑的 glTF / GLB 三维资产、独立碰撞代理、原平面拓扑数据和 Unreal Editor 导入脚本。网页的参观程序在 Three.js 中运行；GLB 不包含网页的 JavaScript 交互逻辑，也不是已经打包的 Unreal 游戏。

交付机器在标准 Epic Games 安装目录与 Unreal 注册表项中未检测到 Unreal Engine。这里的导入方式按 Epic 官方文档核对，Python 脚本仅完成语法检查；尚未在 Unreal Editor 中执行，也未完成 PIE、Lumen 或打包验收。

## 文件用途

| 文件 | 用途 |
| --- | --- |
| `models/aa-showroom.glb` | 完整视觉场景，保留节点层级、材质贴图与场景变换。 |
| `models/aa-collision.glb` | 独立碰撞代理。各形状独立命名，节点以 `COL_` 加碰撞 ID 命名。 |
| `models/aa-showroom.collisions.json` | 对应碰撞 ID、类型与参数，供程序重建和核对。 |
| `models/` 内的分类 GLB | 按资产类别单独编辑与替换，名称以交付目录实际文件为准。 |
| `layout.js` | 实墙轮廓、8 个点位、尺寸轴线、入口出口与导览骨架。 |
| `unreal/import_showroom.py` | 将视觉/碰撞场景导入 `/Game/AAExpo`，设置静态碰撞代理并生成执行报告。 |

源场景按米建模，Three.js 的 Y 为高度，X/Z 为平面坐标。Unreal 使用厘米和 Z 向上坐标；glTF 导入流程承担坐标与单位转换。脚本不会再乘 100 或再手工旋转全场。导入后以尺寸验收，避免重复缩放。[Epic 坐标与单位说明](https://dev.epicgames.com/documentation/unreal-engine/migrating-assets-from-unity-to-unreal-engine)、[Epic glTF 米到厘米的导入换算说明](https://dev.epicgames.com/documentation/unreal-engine/datasmith-import-options-in-unreal-engine)

## 导入步骤

1. 在 Unreal Editor 中建立项目并打开空关卡。启用 **Python Editor Script Plugin**、**Interchange** 及 glTF 导入能力，按编辑器提示重启。
2. 保持 `unreal/`、`models/` 与本说明位于同一交付目录下。脚本通过自己的位置读取 `../models/`。
3. 在项目的 Interchange 设置中保留 **Import Into Level** 场景管线；保留层级与源节点变换，不合并全部网格，不额外覆盖导入缩放。
4. 使用编辑器的 **Execute Python Script** 执行 `unreal/import_showroom.py`。脚本将完整场景与代理场景导入当前关卡，资产分别进入 `/Game/AAExpo/Visuals` 和 `/Game/AAExpo/Collision`。
5. 保存当前关卡为新的展厅关卡。查看项目 `Saved/AAExpo_import_report.json`；报告生成只表示导入/设置完成，不能代替游览验收。

脚本使用 `InterchangeManager.import_scene`，使节点变换进入关卡。单纯把 GLB 拖入 Content Browser 主要是导入资产，不应再把全部零件随意放到同一位置。已有 `/Game/AAExpo` 资产时脚本会停止，避免覆盖；重复试验可使用新项目或修改脚本的 `DESTINATION` 为新目录。[Epic Interchange 场景导入说明](https://dev.epicgames.com/documentation/en-us/unreal-engine/importing-assets-using-interchange-in-unreal-engine)、[InterchangeManager API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/InterchangeManager?application_version=5.6)、[ImportAssetParameters API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/ImportAssetParameters?application_version=5.6)

## 碰撞采用哪一种方式

本脚本使用**独立低细节代理的静态逐三角形碰撞**，即 `CTF_USE_COMPLEX_AS_SIMPLE`；没有自动生成把整个房间包住的凸包。中部连续实墙的凹口、圆厅左下通道、南侧入口与东南出口仍来自代理的真实网格轮廓。艺术环灯的分段代理保留中空部分。

视觉模型的碰撞设为 `NoCollision`。代理组件设为 `BlockAll`、静态、关闭 `Simulate Physics`，同时隐藏其渲染与投影；关闭可见性不等于关闭碰撞。该模式用于固定建筑和固定设备，官方明确复杂碰撞作为简单碰撞只适合静态形状，不应用于受力运动的代理刚体。[CollisionTraceFlag API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/CollisionTraceFlag?application_version=5.6)、[PrimitiveComponent 碰撞设置 API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/PrimitiveComponent?application_version=5.6)

脚本通过 `StaticMesh.body_setup` 设置碰撞复杂度，并开启代理 LOD 0 各 Section 的碰撞；如导入器未创建 BodySetup，先用编辑器接口初始化，再立即移除临时简单盒体。此后保存静态网格。[StaticMesh API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/StaticMesh?application_version=5.6)、[BodySetupCore API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/BodySetupCore?application_version=5.6)、[StaticMeshEditorSubsystem API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/class/StaticMeshEditorSubsystem?application_version=5.6)

如后续要让设备搬动、翻倒或参与物理模拟，应为该设备建立多个简单凸体并独立验收。自动凸分解的官方接口是 `set_convex_decomposition_collisions(mesh, hull_count, max_hull_verts, hull_precision)`；它会替换既有简单碰撞，凹形建筑不能未经检查直接套用。[Epic 静态网格碰撞文档](https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-collisions-with-static-meshes-in-blueprints-and-python-in-unreal-engine)

## 尺寸、命名和材质验收

| 项目 | 目标 |
| --- | --- |
| 平面结构轴线 | 30.810 × 13.805 m，即 3081 × 1380.5 cm。实体外皮因墙厚略超出结构轴线。 |
| 墙体高度 | 4.2 m / 420 cm，为设计假设，平面图没有实测层高。 |
| 南侧入口 | 约 4.195 m / 419.5 cm。 |
| 东南出口 | 约 3.595 m / 359.5 cm。 |
| 实墙关系 | 灰色连续区域为实体墙；黑色结构位包合于墙中，没有新增独立柱。 |
| 碰撞对应 | `COL_<id>` 对应 JSON 内的碰撞 ID；引擎若规范化名称，以执行报告和源 JSON 对照。 |
| 材质 | 暖象牙、深橄榄、石材、香槟金属与暖光；文字纹理应清晰，屏幕与玻璃单独检查。 |

GLB 材质与 Three.js 的渲染结果会受引擎灯光、色调映射和透明材质设置影响。导入后需核对玻璃透明度、贴图颜色空间、屏幕自发光与灯具发光；浏览器光晕、后期效果和网页互动不会自动变成 Unreal 后期或蓝图。

## 沉浸式游览验收

在关卡中配置 Character / Pawn、相机与输入后，在 PIE 中检查：进入南侧入口；由序厅左下开口到历程区；从西侧通道绕过横向实墙到产业区；经文化区北侧通道到党建区；绕实墙东端到实验室与未来区；从东南出口离开。源编号保留已有效果图对应关系，实际原图顺序是 **P01 → P02 → P04 → P03 → P05 → P06 → P07 → P08**。

还需检查沿墙滑动、圆弧接缝、展柜边角、控制台、沙盘和艺术灯代理是否与可见模型吻合。互动设备的开关、沙盘图层、UI 和导览应在 Unreal 蓝图中按源程序逻辑实现；本导入脚本仅负责资产及静态碰撞配置。