basegames/zeling_v2
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

摄像机区域的优化

Browse Source
This commit is contained in:
Joywayer
2026-05-17 07:56:12 +08:00
parent f264329751
commit d25f237e76
62 changed files with 25774 additions and 5450 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
Docs/Verification/12_Manual_CameraSystem.md
View File

@@ -43,16 +43,27 @@ Persistent.unity
└── [Camera]
└── CameraStateController ExecutionOrder = -100
组件: CameraStateController
│ _vcamA → VCamA（全局虚拟相机 A）
│ _vcamB → VCamB（全局虚拟相机 B）
│ _vcamA → VCamA（全局虚拟相机 A）
│ _vcamB → VCamB（全局虚拟相机 B）
│ _lookSystem → CameraLookSystem 节点
组件: CinemachineBrain ← 实际渲染相机（随 Main Camera 放置）
组件: CinemachineImpulseSource ← 屏幕抖动信号源
├── CameraLookSystem ← 运行时由 SetFollowTarget() 赋值基准目标
│ 组件: CameraLookSystem 双轴窥视偏移 + 速度门控；输出 VirtualTarget
├── VCamA
│ 组件: CinemachineCamera Follow = Player/CameraFollowTarget
│ 组件: CinemachineCamera Follow = CameraLookSystem.VirtualTarget（运行时自动赋值）
│ 组件: CinemachinePositionComposer Body 跟随组件；初始值与 CameraArea 默认值对齐
│ 组件: CinemachineConfiner2D ← 由 CameraStateController 动态更新 BoundingShape2D
│ 组件: CameraAxisLockExtension 锁定 X 或 Y 轴（竖井 / 走廊场景）
│ 组件: CameraAsymmetricDampingExtension 非对称 Y 阻尼（下落快恢复，起跳慢追赶）
│ 组件: CameraAdaptiveLookaheadExtension 速度自适应 Lookahead（移动快 → 预见更多）
└── VCamB
组件: CinemachineCamera Follow = Player/CameraFollowTarget
组件: CinemachineCamera Follow = CameraLookSystem.VirtualTarget（运行时自动赋值）
组件: CinemachinePositionComposer 同 VCamA
组件: CinemachineConfiner2D ← 由 CameraStateController 动态更新 BoundingShape2D
组件: CameraAxisLockExtension
组件: CameraAsymmetricDampingExtension
组件: CameraAdaptiveLookaheadExtension
Level_01.unity
├── [CameraAreas]
@@ -92,8 +103,9 @@ Level_01.unity
| GameObject | 挂载组件 | 说明 |
|-----------|---------|------|
| `[CameraController]` | `CameraStateController`、`CinemachineBrain`、`CinemachineImpulseSource` | ExecutionOrder = -100 |
| `VCamA` | `CinemachineCamera`、`CinemachineConfiner2D` | 全局虚拟相机 A；拖入 `CameraStateController._vcamA` |
| `VCamB` | `CinemachineCamera`、`CinemachineConfiner2D` | 全局虚拟相机 B；拖入 `CameraStateController._vcamB` |
| `CameraLookSystem` | `CameraLookSystem` | 双轴窥视偏移（垂直+水平）+ 速度门控；输出 `VirtualTarget` 供 VCam 跟随；拖入 `CameraStateController._lookSystem` |
| `VCamA` | `CinemachineCamera`、**`CinemachinePositionComposer`**、`CinemachineConfiner2D`、`CameraAxisLockExtension`、`CameraAsymmetricDampingExtension`、`CameraAdaptiveLookaheadExtension` | 全局虚拟相机 A；**PositionComposer 是 Body 组件，必须存在**；拖入 `CameraStateController._vcamA` |
| `VCamB` | `CinemachineCamera`、**`CinemachinePositionComposer`**、`CinemachineConfiner2D`、`CameraAxisLockExtension`、`CameraAsymmetricDampingExtension`、`CameraAdaptiveLookaheadExtension` | 全局虚拟相机 B；同 VCamA；拖入 `CameraStateController._vcamB` |
> **注意**：`CinemachineBrain` 须挂在附有 `Camera` 组件（Main Camera）的 GameObject 上，
> 否则 Cinemachine 无法驱动视口渲染。两台全局 VCam 初始优先级均为 0，由 `CameraStateController` 在运行时动态管理。
@@ -108,6 +120,7 @@ Level_01.unity
| `_vcamA` (CinemachineCamera) | ● 已绑定 |
| `_vcamB` (CinemachineCamera) | ● 已绑定 |
| `_brain` (CinemachineBrain) | ● 已绑定 |
| `_lookSystem` (CameraLookSystem) | ● 已绑定 |
| `_impulseSource` (CinemachineImpulseSource) | ◌ 可选；用于屏幕抖动 |
| `_defaultBlendProfile` (CameraBlendProfileSO) | ◌ 可选；未设置则无混合过渡 |
@@ -175,12 +188,18 @@ Level_01.unity
### 3.4 全局 VCam Follow 绑定
Persistent 场景中两台全局 VCam 的 `CinemachineCamera.Follow` 须指向 **Player 下的 `CameraFollowTarget` 子节点**，而非 Player 根节点本身。
使用 `Place Player` 工具放置 Player 时，`CameraFollowTarget` 子节点会被自动创建（`localPosition = 0`）。
Persistent 场景中两台全局 VCam 的 `CinemachineCamera.Follow` **不直接指向 Player**，
而是指向 `CameraLookSystem` 组件在运行时生成的 **`[CameraLookTarget]` 虚拟目标节点**。
该节点由 `CameraStateController.SetFollowTarget(Transform)` 在玩家注册时自动创建并赋值，
其世界位置 = Player 基准目标位置 + 当前窥视偏移（`CameraLookSystem` 的双轴输出）。
**方法**：
- **自动**：打开 **Camera Area Setup** 窗口 → CameraStateController 区域 → 点击 **为全局 VCam 赋值 Follow 目标**（场景中必须已有 tag=Player 对象）
- **手动**：分别选中 `VCamA` / `VCamB` → CinemachineCamera 组件 → `Follow` 字段拖入 `Player/CameraFollowTarget` Transform
> **不要在 Inspector 中手动把 VCam.Follow 拖到 Player 本身或 Player/CameraFollowTarget。**
> `SetFollowTarget` 会在运行时覆盖，且直接指向 Player 会绕过窥视偏移计算。
**工具支持**：
**Camera Area Setup** 窗口 → **为全局 VCam 赋值 Follow 目标** 按钮
→ 该按钮仅用于调试回退（绕过 LookSystem，直指 Player/CameraFollowTarget）。
正式流程请通过 `ICameraService.SetFollowTarget(playerTransform)` 注册，由系统自动处理。
---
@@ -249,17 +268,22 @@ Inspector 参数预览区实时显示 FOV（来源：专有 VCam → 全局 VCam
### 4.2 CameraConfigSO
**创建路径**：`Assets → Create → BaseGames → Camera → CameraConfig`
> ⚠ **Legacy / 已废弃**：`CameraConfigSO` 是早期相机系统的配置资产，现已不再被 `CameraStateController` 读取或应用。
> 当前架构直接通过 `CameraArea` 字段（`ScreenPosition`、`DeadZoneSize`、`LookaheadTime`、`DampingDown`、`DampingUp` 等）在 `ConfigureSlot` 时写入 Cinemachine 组件，无需此 SO。
> 若项目中仍存在 `CameraConfigSO` 资产，可安全忽略或删除。
~~**创建路径**：`Assets → Create → BaseGames → Camera → CameraConfig`~~
| 字段 | 说明 | 典型值 |
|------|------|--------|
| `FollowDamping` | 跟随阻尼（越大越迟钝） | `0.15` |
| `LookAheadTime` | 朝向预见时间（秒） | `0.3` |
| `DeadZoneSize` | 死区尺寸（玩家在此范围内移动相机不动） | `(1, 0.5)` |
| `SoftZoneSize` | 软区尺寸（慢速追赶） | `(2.5, 2)` |
| `LookDownOffset` | 俯视偏移（负值向下） | `-1.5` |
| `LookUpOffset` | 仰视偏移（正值向上） | `1.5` |
| `DefaultImpulseStrength` | 默认震屏强度 | `0.3` |
| `FollowDamping` | ~~跟随阻尼~~ | — |
| `LookAheadTime` | ~~朝向预见时间~~ | — |
| `DeadZoneSize` | ~~死区尺寸~~ | — |
| `SoftZoneSize` | ~~软区尺寸~~ | — |
| `LookDownOffset` | ~~俯视偏移~~ | — |
| `LookUpOffset` | ~~仰视偏移~~ | — |
| `DefaultImpulseStrength` | ~~默认震屏强度~~ | — |
> `CameraConfigSO` 的配置值须由运行时的 `CameraStateController` 或相机系统读取并写入 Cinemachine 组件，具体写入逻辑取决于 `CameraStateController.ApplyConfig()` 的实现（如有扩展）。
@@ -285,7 +309,7 @@ Inspector 参数预览区实时显示 FOV（来源：专有 VCam → 全局 VCam
| `✗`（红） | 缺失必填项 |
| `◌`（黄） | 可选项未设置 |
检查项：`_vcamA`、`_vcamB`（必填）、`_brain`（必填）、`_impulseSource`（可选）、`_defaultBlendProfile`（可选）
检查项：`_vcamA`、`_vcamB`（必填）、`_brain`（必填）、`_lookSystem`（必填）、`_impulseSource`（可选）、`_defaultBlendProfile`（可选）
底部按钮：**为全局 VCam 赋值 Follow 目标** → 查找 Player/CameraFollowTarget 并写入两台 VCam 的 Follow 字段。
@@ -461,7 +485,7 @@ Inspector 参数预览区实时显示 FOV（来源：专有 VCam → 全局 VCam
| 现象 | 原因 | 解决 |
|------|------|------|
| Game 视图相机不动（黑屏或固定位置） | 全局 VCam `Follow` 未绑定 | Camera Area Setup → 为全局 VCam 赋值 Follow 目标 |
| Game 视图相机不动（黑屏或固定位置） | 全局 VCam `Follow` 未绑定 | `ICameraService.SetFollowTarget(player)` 注册玩家；或 Camera Area Setup → 为全局 VCam 赋值 Follow 目标 |
| 相机追赶卡顿/震颤 | `CinemachineConfiner2D.BoundingShape2D` 未绑定或碰撞体顶点有误 | 确认 `CameraArea._confinerCollider` 已绑定，PolygonCollider2D 顶点数 ≥ 3 |
| 进入区域后限位未更新（仍在旧区域限位内） | `CameraArea._confinerCollider` 为空，`ConfigureSlot` 跳过了更新 | 打开 Camera Area Setup 修复 `_confinerCollider` 绑定 |
| 场景中有多个 `CinemachineBrain` | Persistent 场景外又添加了含 Camera 组件的对象 | 仅 Main Camera 上保留一个 Brain |
@@ -470,3 +494,7 @@ Inspector 参数预览区实时显示 FOV（来源：专有 VCam → 全局 VCam
| 触发器无响应（玩家穿越后相机不切） | `CameraTriggerZone._targetArea` 未绑定，或 `_playerTag` 不匹配 | 检查 `_targetArea` 是否已拖入 `CameraArea`；确认 Player Tag = "Player" |
| `Camera Area Setup` 窗口列表为空 | 场景未保存或 DomainReload 后未刷新 | 点击窗口内 `↻ 刷新` 按钮 |
| 专有 VCam 不切换 | `_dedicatedPriority` ≤ 全局激活优先级（默认 10） | 将 `_dedicatedPriority` 设置为 > 10（默认 20 已满足） |
| Camera Area Setup 中 `_lookSystem` 红色 ✗ | `CameraStateController._lookSystem` 未绑定 | 将 Persistent 场景 `[Camera]/CameraLookSystem` 节点拖入该字段；或重新运行 SceneScaffoldTools |
| 按住方向键相机偏移不出现（窥视无效） | `CameraLookSystem._baseTarget` 未设置 | 确认 `ICameraService.SetFollowTarget(player)` 在玩家 Awake/Start 后调用 |
| 下落时相机跟随过慢（非对称阻尼异常） | `CameraAsymmetricDampingExtension` 未挂到 VCamA/VCamB，或 `DampingDown` 未被 `ConfigureSlot` 写入 | 确认两台 VCam 已挂载该扩展；检查 `CameraArea._dampingDown` > 0 |
| 高速移动时 Lookahead 不变化 | `CameraAdaptiveLookaheadExtension` 未挂到 VCamA/VCamB，或 `SetConfiguredMax` 未被调用 | 确认两台 VCam 已挂载该扩展；检查 `ConfigureSlot` 代码路径正常执行 |