UnityAI/modules/frameworks/相机系统/使用指南.md

# 相机系统使用指南

## 一、创建自定义相机

### 1.1 继承 AbsHFCameraItem

```csharp
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;
    }
}
```

---

## 二、管理相机堆栈

### 2.1 使用相机管理器

```csharp
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);
    }
}
```

### 2.2 相机堆栈架构

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

---

## 三、相机管理 API

### 3.1 常用方法

| 方法 | 说明 |
|-----|------|
| `AddCamera()` | 添加相机到堆栈 |
| `RemoveCamera()` | 从堆栈移除相机 |
| `GetCamera()` | 获取指定相机 |

---

**版本**: v1.0  
**生效日期**: 2026年  
**适用范围**: GiftGameX 项目业务开发人员

---

## 文档关联

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

| 文档 | 关联原因 |
|---|---|
| [相机系统入口](README.md) | 本文件是相机系统模块的子文档 |
| [UI 窗口系统](../UI窗口系统/README.md) | UI 窗口系统常与相机系统协作 |
| [资源管理](../资源管理/README.md) | 相机资源加载依赖资源管理 |
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |