高效游戏开发指南：拒绝返工与项目规划

## 系统名称

## 1. 目标 (Goal)

这个系统要解决什么问题？

## 2. 非目标 (Non-Goals)

明确这个系统**不做**什么，防止需求蔓延。

## 3. 设计方案 (Design)

### 3.1 数据结构

### 3.2 关键流程

### 3.3 边界情况处理

## 4. 待定问题 (Open Questions)

列出需要后续确认的点。

## AssetSpec.yaml - 资源规格文档
UI图标:
  尺寸: 256x256px
  格式: PNG with Alpha
  命名: icon_{类型}_{名称}.png

角色模型:
  面数上限: 5000 tris (移动端)
  骨骼数: 最多30根
  贴图: 单张 2048x2048 的合并贴图

特效:
  粒子数上限: 50 (同屏)
  持续时间: 不超过 3 秒

## Unity 生成文件
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Uu]ser[Ss]ettings/

## 永远不要提交的配置
*.csproj
*.unityproj
*.sln
*.suo
*.user
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

## 大型资源通过 Git LFS 管理
*.psd
*.ai
*.fbx
*.obj
*.wav
*.mp3
*.ogg
*.mp4

## 安装 Git LFS
git lfs install

## 追踪大文件类型
git lfs track "*.psd"
git lfs track "*.fbx"
git lfs track "*.wav"
git lfs track "*.mp4"

## 提交 .gitattributes
git add .gitattributes
git commit -m "chore: 配置 Git LFS"

// ❌ 不好的写法 - 每帧都 GetComponent
void Update() {
    GetComponent<Rigidbody>().velocity = Vector3.zero;
}

// ✅ 好的写法 - 缓存引用
Rigidbody _rb;
void Awake() {
    _rb = GetComponent<Rigidbody>();
}
void Update() {
    _rb.velocity = Vector3.zero;
}

## 改动说明

简要描述这次改动做了什么。

## 相关 Issue

关联 #123

## 测试情况

- [ ] 单元测试通过
- [ ] 手动测试通过
- [ ] 性能测试无明显下降

## 截图/录屏（如有 UI 改动）

[可选] 附上改动前后的对比

## Reviewer 注意事项

这个改动可能影响到 XX 系统，请重点关注 YY 部分。

// ❌ 每次拼接都会产生新的 string 对象
void Update() {
    string text = "Score: " + score.ToString();
    scoreText.text = text; // GC Alloc!
}

// ✅ 使用 StringBuilder 或缓存
using System.Text;
StringBuilder _sb = new StringBuilder(32);

void Update() {
    _sb.Clear();
    _sb.Append("Score: ");
    _sb.Append(score);
    scoreText.text = _sb.ToString();
}

// ❌ 不要在 Update 中查找
void Update() {
    GameObject player = GameObject.Find("Player");
    player.transform.position += Vector3.forward;
}

// ✅ 在初始化时查找并缓存
Transform _playerTransform;
void Start() {
    _playerTransform = GameObject.Find("Player").transform;
}
void Update() {
    _playerTransform.position += Vector3.forward;
}

// ❌ 将值类型转换为 object 会装箱
Dictionary<string, object> data = new();
data["health"] = 100; // Boxing!

// ✅ 使用泛型或专用数据结构
Dictionary<string, int> intData = new();
intData["health"] = 100; // No boxing

public class BulletPool : MonoBehaviour {
    [SerializeField] GameObject _bulletPrefab;
    Queue<GameObject> _pool = new(50);

    void Start() {
        // 预热：创建初始数量的子弹
        for (int i = 0; i < 50; i++) {
            GameObject bullet = Instantiate(_bulletPrefab);
            bullet.SetActive(false);
            _pool.Enqueue(bullet);
        }
    }

    public GameObject Get() {
        if (_pool.Count > 0) {
            GameObject bullet = _pool.Dequeue();
            bullet.SetActive(true);
            return bullet;
        }
        return Instantiate(_bulletPrefab); // 池子空了才实例化
    }

