XCEngine/docs/used/Nahida Unity工程迁移与卡通角色渲染落地计划_完成归档_2026-04-11.md

# Nahida Unity工程静态卡通渲染迁移计划
日期: 2026-04-10
状态: 已按“仅静态卡通渲染”范围重写

## 1. 范围锁定

这份计划只服务一个目标：

- 把 Nahida 的静态卡通渲染效果迁到 XCEngine。

本轮明确不做：

- 骨骼动画
- 运行时 skinning
- `SkinnedMeshRenderer` 运行链路
- blend shape 驱动
- Animator / Humanoid / Retargeting
- Unity 动画系统还原

如果后面发现 Unity 原样例里某些视觉细节依赖骨骼或 blend shape，本轮处理原则是：

- 先接受静态近似
- 不为此把范围扩成动画系统

## 2. 当前目标

本轮要落地的是一套“静态可渲染”的 Nahida 角色效果，重点是：

- body / hair / face / brow / dress 的分材质关系
- toon 明暗分层
- face shadow 基本成立
- outline 基本成立
- 在独立预览场景里稳定对比和调试

换句话说，本轮不是“把 Unity 角色系统搬过来”，而是：

- 先把 Nahida 的静态画面效果在你自己的引擎里立住

## 3. 已知事实

### 3.1 资源基线已经整理

当前已经完成的 Phase 0 资源整备：

- 引擎项目内静态资源基线：
  - `project/Assets/Characters/Nahida/`
- Unity 原始参考快照：
  - `docs/reference/NahidaUnity/`

已落地的关键资源包括：

- Nahida 的 `FBX`
- body / hair / face / shared 贴图集
- `Nahida_Body_Smooth.mesh`
- Unity 材质、shader、scene、脚本参考文件

### 3.2 当前运行时能力

当前引擎已经具备：

- `MeshFilterComponent + MeshRendererComponent` 静态网格渲染路径
- `MeshRendererComponent` 的多材质槽能力
- `Material` / `Shader` 资源导入体系

当前引擎没有现成闭环：

- skinning
- skeleton runtime
- blend shape runtime

所以当前正确路线不是补动画，而是：

- 先基于现有静态渲染路径做 Nahida 的静态效果落地

### 3.3 Nahida 的 Unity 语义里哪些需要保留

从 Unity 原工程看，本轮静态渲染仍然必须保留这些语义：

- 7 份材质的分工关系
- `_LightMap` 驱动的 toon 阴影分层
- `_FaceLightMap + _FaceShadow + _FaceDirection` 的面部阴影语义
- `_MetalMap`、rim、outline 的材质逻辑
- `Nahida_Body_Smooth.mesh` 对描边效果的贡献

### 3.4 哪些 Unity 语义本轮只记录、不实现

本轮只作为参考保留，不进入当前执行范围：

- `SkinnedMeshRenderer`
- blend shape 默认值
- 头骨驱动的面部朝向更新
- 完整 URP 后处理还原

## 4. 迁移原则

### 4.1 先静态成立，再谈角色系统

当前第一优先级是：

- 让 Nahida 在静态场景里正确显示

不是：

- 先做角色运行时架构大一统

### 4.2 先复用现有静态网格路径

只要当前导入出来的 Nahida mesh / section / material slot 足够支撑静态装配，就优先用现有：

- `MeshFilterComponent`
- `MeshRendererComponent`

不额外引入：

- `ModelComponent`
- `SkinnedMeshRendererComponent`

### 4.3 Unity 文件继续只做参考

`docs/reference/NahidaUnity/` 里的 `.mat`、`.shader`、`.unity` 继续只作为语义来源。

最终落地仍然必须是：

- 引擎自己的 `Shader`
- 引擎自己的 `Material`
- 引擎自己的 `Scene`

### 4.4 面部朝向先做静态近似

本轮不做基于头骨的 `_FaceDirection` 驱动。

优先级改为：

- 先给面部材质写一个可接受的静态 `_FaceDirection`
- 如果后面确实需要，再加一个基于对象整体朝向的简化驱动

不进入本轮的：

- 基于 head bone 的动态朝向更新

## 5. 分阶段方案

### Phase 0: 资源整备

状态：

- 已完成

已完成内容：

- 建立 `project/Assets/Characters/Nahida/` 资源树
- 补齐缺失贴图
- 补齐 `Nahida_Body_Smooth.mesh`
- 建立 `docs/reference/NahidaUnity/` 参考区
- 写出资源说明与依赖映射

### Phase 1: 静态装配基线

目标：

- 确认当前 Nahida 的 FBX 导入产物能否直接支撑静态场景装配
- 建立一个专门用于调试 Nahida 的静态预览场景

任务：

