zeling_v2/Docs/Standards/LayerSpec.md

Unity Layer 命名与用途规范

版本：1.0
创建日期：2026-05
适用范围：项目所有 GameObject 的 Layer 分配
关联文档：Standards/AssetFolderSpec.md、Editor/Tools/Physics2DLayerReport.cs

---

目录

1. 概述
2. Layer 清单
3. Physics 2D 碰撞矩阵
4. 使用规范
5. 检查与修复工具

---

1. 概述

本项目使用固定的 Layer 名称集合来驱动 Physics 2D 碰撞矩阵、伤害判定、视线检测（LOS）、地面检测等核心系统。所有 Layer 必须在 Edit → Project Settings → Tags and Layers 中手动创建，名称必须与本文档一致（大小写敏感）。

重要：代码中通过 LayerMask.NameToLayer("LayerName") 引用 Layer，若 Layer 不存在将返回 -1 并导致逻辑错误。创建场景对象时请优先使用 BaseGames → Scene → Place 菜单工具，该工具会自动校验并赋值 Layer。

---

2. Layer 清单

2.1 玩家相关

Layer 名称	挂载对象	用途说明
Player	玩家根节点 GameObject	玩家物理碰撞体（含 Rigidbody2D）；地面检测、存档点、检查点触发器通过此 Layer 筛选玩家
PlayerHurtBox	玩家子节点 HurtBox	接收伤害的碰撞体（isTrigger）；EnemyHitBox / EnemyProjectile 命中此 Layer 时对玩家造成伤害
PlayerHitBox	玩家武器 / 技能 HitBox	发出伤害的碰撞体；命中 EnemyHurtBox 时触发对敌人的伤害判定
PlayerProjectile	玩家发射的投射物	玩家子弹；不与 PlayerHurtBox、EnemyProjectile 碰撞，命中 EnemyHurtBox 或 Ground 时有效

2.2 敌人相关

Layer 名称	挂载对象	用途说明
Enemy	敌人根节点 GameObject	敌人物理碰撞体（含 Rigidbody2D）；与 Ground 碰撞实现站立
EnemyHurtBox	敌人子节点 HurtBox	接收伤害的碰撞体（isTrigger）；PlayerHitBox / PlayerProjectile 命中此 Layer 时对敌人造成伤害；EnemyHitBox 也可命中此 Layer（敌人互伤，HitBox 运行时排除自身根节点）
EnemyHitBox	敌人武器 HitBox / LethalTrap 主体	发出伤害的碰撞体；命中 PlayerHurtBox 时触发对玩家的伤害判定
EnemyProjectile	敌人发射的投射物	敌人子弹；不与 EnemyHurtBox 碰撞，命中 PlayerHurtBox 或 Ground 时有效

2.3 地形相关

Layer 名称	挂载对象	用途说明
Ground	静态地面、移动平台、Tilemap 地形、障碍物	玩家与敌人站立的实体地面；PlayerMovement 的 _groundLayer、PlayerWallDetector 的 _wallLayer（默认）均包含此 Layer；投射物命中后销毁
Wall	墙壁碰撞体（垂直面）	玩家攀墙检测（PlayerWallDetector 默认掩码包含 Wall 和 Ground）；若地形使用统一的 Tilemap 则墙壁可合并到 Ground Layer

2.4 触发区域

Layer 名称	挂载对象	用途说明
TriggerZone	存档点（CheckpointMarker）、存档台（SavePoint）、传送站（TeleportStation）、房间过渡（RoomTransition / DoorTransition）、相机区域（CameraArea）	纯触发碰撞体（isTrigger），不参与物理阻挡；统一使用此 Layer 方便在碰撞矩阵中集中管理

2.5 特殊用途

Layer 名称	挂载对象	用途说明
PhantomBody	幽灵/幻象角色的实体碰撞体	PhantomInteractable 通过 other.gameObject.layer == PhantomBody 判断是否为幻象角色触发交互

---

3. Physics 2D 碰撞矩阵

以下为项目期望的碰撞配置，由 Physics2DLayerReport 工具维护与校验。

Layer A	Layer B	应碰撞	说明
PlayerHitBox	EnemyHurtBox	✅	玩家攻击伤害敌人
EnemyHitBox	PlayerHurtBox	✅	敌人攻击伤害玩家
EnemyHitBox	EnemyHurtBox	✅	敌人可互相伤害（HitBox 运行时排除自身根节点）
Player	Ground	✅	玩家站在地面上
Enemy	Ground	✅	敌人站在地面上
PlayerProjectile	EnemyHurtBox	✅	玩家投射物伤害敌人
PlayerProjectile	PlayerHurtBox	❌	玩家投射物不自伤
PlayerProjectile	Ground	✅	玩家投射物命中地形
EnemyProjectile	PlayerHurtBox	✅	敌人投射物伤害玩家
EnemyProjectile	EnemyHurtBox	❌	敌人投射物不自伤
EnemyProjectile	Ground	✅	敌人投射物命中地形
PlayerHitBox	PlayerHurtBox	❌	玩家不自伤
PlayerProjectile	EnemyProjectile	❌	子弹不互相碰撞（Clash 系统单独处理）

未在上表中列出的 Layer 对默认继承 Unity 全局设置（默认全部碰撞）。

---

4. 使用规范

4.1 Layer 赋值方式

• 优先使用 SceneObjectPlacerTool（菜单 BaseGames → Scene → Place → …）自动赋值，避免遗漏。
• 手动创建 GameObject 时，在 Inspector 顶部 Layer 下拉菜单中选择对应 Layer。
• 代码中引用时，通过 LayerMask.NameToLayer("LayerName") 获取整型索引，或通过 LayerMask.GetMask("LayerA", "LayerB") 获取掩码值。

// 推荐：缓存到字段，避免每帧调用
private int _playerLayer;

void Awake()
{
    _playerLayer = LayerMask.NameToLayer("Player");
}

4.2 子节点继承规则

• 玩家 / 敌人根节点与其 HurtBox、HitBox 必须分别挂不同 Layer，不可统一使用根节点 Layer。
• LethalTrap（陷阱）：主体用 EnemyHitBox，可弹起的子 HurtBox 用 EnemyHurtBox。
• 触发区域对象（存档点等）统一用 TriggerZone，不需要额外子节点分层。

4.3 禁止事项

• 禁止在代码中硬编码 Layer 整型编号（如 layer == 8），必须使用名称转换。
• 禁止直接修改 ProjectSettings/TagManager.asset 中的 Layer 顺序（会导致所有已赋值对象 Layer 错乱）。
• 禁止将 TriggerZone 对象的 Collider 设置为非 trigger（isTrigger 必须为 true）。

---

5. 检查与修复工具

项目提供了 Physics2DLayerReport 编辑器工具，位于菜单：

BaseGames → Tools → Physics2D Layer Matrix → Check
BaseGames → Tools → Physics2D Layer Matrix → Auto Fix

• Check：打印当前碰撞矩阵与期望配置的对比报告。
  • ✅ 正常
  • ❌ 当前配置与期望不符（需修复）
  • ⚠ Layer 不存在（需先在 Tags and Layers 中创建）
• Auto Fix：自动将所有不符合期望的碰撞对修正为正确值，并持久化到 ProjectSettings。

建议在以下时机运行 Check：新人入职初始化环境、合并来自其他分支的 ProjectSettings 变更后、新增 Layer 之后。