Skip to main content

Scene/Prefab 接入标准

本页定义项目内场景、预制体和资源引用的最小接入要求。
与 art-assets.md、配置表和 handoff 约束冲突时，以更高优先级文档为准。

适用范围​

  • 所有需要进入游戏场景树、UI 树或功能树的美术/技术资源。
  • 所有将资源挂载到 GameObject、Canvas、Prefab 的改动。

预制体层级与组件边界​

  1. 仅允许 Prefab 作为交付单位，不允许以散落场景物体替代长期资产。
  2. 同功能链路避免重复 prefab 嵌套与重复实例化，优先通过子资源引用复用。
  3. 禁止 prefab 之间通过未命名/临时空节点传递状态依赖。
  4. 禁止在 release 代码路径硬编码测试节点、测试粒子或测试纹理引用。
  5. 组件脚本挂载遵循“职责单一”：
    • 显示层：UI/表现脚本
    • 业务层：状态驱动脚本
    • 数据层：配置读取或状态缓存脚本

资源引用约束​

  • 引用必须可从 resource_key 反查到 source 与 导出清单。
  • 统一采用绝对稳定引用（配置 key + handoff key），禁止临时路径引用。
  • 同一功能中的同类资源禁止多份语义重复资源并行存在（如双份同名 icon）。
  • 场景中的测试/调试对象必须有统一开关控制，release 关闭后不允许留下组件或引用。

变更粒度与审批触发​

  • 功能新增：形成完整接入清单（含 prefab 变更、场景变更、资源 key 与引用目标）。
  • 资源迁移：仅允许在 handoff 中同步“原 key / 新 key / 兼容窗口”三项信息后合入。
  • 结构大改（移除、重建 root）必须产出影响范围和回滚说明。

验收清单（必须）​

  • prefab 变更的 owner review 与可视 evidence 到位。
  • 场景树中无临时测试 Prefab 残留。
  • 引用链路为三段闭环：resource_key -> prefab/scene -> 配置表 entry。
  • 发现 duplicate root、非法挂载、直接引用 editor-only 资源 时，返回 blocker。