- 盘点 Nahida 当前导入出来的 mesh / submesh / material slot
- 确认应该使用哪些 meshRef 来组装静态角色
- 创建 `NahidaPreview.xc`
- 在场景中放入 Nahida 的静态实例
- 先用占位或默认材质把所有 slot 挂齐

验收：

- Nahida 能在独立场景中稳定显示
- mesh slot 拆分关系清楚
- 预览场景不依赖主场景的历史脏数据

### Phase 2: Toon Shader移植

目标：

- 在 XCEngine 里建立 Nahida 用的引擎原生 toon shader

任务：

- 新建 Nahida toon shader
- 先移植最关键的静态视觉能力：
  - base map
  - base color
  - `_LightMap`
  - `_FaceLightMap`
  - `_FaceShadow`
  - `_MetalMap`
  - rim
  - outline
- 不依赖 Unity URP include

验收：

- body / hair / face / dress 的 toon 分层开始成立
- 面部和头发不再是默认 PBR 外观

### Phase 3: 引擎原生材质落地

目标：

- 建立 Nahida 的引擎原生材质资产

任务：

- 建立：
  - `Nahida_Base.material`
  - `Nahida_Body.material`
  - `Nahida_Hair.material`
  - `Nahida_Face.material`
  - `Nahida_Brow.material`
  - `Nahida_Dress1.material`
  - `Nahida_Dress2.material`
- 按依赖图绑定贴图和参数
- 把材质正式挂到静态预览场景

验收：

- 7 份材质语义清楚
- 各 slot 的贴图和参数不串位
- 删除 Unity 参考 `.mat` 后不影响引擎内显示

### Phase 4: 描边与面部阴影补全

目标：

- 把最关键的卡通识别特征补完整

任务：

- 接入 `Nahida_Body_Smooth.mesh` 或等价静态描边路径
- 补全 outline 参数
- 给 face 材质写静态 `_FaceDirection`
- 如确有必要，增加基于角色整体朝向的简化 `_FaceDirection` 驱动

验收：

- outline 视觉成立
- face shadow 不明显错误
- 不引入骨骼依赖

### Phase 5: 预览场景与视觉调优

目标：

- 做一个可稳定对照 Unity 的静态 Nahida 预览场景

任务：

- 固定相机
- 固定主光
- 简化背景
- 对 body / hair / face / outline 做迭代调参
- 如确有必要，再补最小后处理

验收：

- 可以稳定截图对比
- 能快速判断问题属于材质、shader、描边还是灯光

## 6. 风险点

### 6.1 静态路线与 Unity 原样不会完全一致

因为本轮不做：

- skinning
- blend shape
- head bone 驱动

所以最终效果可以接近，但不保证和 Unity 样例逐像素一致。

### 6.2 描边依赖特殊 mesh

如果忽略 `Nahida_Body_Smooth.mesh`，outline 很可能明显跑偏。

### 6.3 Face shadow 不是纯贴图问题

即使不做骨骼，`_FaceDirection` 也至少要给一个合理静态值，否则面部阴影会别扭。

### 6.4 不应该一上来做后处理

如果在 shader、材质、outline 还没立住前就先做 bloom / tonemap，会把问题源混在一起。

## 7. 验收标准

### 档位A：静态资源正确

- `project/Assets/Characters/Nahida/` 资源完整
- `docs/reference/NahidaUnity/` 参考区完整
- 预览场景可稳定打开

### 档位B：静态角色正确

- Nahida 静态显示成立
- body / hair / face / brow / dress 分材质正确
- toon 阴影、outline、face shadow 基本成立

### 档位C：视觉接近样例

- 角色整体风格接近 Unity 样例
- 关键差异只剩高级细节，而不是基础渲染错误

## 8. 推荐执行顺序

1. 先确认 Nahida 当前导入产物的静态装配方式
2. 再做引擎原生 toon shader
3. 再做 7 份引擎原生材质
4. 再补 outline 和 face shadow
5. 最后做预览场景调优与可选后处理

明确不要做成：

1. 先补 skinning
2. 先补动画系统
3. 先补骨骼驱动组件

这不在当前范围内。

## 9. 下一步

基于当前状态，下一步不是继续做计划，也不是做骨骼运行时，而是：

1. 先确认 Nahida 当前导入出来的静态 mesh / section / material slot 布局是否足够支撑静态装配。
2. 如果足够，直接开始建立 `NahidaPreview.xc`、引擎原生 toon shader、以及 Nahida 的材质壳子。

当前代码现状对这个判断是偏乐观的：

- 现有渲染路径已经支持 `MeshFilter + MeshRenderer`
- `MeshRendererComponent` 已经支持多材质槽
- Nahida 当前导入产物里已经存在大量静态 mesh 子资源

所以最合理的下一执行切口是：

- 直接进入“静态预览场景 + toon shader + native materials”这一段

而不是去碰动画系统。