UnityAI/modules/frameworks/相机系统/README.md

相机系统

分类

• 核心框架

目的

管理多相机注册、相机堆栈排序、渲染顺序控制，为 UI、场景、特效等提供分层渲染能力。

---

核心类

类	职责
HFCameraManager	相机管理器单例，维护相机列表和主相机引用
HFMainCamera	主相机，管理 CameraStack
AbsHFCameraItem	相机项抽象基类，子类实现具体相机逻辑

---

创建自定义相机

继承 AbsHFCameraItem，实现 CameraItem 和 Weight 属性：

public class UIOverlayCamera : AbsHFCameraItem
{
    [SerializeField] private Camera uiCamera;
    [SerializeField] private int weight = 10;
    
    public override Camera CameraItem => uiCamera;
    public override int Weight => weight;
    
    protected override void OnInitialize()
    {
        base.OnInitialize();
        uiCamera.clearFlags = CameraClearFlags.Depth;
        uiCamera.depth = 100;
    }
}

---

相机堆栈架构

HFMainCamera (主相机)
    │
    ├── CameraStack (相机堆栈)
    │       ├── CameraItem1 (Weight=10)
    │       ├── CameraItem2 (Weight=20)
    │       └── CameraItem3 (Weight=5)
    │
    └── 按 Weight 排序 → 渲染顺序控制

---

管理相机

public class CameraController : MonoBehaviour
{
    void Start()
    {
        HFCameraManager cameraMgr = HFCameraManager.Instance;
        
        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
        cameraMgr.AddCamera(uiCamera);
        
        Camera mainCam = cameraMgr.mainCamera.MainCamera;
    }
    
    void OnDestroy()
    {
        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
        HFCameraManager.Instance.RemoveCamera(uiCamera);
    }
}

---

常用 API

方法	说明
AddCamera(AbsHFCameraItem)	添加相机到堆栈
RemoveCamera(AbsHFCameraItem)	从堆栈移除相机
GetCamera(string cameraName)	获取指定名称相机

---

使用规则

• 相机项必须继承 AbsHFCameraItem。
• Weight 决定堆栈内渲染顺序，值越大越靠后渲染。
• 添加和移除相机需成对出现，避免残留。
• UI 相机通常使用 CameraClearFlags.Depth 和较高 depth。

---

相关模块

• UI 窗口系统
• 资源管理

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
modules/模块索引.md	模块索引是项目知识总入口
modules/frameworks/UI窗口系统/README.md	UI 窗口系统常与相机系统协作
rules/10-架构说明.md	架构说明定义总体分层和依赖方向
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径