    public void Return(GameObject bullet) {
        bullet.SetActive(false);
        _pool.Enqueue(bullet);
    }
}

// 不要用暴力遍历查找范围内的敌人
// ❌ O(n) - 每个塔都遍历所有敌人
foreach (var tower in towers) {
    foreach (var enemy in enemies) {
        if (Vector3.Distance(tower.pos, enemy.pos) < tower.range) {
            tower.Attack(enemy);
        }
    }
}

// ✅ 使用网格 (Grid) 或四叉树 (Quadtree)
GridSystem grid;
foreach (var tower in towers) {
    List<Enemy> nearbyEnemies = grid.GetEnemiesInRange(
        tower.position, tower.range
    );
    // 现在只遍历附近的敌人
}

public class Tower : MonoBehaviour {
    [SerializeField] float attackRange = 5f;

    // 在 Scene 视图中绘制攻击范围
    void OnDrawGizmos() {
        Gizmos.color = Color.yellow;
        Gizmos.DrawWireSphere(transform.position, attackRange);
    }

    // 只在选中时绘制（减少干扰）
    void OnDrawGizmosSelected() {
        Gizmos.color = Color.red;
        Gizmos.DrawSphere(transform.position, 0.5f);
    }
}

void Update() {
    // 绘制射线，持续 1 秒
    Debug.DrawRay(
        transform.position,
        transform.forward * 10f,
        Color.green,
        1f
    );
}

public class DebugManager : MonoBehaviour {
    void Update() {
#if UNITY_EDITOR || DEVELOPMENT_BUILD
        // 这段代码只在编辑器或开发版本中运行
        if (Input.GetKeyDown(KeyCode.F1)) {
            SpawnTestEnemy();
        }
        if (Input.GetKeyDown(KeyCode.F2)) {
            AddGold(1000);
        }
#endif
    }
}

#if UNITY_EDITOR
using UnityEditor;

public class GameDebugger : EditorWindow {
    [MenuItem("Vampirefall/Game Debugger")]
    static void ShowWindow() {
        GetWindow<GameDebugger>("游戏调试器");
    }

    void OnGUI() {
        GUILayout.Label("快速测试", EditorStyles.boldLabel);

        if (GUILayout.Button("生成测试波次")) {
            // 触发测试逻辑
            FindObjectOfType<WaveManager>()?.SpawnTestWave();
        }

        if (GUILayout.Button("清空所有敌人")) {
            var enemies = FindObjectsOfType<Enemy>();
            foreach (var enemy in enemies) {
                Destroy(enemy.gameObject);
            }
        }

        if (GUILayout.Button("金币 +1000")) {
            PlayerController.Instance.AddGold(1000);
        }
    }
}
#endif

public enum LogLevel {
    Debug,   // 详细调试信息
    Info,    // 一般信息
    Warning, // 警告
    Error    // 错误
}

public static class GameLogger {
    static LogLevel _minLevel = LogLevel.Info;

    public static void Log(string message, LogLevel level = LogLevel.Info) {
        if (level < _minLevel) return;

        switch (level) {
            case LogLevel.Debug:
                Debug.Log($"[DEBUG] {message}");
                break;
            case LogLevel.Info:
                Debug.Log($"[INFO] {message}");
                break;
            case LogLevel.Warning:
                Debug.LogWarning($"[WARN] {message}");
                break;
            case LogLevel.Error:
                Debug.LogError($"[ERROR] {message}");
                break;
        }
    }
}

## Jenkins/GitHub Actions 自动构建脚本
name: Daily Build

on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build Unity Project
        run: |
          unity-build --project . --platform Android
      - name: Run Tests
        run: unity-test --project .
      - name: Upload APK
        if: success()
        uses: actions/upload-artifact@v2
        with:
          name: vampirefall-daily.apk
          path: build/vampirefall.apk

