星火 2.0 开发文档

主题

单位换模与表现重建 ​

主参考：单位换模与附属表现重建。涉及 GameGraph 时同时按需阅读桥接语义和骨骼动画。

先确定项目要控制什么 ​

  • 使用框架主模型：服务端 ModelSwap(link, tag) / ModelSwapPop(tag)，客户端在本轮新模型和所需绑点就绪后恢复默认表现。
  • 自定义外观控制：服务端同步项目自有 PropertyUnit 外观值，客户端从当前状态管理自己创建的模型子树；Unit 继续负责身份、移动与玩法属性。
  • 只加装备或外观部件：读自动挂载模型表现或GameGraph 附加模型，无需重建整个主模型。

常规重建规则 ​

  1. unit.RebuildDefaultActors() 完全清理单位作用域，并默认重建当前技能、Buff 等附着对象的默认 Actor；false 只处理单位作用域。单个技能 / Buff 用自己的 RebuildDefaultActors()。
  2. 携带物品的 HostedActors 由物品记账，却也在持有者 Unit 的 ActorScope 中。单位重建会清掉它们，必须随后遍历 InventoryManager.Items.OfType<ItemMod>() 调用 RebuildHostedActors()，否则装备外观不能恢复。单独恢复物品时只调用物品入口。
  3. 明示副作用：清理范围中的动态 Actor 同样销毁，不播放淡出；只恢复当前数据的 ActorArray，旧引用失效，实例变换和播放进度丢失，声音 / 动画可能重启。技能冷却、Buff 层数与时长、装备属性和授予技能不重置。未登记到对应集合的节点由项目清理。
  4. 物品重建按当前槽位、持有者和启用条件创建，只处理该物品记录的表现；不恢复地面自身或品质特效。不要拿 UpdateModifications(forced: true) 代替表现重建。
  5. 服务端调用只是给当前可见客户端的一次请求，不等待模型加载。客户端调用只影响本地。不要生成 ModelSwap(); RebuildDefaultActors(); 并承诺顺序可靠，也不要以固定帧数 / 延迟作为模型已就绪的证据。当前没有通用的脚本换模前后通知；项目需核对目标实例和实际绑点，取消过时请求。

高级路线必须保留的知识 ​

  • 换模保留单位根 Node，替换模型子树、骨架和 Socket。普通子表现靠父子变换跟随，不需要每帧查找绑点；换模前若父节点就是 Socket，可读取 Parent.Name，有自建中间锚点则需要项目语义映射。
  • GetAnimatedModel() 是骨骼渲染组件包装，不是整个主模型管理器。SetModel(mesh) 只改网格 / 骨架，不负责完整 Prefab、材质、动画、Socket 和状态条更新。只销毁项目自己拥有的组件 / 子树，不能随意删除框架主模型组件或单位根。
  • 自建外观在 EventUnitCreate 和对应 EventUnitPropertyChange 都按当前值应用；前者包含重新进入客户端视野。合并属性与节点就绪顺序、连续形态请求；销毁 / 离开视野时清理自建实例和订阅。服务端独立维护形态的玩法判定。
  • 先准备新实例、核对挂点，再迁移子表现并释放旧实例；Prefab.CreateInstance(parent) 必须有父节点。模型组件常在子节点中，复杂 Prefab 要明确选择主骨骼宿主。
  • 对框架主模型的普通 Actor 用 Actor.AttachTo(unit, socketName) 更新 Actor 挂接关系，再恢复需要保留的局部变换。直接 Node.Parent / AddChild() 不会同步 Actor 的父子记账和专用绑定。
  • 自建 Prefab 的 Socket 不会自动成为 Actor.AttachTo(unit, socketName) 的查询目标；需要项目挂接逻辑。若把 Actor 改挂自建锚点，先 Actor.Detach()，再操作其表现 Node，并自行管理变换、清理及独立的作用域归属。默认重建不会自动路由到自建模型。
  • GetSocket(name) 返回骨骼 Node + 局部变换快照；要在骨骼下建锚点并应用这些变换。它不等于 Prefab 内实际 Socket Node。替换后重新查找，不复用旧骨骼、Socket 或组件。
  • 只在本轮迁移时需要保留的实例可用临时快照；C# Node 包装不保住底层节点，必须在旧子树释放前读出信息并把子表现迁到仍被持有的节点。事后扫描不能保证恢复已消失的绑点名。
  • 骨骼附加模型需解除旧 AdditionModelAttachment 并向新宿主重新挂载；材质、光束等按专用引用关系处理，不能承诺移动 Node 覆盖全部 Actor 类型。

用现有 API 自建外观不需要为方案本身新增客户端能力，但具体 API 仍需满足目标客户端支持范围。代码编译只证明签名正确；模型、骨架和绑点效果应在实际资源中验证。