---
name: unity-development-rules
description: Unity 开发规则（Unity Vision 项目）。在本项目里写或改 C# 脚本、预制体、场景时适用，包含节点引用接线等硬性约定。
---

# Unity 开发规则

本项目的硬性约定。动手写脚本、改预制体或场景之前先对照这里。

## 节点引用必须在 Inspector / 预制体里指定，不能硬编码到代码

脚本要访问场景或预制体里的节点（Transform、Text、Image、其他组件……）时，一律用 `[SerializeField]` 字段，由 Inspector 或预制体把引用接好。

**不允许**——在代码里按名字 / 标签 / 路径找节点：

```csharp
// ❌ 节点名字写死在代码里
target = transform.Find("FPS").GetComponent<TMP_Text>();
target = GameObject.Find("FPS").GetComponent<TMP_Text>();

foreach (var t in GetComponentsInChildren<TMP_Text>(true))
    if (t.name == "FPS") return t;
```

**允许**：

```csharp
[SerializeField] private TMP_Text target;   // ✅ 引用由 Inspector / 预制体提供
```

**为什么**：节点改名或挪位置以后，硬编码的查找会静默失效——不报错、就是不工作；而且引用关系藏在代码里，看 Inspector 看不出到底接没接上。

**引用为空时**：不要写运行时兜底查找，直接报错，让接线问题第一时间暴露。

```csharp
private void Awake()
{
    if (target == null)
        Debug.LogError("[Xxx] 没有指定 target，请在 Inspector 里拖入。", this);
}
```

**边界**：这条只约束游戏运行时代码。编辑器工具、一次性批处理脚本需要按结构查找节点时可以照常查找。