（本文为《Unity VFX 提效工具源码拆解》系列第 9 篇，承接第 8 篇的 P4、备注解析与反射桥。本篇将这些输入汇合为场景建档、骨骼挂载、Timeline 绑定与性别变体迁移，梳理全系列最终的数据闭环。）
一、自动装配真正需要的是资源之间的关系
同一份交付可能包含目录、角色、动作与挂点
特效任务交到制作端时，策划通常给出业务 ID，模型团队提供道具和角色，动作团队提供动画及绑定说明。新人必须回答：文件放到哪个目录，生成哪些 Scene，使用男角色还是女角色，道具挂到哪根骨骼，哪段动画交给哪个 Animator。
这些问题里，视觉与节奏仍需要专业判断，但目录、命名、配对和挂点有相对稳定的项目协议。VFXStandardizerView 把 ID 转成预期目录、后缀与交付清单；VFXContentPopulator 把场景上下文、已导入资源和备注条目转成实际对象及轨道。两层分开，才能判断错误来自规则推导还是装配执行。
先认识四种中间数据
SuffixItem 保存场景后缀和用途说明；ParsedVFXConfig.noteItems 保存备注解析出的模型、动画与绑定；spawnedMales/spawnedFemales 保存本轮已生成角色；handledModels 保存本次已经处理的模型名。前三种向后续方法提供输入，最后一种用于调用内去重。
下文代码均为实际源文件的关键节选。ID 含义、路径和骨骼名称来自当前项目约定，不能直接当成 Unity 内置业务规则迁移到其他工程。
二、ID 如何变成目录与场景文件
前四位前缀决定资源根目录
GetExpectedRootFolder 接收目标 ID 和年份，返回 Unity 资产根路径；它不查找模型，也不创建场景。
csharp
// GetExpectedRootFolder ID目录映射：以下保留实际处理语句，外围上下文见正文。
public static string GetExpectedRootFolder(string targetID, int targetYear)
{
if (string.IsNullOrEmpty(targetID) || targetID.Length < 4) return "Assets/resources/media/shaders/item_effect";
string prefix = targetID.Substring(0, 4);
switch (prefix)
{
case "2080": case "2084": case "2086": case "2045": case "2065":
return "Assets/resources/media/shaders/item_effect";
case "5112":
return "Assets/resources/media/shaders/Fitments/5112";
case "8040": case "1096": case "1196":
return $"Assets/resources/media/shaders/role/cloth_eff_{targetYear}";
case "4010":
return "Assets/resources/media/shaders/role/link";
case "4011": case "4111":
return targetID.Length >= 8 ? $"Assets/resources/media/shaders/role/link_new/link_{targetYear}" : "Assets/resources/media/shaders/role/link";
default:
return "Assets/resources/media/shaders/item_effect";
}
}Substring(0, 4) 取得品类前缀，switch 把它映射到物品、座驾、角色外观或连线等目录。部分目录使用年份，部分还检查 ID 长度。输入不足或未知前缀回退到物品目录，因此"返回非空路径"不代表 ID 已通过完整业务校验。
UpdateSuffixesBasedOnID 继续根据品类推导 sceneSuffixes，让后面的创建循环只消费后缀列表。这样目录规则与场景创建 API 不必写在同一个循环里，维护品类时也更容易定位修改点。
建档创建缺失 Scene，特定分支才自动装配
GenerateStandardPipeline 先检查目标 ID 与当前场景，再建立目标目录。下面节选从后缀列表构造文件路径，并展示当前真正接入的自动装配条件。
csharp
// GenerateStandardPipeline Scene建档与hand分支：以下保留实际处理语句，外围上下文见正文。
foreach (var item in sceneSuffixes)
{
string suffixPart = string.IsNullOrEmpty(item.suffix) ? "" : $"_{item.suffix}";
string scenePath = $"{targetDir}/{targetID}{suffixPart}.unity";
if (!File.Exists(scenePath))
{
var newScene = EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Additive);
EditorSceneManager.SaveScene(newScene, scenePath);
bool is2065Hand = targetID.StartsWith("2065") && item.suffix.Equals("hand", System.StringComparison.OrdinalIgnoreCase);
if (is2065Hand && newScene.IsValid())
{
EditorSceneManager.SetActiveScene(newScene);
VFXContentPopulator.PopulateScene(newScene);
EditorSceneManager.MarkSceneDirty(newScene);
EditorSceneManager.SaveScene(newScene);
assembledHandCount++;
}
EditorSceneManager.CloseScene(newScene, true);
createCount++;
}suffixPart 控制文件名是否追加下划线，File.Exists 避免重复创建已存在 Scene。NewScene(..., Additive) 创建临时场景，SaveScene 写出文件。只有新建的 2065 品类且后缀为 hand 时，循环才切换活动场景并调用 PopulateScene，随后再次保存。
这是代码中的明确分支：一般建档不等于自动填充全部场景，已存在的 hand Scene 也不会在这个条件下重新装配。源代码弹窗把未保存活动场景称为"引擎底层限制"，实际执行语句体现的是本工具的入口前置检查，不应将提示文字提升为 Unity 的普遍规则。
填写 ID 后生成预设 Scene，面板依据品类规则列出预计交付文件，目录中出现缺失场景。清单反映命名与后缀推导，文件创建反映建档执行；只有满足特定条件的分支还会继续装配，检查时应把三类结果分别核对。
三、常规装配如何汇合场景、备注与角色
场景名称提供业务入口，活动场景必须先有路径
PopulateScene(Scene targetScene) 从 targetScene.name 按下划线拆出 ID，从场景路径取得目录，再调用目录规则方法定位资源范围。尚未保存或无效 Scene 会停止执行。这条入口已经在第 1 篇给出起始代码，本篇继续追踪其后传递的数据。
常规分支创建或取得场景与 Timeline 根节点，为导演创建新的 TimelineAsset，随后取得备注配置与角色数量。
csharp
// 创建Timeline与装配上下文：以下保留实际处理语句，外围上下文见正文。
PlayableDirector director = timelineRoot.GetComponent<PlayableDirector>();
if (director == null) director = Undo.AddComponent<PlayableDirector>(timelineRoot);
string timelinePath = GenerateUniqueTimelinePath(sceneDir, sceneName);
TimelineAsset timelineAsset = ScriptableObject.CreateInstance<TimelineAsset>();
AssetDatabase.CreateAsset(timelineAsset, timelinePath);
director.playableAsset = timelineAsset;
GroupTrack sceneGroup = GetOrCreateSceneGroup(timelineAsset);
VFXMaxConfigParser.ParsedVFXConfig config = LoadConfigForTarget(targetID, localEffectFolder);
int maleCount = 0, femaleCount = 0;
ParseRoleGenderFromSceneName(sceneName, targetID, out maleCount, out femaleCount);timelinePath 是输出文件路径，timelineAsset 是新时间轴对象，director 是场景中的执行组件。创建资产后赋给 director.playableAsset，二者才产生关联。config 来自第 8 篇的文本查找与解析；maleCount/femaleCount 则来自场景命名规则。
GenerateUniqueTimelinePath 会创建新可用路径，因此重复装配常规场景可能产生额外时间轴，而不是原地幂等更新。根节点复用或模型去重并不能单独保证整条流程重复执行无副作用。
角色列表、去重集合和时间轴一起传给后续方法
PopulateRoles 生成角色并返回男、女对象列表。handledModels 使用忽略大小写的 HashSet<string>，使同一轮中通过多个途径找到的模型尽量只处理一次。它的生命周期限定在本次调用，下一次按钮执行会重新创建集合。
常规装配在已有角色和时间轴的基础上，决定使用备注还是命名扫描。
csharp
// 备注与命名扫描分流：以下保留实际处理语句，外围上下文见正文。
if (config != null && config.noteItems.Count > 0)
{
PopulateFromMaxNoteConfig(config, sceneName, targetID, localEffectFolder, envRoot.transform, spawnedMales, spawnedFemales, timelineAsset, director, handledModels, hasChildCamera);
}
else
{
PopulateWithoutConfigAutoScan(targetID, sceneName, localEffectFolder, envRoot.transform, spawnedMales, spawnedFemales, timelineAsset, director, handledModels, hasChildCamera);
}config.noteItems.Count > 0 才进入 PopulateFromMaxNoteConfig。它同时获得场景名、ID、资源目录、场景根 Transform、男女角色列表、时间轴、导演和去重集合，因此能够把备注中的动作关联到本轮实际生成的对象；没有条目时进入 PopulateWithoutConfigAutoScan。
这解释了长参数列表的来源：它在显式传递同一次装配上下文。进一步可封装为上下文对象降低参数数量，但当前代码还使用这些独立参数，不能将未实现的架构重构写成既有能力。
骨骼挂载与动画轨道是两个关联动作
挂载先根据备注或项目规则取得目标 Transform，再将模型实例设为其孩子，设置约定的局部位置与旋转。动画还需要绑定到目标 Animator，否则文件存在也不会由 Timeline 驱动。
BindToTimeline 接收目标对象与选出的动画片段，先检查 Animator，再创建轨道并写导演绑定。
csharp
private static void BindToTimeline(TimelineAsset timeline, PlayableDirector director, GameObject targetObj, string trackName, AnimationClip clipToPlay, GroupTrack parentGroup = null)
{
if (targetObj == null) return;
Animator animator = targetObj.GetComponent<Animator>();
if (animator == null) return;
var existingTrack = timeline.GetOutputTracks().FirstOrDefault(t => t.name == trackName) as AnimationTrack;
if (existingTrack != null)
{
timeline.DeleteTrack(existingTrack);
}
// 如果传入了指定的 Group，则使用该 Group，否则回退到默认的 "场景" Group
GroupTrack sceneGroup = parentGroup != null ? parentGroup : GetOrCreateSceneGroup(timeline);
var newTrack = timeline.CreateTrack<AnimationTrack>(sceneGroup, trackName);
newTrack.matchTargetFields = (MatchTargetFields)0;
EditorUtility.SetDirty(timeline);
director.SetGenericBinding(newTrack, animator);
if (clipToPlay != null)
{
var timelineClip = newTrack.CreateClip(clipToPlay);
timelineClip.start = 0;
timelineClip.duration = clipToPlay.length;
timelineClip.displayName = clipToPlay.name;
var animAsset = timelineClip.asset as AnimationPlayableAsset;
if (animAsset != null)
{
animAsset.removeStartOffset = false;
}
}
}targetObj.GetComponent<Animator>() 只检查对象自身；没有组件便返回。代码先从 GetOutputTracks 取首条同名轨道，再尝试转为 AnimationTrack；只有转换成功才删除它，随后创建目标组下的新动画轨道。若首条同名轨道是其他类型，即使后面还有同名动画轨道，也不会继续查找，因此这里不能视为可靠的全局去重。
SetGenericBinding(newTrack, animator) 把轨道键映射到组件，CreateClip 把动画资产放进轨道，随后设置起点、时长和显示名。matchTargetFields = 0 与 removeStartOffset = false 影响片段偏移匹配，目的是按当前装配约定保留动画数据；它们并不自动修正所有根运动或骨骼坐标差异。导演绑定的架构原理见第 4 篇。
四、座驾分支为什么要单独组织层级
实际入口先处理 5112，再离开常规分支
PopulateScene 前段遇到 5112 会调用 Populate5112CompleteFlow，保存资产、标记场景并提前返回。后文虽然还保留调用 Populate5112Scene 的条件分支，但对同一前缀已经不可达。解释执行行为时必须沿真实控制流，而不是把所有同名前缀方法都串成一次调用。
完整座驾流程先定位核心模型，再在它下面找 Bone_z 和 Bone_f，分别作为角色挂点。下面节选展示男性角色如何进入载具层级。
csharp
// 2. 生成角色
Transform boneZ = FindDeepChild(coreObj.transform, "Bone_z");
Transform boneF = FindDeepChild(coreObj.transform, "Bone_f");
GameObject man = null, woman = null;
if (boneZ != null)
{
man = VFXReflectionBridge.SpawnRoleFromBodypartWindow(false);
if (man != null)
{
man.transform.SetParent(boneZ);
man.transform.localPosition = Vector3.zero;
man.transform.localEulerAngles = new Vector3(90f, 0f, 0f);
Undo.RegisterCreatedObjectUndo(man, "Create Man");
if (!man.GetComponent<Animator>()) Undo.AddComponent<Animator>(man);
}
}FindDeepChild 是项目的递归查找方法，SpawnRoleFromBodypartWindow 是反射桥包装；SetParent、局部变换和 Undo 来自 Unity。核心模型给出挂点位置，反射桥提供角色对象，二者通过 Transform 建立父子关系，而不是依靠屏幕位置对齐。
双人条件下才处理女性挂点。随后根据配置模式读取备注或手动骨骼名，为道具建立关联，并创建展示与前进等状态对应的时间轴。VFX_ConfigMode 的手动/配置切换在这条 5112 完整流程中被读取，不能推断常规品类也使用同一模式选择；常规装配仍会自行查找备注。
在符合命名规则的已保存 Scene 中，从 Hierarchy 执行"一键装配当前场景"，工具由场景 ID 选择具体业务分支。座驾场景围绕核心模型和指定骨骼组织角色与道具，常规场景则沿角色列表和备注条目装配；同一个入口并不意味着所有品类生成完全相同的层级。
五、对戒手部装配：性别、配对 ID 与骨骼联合定位
偶数 ID 可回退到配对男性资源目录
Populate2065HandScene 接收已有角色列表、时间轴与导演。它依据 ID 最后一位判断性别；女性资源检索还会补充配对男性目录。
csharp
// 2065性别配对与目录回退：以下保留实际处理语句，外围上下文见正文。
bool isFemale = false;
if (targetID.Length > 0)
{
char lastChar = targetID[targetID.Length - 1];
if (char.IsDigit(lastChar)) isFemale = ((lastChar - '0') % 2 == 0);
}
string assetSourceID = targetID;
if (isFemale && long.TryParse(targetID, out long idNum))
{
assetSourceID = (idNum - 1).ToString();
}
string maleFolder = $"{baseEffectFolder}/{assetSourceID}";
List<string> searchFolders = new List<string>();
if (AssetDatabase.IsValidFolder(localEffectFolder)) searchFolders.Add(localEffectFolder);
if (AssetDatabase.IsValidFolder(maleFolder) && !searchFolders.Contains(maleFolder)) searchFolders.Add(maleFolder);isFemale 来自末位偶数规则，assetSourceID 在女性分支减一。两者都是项目数据协议，不能用于任意角色 ID。搜索目录先包含当前目标目录，再在有效且不重复时加入男性目录，让共享模型有明确回退来源。
模型查找完成后，仍要确认角色与手指骨骼
方法从已有男、女列表取得目标角色，缺失时尝试反射创建。随后查找 targetBoneName，找不到就返回并记录警告，避免把戒指随意放到世界根。
csharp
// 对戒骨骼挂载与局部变换：以下保留实际处理语句，外围上下文见正文。
Transform boneTrans = FindDeepChild(targetRole.transform, targetBoneName);
if (boneTrans == null)
{
Debug.LogWarning($"[VFX Studio] 角色身上找不到手指骨骼【{targetBoneName}】，戒指挂载失败！");
return;
}
GameObject ringInstance = PrefabUtility.InstantiatePrefab(ringPrefab) as GameObject;
ringInstance.name = ringModelName;
ringInstance.transform.SetParent(boneTrans);
ringInstance.transform.localPosition = Vector3.zero;
if (hasChildCamera)
{
ringInstance.transform.localEulerAngles = new Vector3(0f, 90f, 0f);
}
else
{
ringInstance.transform.localEulerAngles = Vector3.zero;
}
Undo.RegisterCreatedObjectUndo(ringInstance, $"Instantiate Ring {ringModelName}");
handledModels.Add(ringModelName);ringPrefab 和 ringModelName 是前段查询结果，boneTrans 是目标骨骼。实例化后指定父级并将局部位置归零；旋转依据 hasChildCamera 选择约定值。这些数值对应当前资产制作坐标，迁移项目时必须与模型导出约定一起修改。
handledModels.Add 记录本轮模型已处理，Undo.RegisterCreatedObjectUndo 记录场景实例创建。之后动作查找和 Timeline 绑定仍是独立步骤：模型存在不保证动画存在，缺失时应分别反馈。
生成或打开 2065 hand Scene 后，装配入口按 ID 选择角色性别、查询戒指模型和动画，再把模型放入目标手指骨骼。画面中的挂载结果来自命名、目录与局部变换规则；检查时应同时查看父级、局部旋转以及时间轴实际播放对象。
六、男转女迁移先保存关系，再替换角色
复制 Scene 的制作成果，不代表绑定会自动迁移
Spawn2065FemaleAssets 为配对女性资源与场景建立入口，再调用 ExactMigrateMaleToFemaleScene。迁移方法处理的对象是女性 Scene 中仍继承男性结构的导演和时间轴。它先保存旧输出轨道的绑定，再复制时间轴文件并切换导演引用。
csharp
// 迁移前绑定快照与Timeline复制：以下保留实际处理语句，外围上下文见正文。
var oldTracks = oldTimeline.GetOutputTracks().ToList();
List<Object> oldBindings = new List<Object>();
foreach (var track in oldTracks)
{
oldBindings.Add(director.GetGenericBinding(track));
}
string oldTimelinePath = AssetDatabase.GetAssetPath(oldTimeline);
string oldTimelineName = Path.GetFileName(oldTimelinePath);
string newTimelineName = oldTimelineName.Replace(maleID, femaleID);
string newTimelinePath = $"{femaleFolder}/{newTimelineName}";
if (File.Exists(newTimelinePath)) AssetDatabase.DeleteAsset(newTimelinePath);
AssetDatabase.CopyAsset(oldTimelinePath, newTimelinePath);
TimelineAsset newTimeline = AssetDatabase.LoadAssetAtPath<TimelineAsset>(newTimelinePath);
if (newTimeline == null) return;
director.playableAsset = newTimeline;
var newTracks = newTimeline.GetOutputTracks().ToList();oldBindings 与 oldTracks 按索引对应，供复制后的新轨道恢复关系。这里的目标时间轴若已存在会被删除，然后才执行复制；它没有采用第 4 篇的唯一文件名策略，也未形成完整磁盘回滚事务。
随后定位男性左手指骨骼，创建女性角色并复制角色根的局部变换，再把男性手指下筛选出的特效孩子移动到女性右手指下。先建立 childrenToMove 再遍历移动，可避免在同一枚举期间改变父级集合；名称以 bip 开头或包含 finger 的孩子被视为骨骼并保留。
根对象和根 Animator 有明确替换规则
下面节选展示新轨道如何根据旧绑定决定目标。
csharp
// 男转女绑定替换规则：以下保留实际处理语句，外围上下文见正文。
if (boundObj == oldMaleCharRoot)
{
director.SetGenericBinding(newTrack, newFemaleCharRoot);
}
else if (boundObj is Animator anim && anim.gameObject == oldMaleCharRoot)
{
director.SetGenericBinding(newTrack, newFemaleCharRoot.GetComponent<Animator>());
}
else
{
director.SetGenericBinding(newTrack, boundObj);
}绑定正好是旧角色根时改为新角色根；绑定是旧根上的 Animator 时改为新角色根上的 Animator；其他对象继续使用原引用。它没有按相对路径普遍重映射所有内部骨骼与组件。这里的 GetOutputTracks 会枚举分组内的输出轨道，并非只取根层；它不包含 GroupTrack 自身及不独立输出的子轨道，子轨道片段的处理范围仍需单独检查。
方法末尾销毁旧男性角色根，因此仍指向旧角色内部对象的绑定可能失效。循环也默认新旧轨道数量和顺序一致，并直接用 oldBindings[i] 取值。标题中的自动迁移应在这些适用边界内理解，不能将方法名中的 Exact 当成已验证的全面保证。
女性动画替换仍依赖资源命名
片段中的 AnimationPlayableAsset.clip 经 FindFemaleEquivalentClip 查找对应女性版本；命中才替换，没有匹配则保留原片段。轨道与片段显示名同步替换 Man/man 及 ID 字符串，但显示名改变不等于绑定或动作资源已正确迁移。
因此应分别检查复制文件、迁移的特效子树、角色根绑定、内部骨骼引用和实际动画。它们是不同层面的结果，不能只通过文件名或角色外观判断完成。
七、交付清单、保存与撤销要各有边界
预测清单表达应交付内容，不验证文件存在
BuildPredictedExcelList 根据当前 ID 与配对规则生成条目，GenerateExportItemsForID 组织文件名，GenerateExcelText 生成适合配表的文本。它们把重复的交付约定程序化，减少跨团队反复确认名称，却不会证明每个文件都已经创建或导出成功。
文件清单、磁盘资产与场景状态应相互核对：预计名称正确但文件缺失，需要回到生成阶段；文件存在但绑定错误，需要回到装配阶段；画面正确但清单遗漏，则需要检查交付规则。
SaveAssets 与 MarkSceneDirty 保存的是不同对象
装配结束通常调用 AssetDatabase.SaveAssets 保存资产，并用 EditorSceneManager.MarkSceneDirty 标记场景待保存；后者不会直接把 Scene 写入磁盘。建档中特定 hand 分支又额外调用 SaveScene，这是另一层明确提交。
Undo 分组能合并部分场景对象创建与组件修改，但不能自动回滚创建、覆盖或删除的所有资产文件。业务入口需要明确告诉操作者本次修改了哪类对象，不能把一次撤销操作当成完整管线事务。
八、全系列的闭环来自显式数据与可检查的关系
从按钮数量转向输入、映射与生命周期
第 1 篇建立窗口、配置与业务服务边界；第 2、3 篇把选择集和组件引用变成批处理；第 4 篇以轨道和层级关系恢复演出绑定；第 5 篇控制扫描与绘制成本；第 6 篇为选定依赖建立副本映射；第 7 篇管理临时实例、时间与图像；第 8 篇把外部命令和文本转换为接口；第 9 篇最终用 ID 和业务规则编排这些能力。
贯穿其中的共同方法是先明确输入，再构造可传递的中间数据，最后在清晰的写入位置提交结果。字典表达旧引用到新引用，列表表达有序任务，集合表达本轮去重，路径表达层级位置；Unity API 提供底层能力，项目封装负责约定与顺序。
新人需要可理解的入口，维护者需要可验证的契约
程序化的收益来自把稳定经验写出来：资源在哪里、依赖复制哪些、角色挂在哪里、动画控制谁、哪些失败会停止。它降低学习与协作成本，同时要求团队维护规则、暴露歧义，并保留最终视觉检查。
系列在此收束。下一步工程化演进应围绕已暴露的具体边界：结构化规则配置、统一执行上下文、可靠错误汇总、重复执行策略和可回滚的资产操作。每项改进都应以实际输入与验证结果为依据，逐步扩大自动化可负责的范围。