目录

Unity Roguelike 项目代码规范

1. 基本目标

• 统一风格，降低维护成本，便于多人协作与调试。
• 代码可读、可测、可视化（日志/Gizmos），保持性能与内存安全。

2. 基础格式

• 统一使用 UTF-8（无 BOM）的编码格式，确保跨平台兼容性；行尾不留空格；换行 \n。
• 缩进 4 空格；花括号换行（K&R 变体）；每文件单一公开类。
• using 顺序：System.* → 第三方 → UnityEngine → UnityEngine.UI → 其他。
• 文件名 = 公开类/接口/枚举名。

3. 命名规则

• 类型/枚举/委托：PascalCase；接口前缀 I（保留现有 SM_ 系列）。
• 字段：camelCase；序列化私有字段 [SerializeField] private；常量 PascalCase 或 UPPER_SNAKE。
• 布尔：以 is/has/can/should 开头；事件：OnXxx。
• Animator 参数：常量化或序列化字段，避免硬编码字符串。
• Inspector 暴露的 LayerMask/Prefab/Transform 等必须命名清晰，含用途。

4. 注释与文档

• 公开类/方法/字段：<summary> 简述用途。
• 复杂逻辑前 1–2 行中文行注释说明意图/边界。
• 调试或临时代码标记 TODO: / NOTE:，注明清理条件。

5. 生命周期与职责

• Awake：缓存组件、空引用防护、生成默认资源（材质/Mesh）。
• Start：外部依赖校验、默认值填充、事件订阅。
• Update：输入、动画参数、非物理逻辑。
• FixedUpdate：物理、速度/力/碰撞决策。
• OnDestroy：解绑事件、销毁自建资源（Mesh/Material/VFX 实例）。
• 禁止在渲染回调中做逻辑；渲染调试放 OnRenderObject/Gizmos。

6. 序列化与 Inspector

• 可调参数均序列化并加 [Header]/[Tooltip]/[Range]。
• 数值在 OnValidate/Awake 用 Mathf.Clamp/Max 做范围保护。
• 必填引用（Animator/Rigidbody2D/Prefab/LayerMask）启动时检测，缺失 Debug.LogError 并禁用脚本或降级。

7. 输入

• 所有按键/轴为可配置字段，不在逻辑中硬编码。
• 输入读取集中在 Update 或输入封装模块；多人/手柄可扩展。

8. 物理与碰撞

• 2D 刚体默认 CollisionDetectionMode2D.Continuous，冻结无用旋转轴。
• 多射线/Overlap 检测封装函数；排除自身；LayerMask 必须显式配置，缺失时有回退与警告。
• 移动/击退/冰冻等通过 Rigidbody/接口（如 SM_IKnockbackable），避免直接改 Transform。
• 碰撞预测/限速有保护：最大安全速度、预测命中即减速/终止。

9. 战斗与数值

• 伤害统一入口：Attribute 或 SM_IDamageable.ApplyDamage(SM_DamageInfo)。
• 记录基础伤害、减伤、最终伤害；元素/暴击集中处理，边界保护（最小 0，最大上限）。
• 状态效果组件化（Burn/Freeze/Stun/Knockback），支持叠加策略（刷新剩余时间或取最大值，明确约定）。
• VFX：prefab + 自动销毁（粒子 duration + 余量或固定超时）；缺失 prefab 只警告不报错。

10. 动画

• Animator 参数在启动时 HasParameter 校验并缓存 hash；缺失时警告并回退默认参数名。
• Trigger 触发前 ResetTrigger；布尔用于持续态，Trigger 用于瞬态。
• 动画事件仅做回调，不放重逻辑；状态切换时先清理残留 Trigger。

11. UI

• UI 脚本只管显隐与交互；业务逻辑与数据独立。
• 打开 UI 时处理 Time.timeScale/AudioListener.pause；淡入淡出用 CanvasGroup/Animator，使用 unscaledDeltaTime。
• 所有 Button/Text/Slider 在 Start 校验空引用；失败时报错并禁用功能。