## 严重 Bug 处理流程

### 1. 快速评估（15 分钟内）

- 影响范围：多少玩家？
- 能否通过服务器配置绕过？
- 是否需要强制更新？

### 2. 临时措施（1 小时内）

- 关闭受影响的功能模块（feature flag）
- 公告通知玩家
- 准备补偿方案

### 3. 修复与验证（4 小时内）

- 紧急修复 bug
- 回归测试
- 准备热更新包

### 4. 上线与监控

- 分批灰度更新
- 监控错误率
- 24 小时值班

// 修改旧代码时，顺手改善一点点
void OldFunction() {
    // 原本的屎山代码
    var data = GetData();
    // ... 一堆难懂的逻辑

    // 这次修改时，加一行注释
    // TODO: 这段逻辑应该拆分成独立函数（下次重构时处理）
}

## 技术债务登记表

## 高优先级（影响开发效率）

- [ ] EnemyController 超过 500 行，需要拆分
- [ ] 配置表加载逻辑耦合在 GameManager 中

## 中优先级（代码质量问题）

- [ ] Tower 系统缺少单元测试
- [ ] UI 代码有大量重复逻辑

## 低优先级（优化项）

- [ ] 部分变量命名不规范
- [ ] 缺少部分注释

// TowerConfig.asset (ScriptableObject)
[CreateAssetMenu(fileName = "Tower", menuName = "Game/TowerConfig")]
public class TowerConfig : ScriptableObject {
    [Header("基础属性")]
    public string displayName;
    public Sprite icon;
    public int buildCost;

    [Header("战斗属性")]
    public float attackRange;
    public float attackInterval;
    public int baseDamage;

    [Header("升级路线")]
    public TowerConfig[] upgradeOptions;

    [Header("特殊效果")]
    public StatusEffectConfig[] onHitEffects;

    // 编辑器验证
    void OnValidate() {
        if (attackInterval <= 0) {
            Debug.LogError($"{name}: 攻击间隔必须大于0!");
        }
        if (buildCost < 0) {
            Debug.LogError($"{name}: 建造成本不能为负!");
        }
    }
}

#if UNITY_EDITOR
public class ConfigReloader : MonoBehaviour {
    void Update() {
        if (Input.GetKeyDown(KeyCode.F5)) {
            ReloadAllConfigs();
            Debug.Log("配置已重新加载！");
        }
    }

    void ReloadAllConfigs() {
        // 重新加载所有 ScriptableObject
        var configs = Resources.FindObjectsOfTypeAll<TowerConfig>();
        foreach (var config in configs) {
            EditorUtility.SetDirty(config);
        }
        AssetDatabase.SaveAssets();
        AssetDatabase.Refresh();
    }
}
#endif

#if UNITY_EDITOR
[MenuItem("Vampirefall/验证所有配置")]
static void ValidateAllConfigs() {
    int errorCount = 0;

    var towers = AssetDatabase.FindAssets("t:TowerConfig");
    foreach (var guid in towers) {
        string path = AssetDatabase.GUIDToAssetPath(guid);
        var config = AssetDatabase.LoadAssetAtPath<TowerConfig>(path);

        // 检查空引用
        if (config.icon == null) {
            Debug.LogError($"{config.name}: 缺少图标!");
            errorCount++;
        }

        // 检查数值合理性
        if (config.attackRange > 20f) {
            Debug.LogWarning($"{config.name}: 攻击范围过大 ({config.attackRange})");
        }
    }

    if (errorCount == 0) {
        Debug.Log("✅ 所有配置验证通过!");
    } else {
        Debug.LogError($"❌ 发现 {errorCount} 个错误!");
    }
}
#endif

/docs
  /tech
    /architecture     # 架构设计
    /patterns        # 设计模式实践
    /tools           # 工具使用
    /postmortems     # 项目复盘