星火 2.0 开发文档

主题

GameGraph 附加模型挂载 ​

这是“自动挂载模型表现”的下钻版本。 附加模型是挂到宿主上的外观资源；上层 Actor 根据 ActorArray 自动管理显示，下钻接口复用同一套挂载、骨骼跟随及可选的宿主网格裁剪机制，由代码选择宿主并维护挂载生命周期。解释功能时先说明这层表里关系，不要把它描述成与自动挂载表现无关的新装备系统。

使用“附加模型”“宿主模型”“主骨骼模型”等公开术语。详细指南为 GameGraph 附加模型挂载；在生成项目中也可从 docs/sdk/systems/GameGraphAdditionModel.md 查阅。

选择入口 ​

  • 单位/物品槽位/Buff 已由数据驱动显示外观：使用 自动挂载模型表现，保留 GameDataActorAdditionModel + ActorArray 生命周期。
  • 直接 GameGraph 角色、换装预览或确实要代码控制挂载：使用本 Skill。无需传 model link，也无需创建附加模型 Actor。
  • 普通静态物件/特效需要指定骨骼或 Socket 加局部偏移：使用 GetBoneNode / GetSocket 子节点挂接，不冒充骨骼附加模型。
  • 玩法属性、命中判定或联机状态：由玩法系统管理。此接口不提供装备逻辑、服务端渲染或自动网络同步。

实施步骤 ​

  1. 将代码限制在 #if CLIENT，核对 api/client/GameGraph_NodeSystem_Component_Graphics.cs 和 api/client/GameGraph_ResourceSystem.cs 中的准确签名。
  2. 确认宿主是 Prefab 实例，取得并保存其主骨骼模型的具体 AnimatedModelComponent。只设置 .mdl / Mesh 的组件不受支持。
  3. Prefab 根节点通常没有模型组件。已知只有一个主骨骼模型时，可在挂载前使用 GetComponentInChildren<AnimatedModelComponent>()；该函数仅返回首项，不识别主骨骼。复杂资源必须先确认模型所在层级，不可将任意模型组件当宿主。挂载后不要重新搜索首项作为宿主。
  4. 确认附加资源是包含骨骼模型的 Prefab，且 Skin、骨骼名、Bind Pose、坐标轴、厘米单位和初始变换适配宿主。具体制作要求沿用上层文档。
  5. 调用 host.AttachAdditionModel(prefabPath, options) 或传已加载 Prefab。保存返回的 AdditionModelAttachment；不存在 Node.AttachAdditionModel 或通用 AdditionModelComponent 创建入口。
  6. 在换装、角色清理、场景结束或宿主替换前调用 Detach() / Dispose()；同一资源多次挂载需要分别保存和清理句柄。不要依赖 GC。
  7. 验证资源发布及实际显示，不以编译通过代替资源适配验收。

最小调用片段 ​

片段假定 host 已确认是主骨骼宿主，additionPath 是真实的 GameCore.ResourceType.Prefab 资源引用；不得虚构资源路径或假设随机模型都适配。

csharp
#if CLIENT
var attachment = host.AttachAdditionModel(
    additionPath,
    new GameGraph.NodeSystem.Component.Graphics.AdditionModelOptions
    {
        CullHostMesh = false,
    });

// 将 attachment 保存在角色/外观所有者中。换装或清理时：
attachment.Detach();
#endif

完整的宿主创建、换装和 IDisposable 示例见指南。下钻后“自动”指按资源骨架完成对齐/跟随，不代表框架会自动监听项目的装备槽位或替项目调用解除挂载。

裁剪、句柄和失败语义 ​

  • AdditionModelOptions.CullHostMesh 对应上层同名字段，默认 false。只有覆盖宿主主体且资源支持裁剪时考虑开启；不能保证任意披风/外套都适合裁剪，不将其当通用防穿模开关。
  • Detach() 与 Dispose() 清理同一次挂载，可重复调用。同一 Prefab 两次挂载返回独立句柄，解除其中一次不应顺带解除另一次。
  • IsAttached 仅反映句柄是否有效并持有标识，不能证明宿主原生对象仍存活或模型当前可见。
  • 路径加载失败、宿主不满足 Prefab 主骨骼条件或附加资源没有可挂载骨骼模型时，可能抛出 InvalidOperationException；已加载资源参数为 null 时抛出 ArgumentNullException。记录具体资源和宿主，修正条件后再试，不通过改成任意子模型掩盖失败。
  • 替换宿主前先清理旧挂载，新实例重新取主骨骼模型，不复用旧句柄。

交付与验收 ​

  • 云资源确保宿主、全部附加模型候选与依赖进入发布清单；动态路径和已加载资源句柄不能替代资源声明。项目 res/ 内容随项目包发布，无需为它单独统计云资源。详见 资源清单排查。
  • 联机外观由服务端同步选择状态，再由每个客户端维护自己的句柄；不要声称调用此 API 自动发布或同步了附加模型。
  • 使用当前匹配的 SDK、依赖库与客户端/编辑器二进制。
  • 检查多帧待机/运动中的对齐与跟随，换装/解除，同一资源两次挂载后分别解除，宿主销毁重建，以及裁剪启用/解除后的宿主显示。
  • 上报已验证的场景与证据；没有运行验收就明确只完成编译或文档核对。