12. 资源与内存

• 自建 Mesh/Material/纹理：OnDestroy 释放。
• 高频对象（投射物/VFX）优先对象池；临时实例必须自动销毁。
• 禁止在运行时频繁创建 GC 压力大的对象（String.Concat 热路径、LINQ 在核心循环等）。

13. 日志与调试

• 关键行为（伤害、死亡、冷却、配置缺失、自动回退）保留 Debug.Log/Warning/Error。
• 量大日志用布尔开关（如 showDebugInfo）；诊断函数用 [ContextMenu] 并标“仅调试”。
• Gizmos/Handles 受开关控制；#if UNITY_EDITOR 包裹 Editor 相关 API。

14. 错误处理

• 空引用防护：早返回 + 日志；外部依赖缺失时禁用脚本或降级。
• 数值非法（负值/NaN）回退默认并警告。
• 网络/IO 不在主线程；Unity 主线程操作保持线程安全。

15. 架构与职责

• 单一职责，小函数；>80 行拆分；公共魔法数抽常量或配置（ScriptableObject）。
• 跨脚本共享数据用 ScriptableObject/管理器，不用 FindObjectOfType 作为长期方案。
• 事件订阅成对绑定/解绑；避免匿名委托解绑困难。

16. 提交与目录

• 不提交 Library/, Logs/, UserSettings/ 等生成目录。
• 单一变更单一提交；提交前跑对应自测并写明影响范围。
• 资源命名有前缀（模块_用途），例如：UI_InventoryPanel, VFX_FireHit.

17. 自测清单（新增/修改功能时）

• 输入：按键/手柄路径可触发；非法输入安全退出。
• 物理：地面/墙体检测正确，连续碰撞无穿模。
• 战斗：攻击命中、LayerMask 生效；伤害/元素/暴击日志正确；状态效果叠加符合策略。
• UI：可开关，暂停逻辑正确；CanvasGroup 动画无时间缩放问题。
• 资源：特效/抛射物自动销毁或回收到池；Mesh/Material 释放。
• 日志：开关可控，缺失配置有清晰错误。

18. 示例代码片段（风格示范）

using UnityEngine;

public class Firebolt : MonoBehaviour
{
    [Header("Config")]
    [SerializeField] private float speed = 8f;
    [SerializeField] private float lifetime = 2.5f;
    [SerializeField] private float damage = 12f;
    [SerializeField] private SM_Element element = SM_Element.Fire;
    [SerializeField] private LayerMask hitLayers;
    [SerializeField] private GameObject hitVfxPrefab;

    private Vector2 direction;
    private float timer;

    public void Launch(Vector2 dir)
    {
        direction = dir.normalized;
    }

    private void Update()
    {
        transform.position += (Vector3)(direction * speed * Time.deltaTime);
        timer += Time.deltaTime;
        if (timer >= lifetime) Destroy(gameObject);
    }

    private void OnTriggerEnter2D(Collider2D other)
    {
        if (((1 << other.gameObject.layer) & hitLayers.value) == 0) return;

        var dmg = other.GetComponent<SM_IDamageable>();
        if (dmg != null)
        {
            dmg.ApplyDamage(new SM_DamageInfo
            {
                Amount = damage,
                Element = element,
                IgnoreDefense = false,
                CritChance = 0.1f,
                CritMultiplier = 1.5f
            });
        }

        PlayHitVfx(other.transform.position);
        Destroy(gameObject);
    }

    private void PlayHitVfx(Vector3 pos)
    {
        if (hitVfxPrefab == null) return;
        var vfx = Instantiate(hitVfxPrefab, pos, Quaternion.identity);
        var main = vfx.GetComponent<ParticleSystem>()?.main;
        Destroy(vfx, main.HasValue && main.Value.duration > 0 ? main.Value.duration + 0.5f : 2f);
    }
}