Unity2Godot_迁移标准模板.md

Unity → Godot 迁移标准模板（可复用）

1. 文档目的

本模板用于指导任意 Unity 库迁移到 Godot 的标准流程，确保迁移工作可复用、可验收、可追踪。

适用场景：

• 需要将 Unity 包（Package/Runtime 模块）迁移到 Godot
• 需要统一跨库迁移标准，便于团队协作与审计
• 需要输出结构化迁移报告用于验收

---

2. 迁移范围定义（先定边界）

2.1 输入信息（必填）

• 源库路径（Unity）：
  • {{UNITY_SOURCE_PATH}}
• 目标库路径（Godot）：
  • {{GODOT_TARGET_PATH}}
• 迁移目标模块：
  • {{TARGET_MODULES}}（例如：Runtime）

2.2 范围约束规则（标准）

• 先做“目录边界”声明，再开始迁移。
• 非目标模块不参与本轮迁移，不作为阻塞项。
• 若排除模块影响构建，必须通过工程配置显式排除其编译输入。

---

3. 核心迁移原则

1. 先编译通过，再行为对齐
   先建立可编译基线，再逐步补齐功能一致性。

2. 先 Runtime，后 Editor
   Editor 存在引擎强耦合差异，默认单独立项。

3. 最小改动原则
   保持原有模块边界与命名风格，避免无关重构。

4. 映射优先原则
   对 Unity API 做 Godot 等价映射；无等价能力先给占位方案并记录。

5. 每步可验证原则
   每个子模块变更后立即构建验证，防止回归扩散。

---

4. 标准迁移流程（SOP）

阶段 0：建立基线

• 确认迁移范围与排除范围
• 配置工程编译边界（例如排除 Editor/**/*.cs）
• 执行首次构建，记录初始错误基线

输出：

• 《构建基线记录》

阶段 1：文件级覆盖对齐

• 统计源/目标 .cs 文件总数
• 输出仅源存在文件（未迁移清单）
• 输出仅目标存在文件（新增清单）

输出：

• 《文件覆盖清单》

阶段 2：类与函数签名对齐

• 对同名文件进行类声明对比
• 对同名文件进行函数签名对比
• 标记“符合预期差异”与“风险差异”

输出：

• 《类函数差异清单》

阶段 3：语义与能力对齐

• 生命周期映射对齐（如 Awake → _Ready）
• 类型映射对齐（如 GameObject → Node）
• 平台能力缺口补齐或明确替代实现

输出：

• 《能力映射与缺口清单》

阶段 4：回归与验收

• 全量构建通过（0 error）
• 关键功能路径验证通过
• 输出最终迁移评估结论

输出：

• 《迁移验收报告》

---

5. 统一映射规则（模板）

5.1 生命周期映射

• Unity Awake → Godot _Ready
• Unity Update → Godot _Process
• Unity OnDestroy/OnApplicationQuit → Godot _Notification（按通知类型分流）

5.2 核心对象映射

• GameObject → Node
• Transform → Node / Node3D（按业务选择）
• Rect → Rect2
• UnityEngine.Object → GodotObject

5.3 路径与平台映射

• Application.persistentDataPath → ProjectSettings.GlobalizePath("user://")
• Application.streamingAssetsPath → res://streaming_assets/ + 平台适配
• 平台判断优先使用 Godot OS / RuntimeInformation

5.4 禁止项（强约束）

• 未声明即迁移 Editor 模块
• 在 Runtime 保留不可达但未标注的 Unity API 代码
• 没有构建验证就给出“迁移完成”结论

---

6. 差异分类标准

A 类：符合预期差异（可接受）

• 生命周期函数名变化（由引擎机制导致）
• 类型名变化但语义一致（如 GameObject → Node）
• 平台路径 API 替换（Unity → Godot）

B 类：需处理差异（阻塞）

• 同名核心函数缺失且无替代实现
• 公共类缺失导致上层调用中断
• Runtime 仍存在可执行路径中的 Unity API 依赖

C 类：技术债差异（非阻塞但需记录）

• 未激活宏分支中的 Unity 遗留代码
• 可替代但尚未优化的实现

---

7. 验收标准（DoD）

必须同时满足：

1. 目标范围内文件迁移完成并有差异说明
2. 目标工程构建通过（0 error）
3. 核心功能路径可运行
4. 所有 B 类差异闭环（修复或有明确替代方案）
5. 输出完整迁移报告并可复查

---

8. 迁移报告标准结构（交付模板）

建议报告标题：

• {{LIB_NAME}}_Runtime_迁移对比报告.md

建议章节：

1. 对比范围
2. 总体统计（文件数、覆盖率、差异率）
3. 未迁移文件清单
4. 类与函数差异清单
5. 符合预期项
6. 不符合预期项
7. 风险与建议
8. 结论（是否达到预期）

---

9. 执行检查清单（可直接复制）

开始前

• 范围已确认（含排除模块）
• 构建命令已确认
• 验收标准已确认

迁移中

• 每个模块改动后都构建验证
• 差异都已分类（A/B/C）
• 缺口都有处理策略

结束前

• 0 error 构建通过
• 迁移报告已输出
• 结论已给出“符合 / 部分符合 / 不符合”

---

10. 结论口径模板（可复用）

10.1 符合预期

该库在本轮迁移范围内已完成核心能力迁移，构建通过，关键路径可运行，结论为“符合预期”。

10.2 部分符合预期

该库已完成主体迁移并可构建，但仍存在功能缺口（见 B 类差异清单），结论为“部分符合预期”，建议按优先级补齐。

10.3 不符合预期

该库当前仍存在阻塞型差异或构建错误，尚不满足验收标准，结论为“不符合预期”。