unity/Docs/Production/ProjectConventions.md

# 项目文件与素材规范

本项目通过 **Unity MCP 操作 Unity 工程，通过 Blender MCP 完成 3D 制作**，首个可玩版在 **Windows PC 上用键盘与鼠标验收**。建档时工程记录的编辑器版本为 `6000.6.8f1`，示例场景 `Assets/Scenes/SampleScene.unity` 包含主相机和方向光。灰盒阶段沿用现有渲染配置。

## MCP 操作与文件交接

- Unity 场景、对象、组件、预制体、导入设置与构建通过 Unity MCP 操作，修改前回读工程路径、当前场景与目标对象。文件保存后检查层级、引用和 Console。
- C#、UXML、USS 与项目文档可通过工作区工具编辑。代码落盘后通过 Unity MCP 刷新并等待编译，再进行播放与测试。Unity 资产引用和 meta 由编辑器维护。
- Blender MCP 开始制作前读取当前文件与场景，在该资产的项目集合中工作。保存可编辑的 blend 源文件，按选定对象导出模型、骨架和必要挂点，检查尺寸和多角度预览。
- 下载工具负责从公开资源页取得免费文件与许可原文，原始文件先归档，再由 Blender MCP 修整或由 Unity MCP 导入。运行时使用的模型、声音、代码及派生文件都能沿 [素材台账](AssetSources.md) 追溯到原始条目。

## Windows 构建验收

- 首轮采用 Windows x86-64 独立构建，产物放在 `Builds/Windows/x64/`，构建场景列表应包含本次交付的入口。直接运行可执行文件，用键鼠走完当前阶段的验收场景。默认键位见 [玩法设计](../Design/GameDesign.md)。
- 驾驶试验场检查移动中精瞄、推进时切视角，以及切出窗口再返回时的鼠标捕获。恢复驾驶需重新按键才触发射击。单战区阶段追加货仓选择、发射中断和主动登机，确认菜单点击与战斗输入各自响应。
- 首轮性能目标取 **1920 × 1080、中等画质、60 FPS**。在同一台测试机预热场景后，分别采样越肩和第一人称下的代表性战斗，以第 95 百分位帧耗时不超过 16.7 毫秒为目标。记录测试机 CPU、GPU、内存、画质配置与实测结果，场景加载耗时另记。

阶段任务及对应的验收用例见 [落地开发计划](ImplementationPlan.md)。

## 新文件放在哪里

目录按实际产出的文件建立。保留现有的 Unity 场景目录和编辑器工具目录。

| 仓库相对路径 | 用途与示例 |
| --- | --- |
| `Assets/Scenes/` | 可打开或构建的场景。第一座灰盒试验场用 `MechTestRange.unity`。 |
| `Assets/Editor/` | Unity 编辑器工具，例如批量核查模型挂点。 |
| `Assets/Game/Input/` | 键鼠输入的 Input Actions 资产与配置。驾驶和界面动作统一在此维护。 |
| `Assets/Game/Scripts/` | 自研运行时代码，按玩法划分为 Mechs、Combat、Equipment、Loot、Extraction、Runs、UI、Save。脚本与主类型同名，例如 `Extraction/CargoPod.cs`。 |
| `Assets/Game/Data/` | 底盘、装备、掉落表、战区目标的可编辑配置。各机体从配置读取数值，共用运行逻辑。 |
| `Assets/Game/Prefabs/` | 可复用的机甲、场景交互物、敌人和界面预制体。外部模型的玩法组件挂在项目自己的预制体上。 |
| `Assets/Game/Art/` | Unity 使用的模型、材质、纹理、动画和特效，分别放在 Models、Materials、Textures、Animations、VFX。 |
| `Assets/Game/Audio/` | 游戏使用的自制音效与音乐，按 SFX、Music 划分。例 `SFX/SFX_Mech_Boost_Start.wav`。 |
| `Assets/Game/UI/` | 驾驶舱与越肩 HUD 的图标、字体和布局资源。第三方字体原件及许可归第三方目录管理。 |
| `Assets/Game/Localization/` | 语言定义、文本表与语言设置；代码放在 `Assets/Game/Scripts/Localization/`，派生字体放在 `Assets/Game/UI/Fonts/`。翻译保留玩法 ID 与存档内容。 |
| `Assets/ThirdParty/<作者或发行方>/<资源包>/` | 直接导入的外部模型、声音、代码和随附许可。对有固定导入路径的包沿用其要求，并在台账记实际位置。 |
| `Packages/` | 由 Unity 包管理器安装的依赖，保留 manifest 和锁定文件。 |
| `SourceAssets/Blender/` | 可编辑的 Blender 源文件，按 Mechs、Environment、Props 分组。 |
| `SourceAssets/Audio/` | 音频母带、剪辑工程和分轨。Unity 使用的导出物进 Audio 目录。 |
| `SourceAssets/ThirdParty/<作者或发行方>/<资源包>/` | 下载的原始压缩包、原始模型、原音频及随附说明。处理后的 Blender 源文件进 SourceAssets/Blender，Unity 导入物进 Assets/ThirdParty 对应包目录。 |
| `Tools/Blender/` | 在 Blender MCP 中使用的可复用导出、尺寸或挂点校验脚本。 |
| `Docs/Design/`、`Docs/Production/` | 玩法方案、制作约定和素材记录。外部许可原文可归档在 `Docs/Production/Licenses/<作者或发行方>/<资源包>/`。 |
| `Docs/QA/` | 随实际构建建立的操作验收、问题复现与性能记录。 |

## 一台机甲的文件流向

Blender MCP 保存建模源文件 `SourceAssets/Blender/Mechs/Mech_Scout_A.blend`，导出到 `Assets/Game/Art/Models/Mechs/Mech_Scout_A.fbx`。Unity MCP 导入后，将驾驶组件组装为 `Assets/Game/Prefabs/Mechs/Mech_Scout_A.prefab`。调整基础操控数值时改底盘配置，换美术模型时复用已有机体行为。

- 模型以米为尺度，导出前检查原点与变换。在 Unity 试验场核对大小、前进方向、碰撞体、武器挂点和驾驶舱视点。用同一个掩体检查越肩遮挡和第一人称舱框。
- 新脚本按 C# 类型名命名。资产名包含对象与用途，例如 `Mech_Scout_A`、`SFX_Mech_Boost_Start`。外部资产保留包内结构，项目侧的修改放在自己的预制体、材质变体或适配代码中。
- 通过 Unity MCP 在编辑器中移动或重命名已导入资产，并回读引用。采用版本控制时，把资产与对应的 `.meta` 一起提交，同时保留 `ProjectSettings/`、包清单和锁定文件。本地生成的 Library、Temp、Logs、UserSettings 与构建产物由各自环境管理。
- 源文件、导出模型、配置和预制体共用可追溯的资产编号。模型根节点、武器挂点和驾驶舱视点使用稳定名称，导出后重新导入时核对现有预制体引用。

## 使用公开免费素材

按具体条目的许可选择模型、音效和代码。下载时记下作者、原始条目链接、版本或下载日期、许可及署名文字，保存实际使用的许可说明。原始文件记录 SHA-256，导入后登记本地路径以及做过的裁剪、重拓扑、转码或代码修改，发布时从记录生成署名名单。

使用顺序为「查条目和许可 → 下载并归档原件 → Blender MCP 修整或音频处理 → Unity MCP 导入 → 挂接预制体和配置 → 场景验证 → 台账记录实际结果」。免费资源的检索入口和逐项记录统一放在 [素材来源与导入台账](AssetSources.md)。UPM 依赖的版本由 `Packages/manifest.json` 和 `Packages/packages-lock.json` 锁定，外部代码同时保留对应许可。

代码与模型的试改采用项目目录中的适配组件、材质或预制体变体。素材替换时先在一个已验证场景回读导入结果，确认脚本组件、碰撞体、相机和武器挂点，再扩展到其他场景。