83 lines
2.6 KiB
Plaintext
83 lines
2.6 KiB
Plaintext
---
|
|
description: Unity 调试信息与 Gizmo 可视化规范
|
|
globs: **/*.cs
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Unity 调试与可视化规范
|
|
|
|
编写 MonoBehaviour 或与场景交互的脚本时，应添加合适的调试信息与可视化 Gizmo，便于编辑器内调试与问题定位。
|
|
|
|
## 1. Gizmo 可视化
|
|
|
|
### 何时添加
|
|
- **空间/范围相关**：中心点、半径、边界框、射线、碰撞区域
|
|
- **路径/轨道**：环形轨道、移动路径、连线
|
|
- **状态可视化**：当前朝向、选中高亮、有效/无效区域
|
|
|
|
### 建议
|
|
- 用 `OnDrawGizmosSelected()`：仅在选中对象时绘制，减少干扰
|
|
- 用 `OnDrawGizmos()`：需始终可见的辅助线（如重要边界）
|
|
- 使用 `#if UNITY_EDITOR` 包裹 Gizmo 代码，避免打进构建
|
|
- 颜色区分：绿色/青绿=有效/正常，黄/橙=参考点，红=警告/边界
|
|
|
|
### 示例
|
|
|
|
```csharp
|
|
#if UNITY_EDITOR
|
|
private void OnDrawGizmosSelected()
|
|
{
|
|
if (ringCenter == null) return;
|
|
float r = ringRadius > 0f ? ringRadius : /* 从 transform 计算 */;
|
|
if (r < 0.01f) return;
|
|
|
|
Vector3 center = ringCenter.position;
|
|
Gizmos.color = new Color(0.3f, 0.9f, 0.55f, 0.6f);
|
|
// 绘制圆环轨迹
|
|
const int segments = 64;
|
|
for (int i = 0; i < segments; i++)
|
|
{
|
|
float a0 = (float)i / segments * 2f * Mathf.PI;
|
|
float a1 = (float)(i + 1) / segments * 2f * Mathf.PI;
|
|
Vector3 p0 = center + new Vector3(Mathf.Cos(a0) * r, Mathf.Sin(a0) * r, center.z);
|
|
Vector3 p1 = center + new Vector3(Mathf.Cos(a1) * r, Mathf.Sin(a1) * r, center.z);
|
|
Gizmos.DrawLine(p0, p1);
|
|
}
|
|
Gizmos.color = new Color(1f, 0.5f, 0f, 0.8f);
|
|
Gizmos.DrawWireSphere(center, 0.05f);
|
|
}
|
|
#endif
|
|
```
|
|
|
|
## 2. 调试日志
|
|
|
|
### 何时添加
|
|
- **配置缺失**：关键引用为 null 时用 `Debug.LogWarning` 提示
|
|
- **异常分支**：不应进入的逻辑用 `Debug.LogError`
|
|
- **状态切换**：可选，重要状态变化用 `Debug.Log`（建议配合 `[Conditional("UNITY_EDITOR")]` 或 `#if UNITY_EDITOR` 限制编辑器内）
|
|
|
|
### 建议
|
|
- 使用 `this` 作为 context 参数，方便 Inspector 中定位对象
|
|
- 避免每帧/高频调用 `Debug.Log`，影响性能
|
|
|
|
### 示例
|
|
|
|
```csharp
|
|
#if UNITY_EDITOR
|
|
if (interactionCollider == null)
|
|
{
|
|
Debug.LogWarning($"[{GetType().Name}] 未找到 Collider2D！请添加或指定 interactionCollider。", this);
|
|
}
|
|
#endif
|
|
```
|
|
|
|
## 3. 可选：Inspector 开关
|
|
|
|
对复杂 Gizmo 或大量日志，可在 Inspector 中加 Bool 开关：
|
|
|
|
```csharp
|
|
[Header("调试")]
|
|
[SerializeField] private bool showDebugGizmo = true;
|
|
[SerializeField] private bool enableDebugLog = false;
|
|
```
|