unity-scriptdesign

**在调用此模块中的任何技能之前：**如果你准备根据技能名称或描述猜测参数并调用技能，请先停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获得参数定义，则可直接进行 dryRun。

触发条件

• 审查代码质量
• 理顺高耦合脚本
• 为可维护性规划重构
• 审查代码质量、理顺高耦合脚本、为可维护性规划重构

Unity 脚本设计审查

在创建游戏玩法脚本之前，或脚本生成后需要进行设计审查时，使用此技能。

审查清单

• 职责：脚本是否只有一个明确的任务？
• 角色：它是否真的应该是 MonoBehaviour、ScriptableObject 或普通 C# 类？
• 耦合：依赖是否明确，而非隐藏的全局对象或深层场景查找？
• 通信：应使用直接引用、接口调用还是事件？
• 性能：是否存在不必要的 Update、重复的 Find、可避免的分配，或热路径中的反射？
• 生命周期：订阅、计时器和异步工作是否都能明确清理？
• Inspector 体验：序列化字段是否为私有、经过分组并有说明？
• 可测试性：核心逻辑能否移入普通 C# 类？
• 命名：类名和字段名是否清晰表达意图，避免晦涩的缩写？

数据生命周期边界

上面的审查清单会问“这个 类 应该放在哪里”。对每个 字段 也问同样的问题。每项状态都有三种生命周期之一，把字段放在错误的生命周期中，是最常见的导致“为什么设计师调整了一个值就出问题了”和“为什么我的单元测试时好时坏”的原因。

生命周期	值的确定时机	所属位置	典型写法
创作时	设计师在 Editor 中、进入 Play 之前	ScriptableObject 资源，或预制体上的 [SerializeField] private	运行时不可变；通过 _config.Speed 读取
组合时	每个场景/实例一次，在 Awake/Start 时	private 字段，通过 GetComponent / GetComponentInChildren / 构造函数参数赋值	缓存引用，不进行逐帧查找
运行时可变	每帧或在游戏玩法事件发生时	private 后备字段 + public 只读属性 + 事件	通过 public float Health { get; private set; } + OnHealthChanged 暴露

典型分配方式

• 武器伤害 / 射速 / 弹匣容量 → 创作时（使用 ScriptableObject，以便热切换平衡参数）。
• 敌方 AI 当前目标 Transform → 如果在生成时设置一次，则为 组合时；如果每帧重新指定目标，则为 运行时可变。
• 玩家当前 HP → 运行时可变，并使用事件。绝不要写成 public float hp;。
• 同一 GameObject 上对 Rigidbody/Animator 的引用 → 组合时，在 Awake 中缓存。
• 关卡音乐曲目 → 通过 ScriptableObject 关卡描述符在 创作时 指定。
• “正在战斗”标记 → 运行时可变，但通常可从其他状态推导出来——审查它是否应该作为字段存在。

为什么要区分

混淆这三种生命周期，会让干净的类变成上帝对象。一个 public float speed 同时由 Inspector 和强化道具脚本修改的 MonoBehaviour，有两个所有者，且没有不变量；任一条路径中的错误都会破坏另一条路径。ECS 烘焙流水线将这一区分设为硬性架构边界（Authoring → Baker → System），这种规范也可直接应用于此：如果你不会在 ECS 中混用 Authoring 组件与运行时回写，就不要在 MonoBehaviour 中这样做。来源：EntitiesSamples/Docs/baking.md:5-16。

防护措施

模式：仅限文档 — 无需设置 REST 技能门禁；在任何运行模式（Approval / Auto / Bypass）下均可自由加载。

• 优先使用描述性名称，而非局部简写。
• 不要为了想象中的效率提升而牺牲可读性。
• 如果更小的重构就能解决实际问题，就不要推荐复杂模式。

输出格式

• 保留：已有的优点
• 简化：应保持直观的部分
• 重构：价值最高的结构性改动
• 性能说明：仅指出真正的热点，不要讨论理论上的微优化
• 可维护性说明：命名、归属、耦合、编辑器易用性