# 光照效果实现

<cite>
**本文档中引用的文件**
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts)
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts)
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts)
- [GameMap.ts](file://assets/script/game/map/GameMap.ts)
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts)
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts)
- [FlashSprite.ts](file://assets/script/game/map/FlashSprite.ts)
- [MoveUV.ts](file://assets/script/game/map/view/MoveUV.ts)
- [map.json](file://assets/resources/config/map/map.json)
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts)
</cite>

## 目录
1. [项目概述](#项目概述)
2. [光照效果架构](#光照效果架构)
3. [核心组件分析](#核心组件分析)
4. [遮罩层实现方案](#遮罩层实现方案)
5. [后处理效果实现](#后处理效果实现)
6. [视野范围控制机制](#视野范围控制机制)
7. [地图分块加载联动](#地图分块加载联动)
8. [性能优化与适配](#性能优化与适配)
9. [高级视觉效果扩展](#高级视觉效果扩展)
10. [最佳实践建议](#最佳实践建议)

## 项目概述

本项目是一个基于Cocos Creator的游戏，采用ECS架构设计，实现了肉鸽游戏风格的迷雾探索玩法。光照效果作为核心视觉系统的重要组成部分，负责控制玩家视野范围，营造神秘感和探索氛围。

### 技术栈特点
- **引擎版本**: Cocos Creator
- **架构模式**: ECS（Entity-Component-System）
- **渲染技术**: 支持多种光照实现方案
- **性能考量**: 针对移动端优化的设计

## 光照效果架构

光照效果系统采用分层架构设计，包含以下核心层次：

```mermaid
graph TB
subgraph "光照效果系统架构"
A[光照控制器] --> B[遮罩层管理器]
A --> C[后处理效果处理器]
B --> D[灰度图遮罩]
B --> E[透明度渐变遮罩]
C --> F[Shader处理]
C --> G[SpriteMask处理]
H[地图分块系统] --> A
I[玩家位置系统] --> A
J[相机跟随系统] --> A
end
subgraph "渲染管线"
K[主摄像机] --> L[光照遮罩层]
L --> M[游戏场景层]
M --> N[UI层]
end
```

**图表来源**
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts#L1-L18)
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L77)

## 核心组件分析

### 基础光照组件

当前项目中的基础光照组件位于[`light.ts`](file://assets/script/game/map/view/map/layer/light.ts#L1-L18)，虽然目前处于空壳状态，但为未来的功能扩展预留了接口。

```mermaid
classDiagram
class LightComponent {
+start() void
+onLoad() void
+update(deltaTime) void
+createFogMask() Mask
+updateVisibility(playerPos) void
+applyShaderEffect() void
}
class MapViewScene {
+camera Camera
+layer Node
+mapLayer MapLayer
+entityLayer EntityLayer
+isFollowPlayer boolean
+ratio Vec2
+init() void
+update(dt) void
}
class MapLayer {
+bgImg Sprite
+init() void
+clear() void
+bgImage Sprite
+width number
+height number
}
LightComponent --> MapViewScene : "控制"
MapViewScene --> MapLayer : "管理"
```

**图表来源**
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts#L4-L18)
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L15-L45)
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts#L15-L46)

**章节来源**
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts#L1-L18)
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L77)
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts#L1-L47)

### 地图视图管理系统

地图视图系统负责整体场景的渲染管理和光照效果的协调工作：

- **摄像机控制**: 实现玩家跟随和视野限制
- **层级管理**: 确保光照效果正确叠加在游戏场景之上
- **渲染优化**: 通过分层渲染减少不必要的绘制调用

**章节来源**
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L15-L77)
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts#L1-L45)

## 遮罩层实现方案

### 方案一：灰度图遮罩层

灰度图遮罩是最经典的迷雾效果实现方式，通过调整纹理的灰度值来控制可见性。

#### 实现原理
1. **纹理准备**: 使用黑白灰度图定义可见区域
2. **Alpha混合**: 通过Shader实现灰度值到透明度的映射
3. **动态更新**: 根据玩家位置实时更新遮罩纹理

#### 技术优势
- **性能优异**: GPU原生支持，计算开销小
- **视觉效果好**: 自然的渐变过渡
- **易于调试**: 可直接编辑遮罩纹理

### 方案二：透明度渐变遮罩

基于透明度渐变的遮罩实现，适合需要复杂视觉效果的场景。

#### 实现特点
- **渐变控制**: 支持多种渐变模式（圆形、矩形、不规则形状）
- **多光源支持**: 可同时处理多个光源的遮罩效果
- **边缘平滑**: 提供高质量的边缘处理

**章节来源**
- [FlashSprite.ts](file://assets/script/game/map/FlashSprite.ts#L1-L28)
- [MoveUV.ts](file://assets/script/game/map/view/MoveUV.ts#L1-L49)

## 后处理效果实现

### Shader-Based光照效果

基于Shader的后处理效果提供了最灵活的光照控制能力：

```mermaid
sequenceDiagram
participant Player as 玩家位置
participant System as 光照系统
participant Shader as Shader处理器
participant Render as 渲染管线
Player->>System : 位置更新
System->>System : 计算视野范围
System->>Shader : 传递参数
Shader->>Shader : 执行光照计算
Shader->>Render : 输出处理结果
Render->>Player : 显示最终画面
```

**图表来源**
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L198-L235)

#### Shader实现要点
1. **顶点着色器**: 处理几何变换和光照坐标计算
2. **片段着色器**: 实现复杂的光照算法和遮罩效果
3. **纹理采样**: 优化纹理访问模式，减少带宽消耗

### SpriteMask实现方案

SpriteMask是一种轻量级的遮罩实现方式：

#### 优势特点
- **简单易用**: 不需要编写Shader代码
- **兼容性强**: 支持所有平台和设备
- **调试方便**: 可直接在编辑器中预览效果

#### 适用场景
- 移动设备优化
- 快速原型开发
- 简单的遮罩需求

**章节来源**
- [FlashSprite.ts](file://assets/script/game/map/FlashSprite.ts#L15-L28)

## 视野范围控制机制

### 动态视野算法

视野范围控制是光照效果的核心功能，其实现涉及多个方面的协调：

```mermaid
flowchart TD
A[玩家位置检测] --> B{视野类型判断}
B --> |静态视野| C[固定半径遮罩]
B --> |动态视野| D[渐进式展开]
B --> |追踪视野| E[跟随玩家移动]
C --> F[遮罩纹理更新]
D --> F
E --> F
F --> G[性能优化检查]
G --> H{性能阈值}
H --> |正常| I[应用最终效果]
H --> |过载| J[降级处理]
I --> K[渲染输出]
J --> L[简化效果]
L --> K
```

**图表来源**
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L198-L262)

### 视野参数配置

| 参数名称 | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| 视野半径 | number | 300 | 玩家周围可见范围半径 |
| 渐变强度 | number | 0.8 | 遮罩边缘的模糊程度 |
| 更新频率 | number | 0.1s | 视野更新的时间间隔 |
| 最大遮罩数量 | number | 4 | 同时存在的遮罩层数 |

**章节来源**
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L198-L262)

## 地图分块加载联动

### 分块加载机制

地图分块加载与光照效果的联动确保了游戏性能和视觉体验的平衡：

```mermaid
graph LR
subgraph "地图分块系统"
A[当前区块] --> B[已加载区域]
C[相邻区块] --> D[预加载区域]
E[远处区块] --> F[未加载区域]
end
subgraph "光照效果系统"
G[视野中心] --> H[光照遮罩]
H --> I[动态更新]
I --> J[性能优化]
end
B --> H
D --> H
F -.-> H
subgraph "联动逻辑"
K[区块加载] --> L[光照初始化]
M[区块卸载] --> N[光照清理]
O[玩家移动] --> P[区块切换]
P --> Q[光照重定位]
end
```

**图表来源**
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L1-L36)
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts#L1-L45)

### 动态更新策略

1. **渐进式加载**: 当玩家接近新区域时逐步加载光照数据
2. **内存管理**: 及时释放远离玩家区域的光照资源
3. **同步机制**: 确保光照效果与地图加载状态保持一致

**章节来源**
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L20-L36)
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts#L15-L45)

## 性能优化与适配

### 性能对比分析

| 实现方案 | CPU开销 | GPU开销 | 内存占用 | 兼容性 | 推荐场景 |
|---------|---------|---------|----------|--------|----------|
| Shader遮罩 | 低 | 中等 | 中等 | 高 | PC端、高端设备 |
| SpriteMask | 中等 | 低 | 低 | 极高 | 移动端、低端设备 |
| 后处理效果 | 中等 | 高 | 高 | 中等 | 主流设备 |

### 适配策略

#### 移动端优化
- **降低分辨率**: 减少光照纹理的分辨率
- **简化算法**: 使用更简单的遮罩算法
- **帧率控制**: 动态调整光照更新频率

#### 高端设备优化
- **增强效果**: 使用高质量的Shader和纹理
- **多光源**: 支持复杂的多光源叠加效果
- **实时阴影**: 实现动态阴影投射

**章节来源**
- [FlashSprite.ts](file://assets/script/game/map/FlashSprite.ts#L1-L28)
- [MoveUV.ts](file://assets/script/game/map/view/MoveUV.ts#L1-L49)

## 高级视觉效果扩展

### 多光源叠加系统

扩展光照系统以支持多个光源的同时作用：

```mermaid
classDiagram
class MultiLightSystem {
+lights LightSource[]
+addLight(source) void
+removeLight(id) void
+updateLights() void
+combineEffects() Texture
}
class LightSource {
+position Vec2
+radius number
+color Color
+intensity number
+shape Shape
+calculateEffect() Effect
}
class ShadowCaster {
+castShadow(light) Texture
+calculateDepthMap() Texture
+applySoftShadows() Texture
}
MultiLightSystem --> LightSource : "管理"
LightSource --> ShadowCaster : "产生"
ShadowCaster --> MultiLightSystem : "贡献"
```

### 动态阴影实现

动态阴影系统能够根据光源位置和物体高度产生真实的阴影效果：

#### 实现步骤
1. **深度缓冲**: 创建专门的深度纹理存储场景深度信息
2. **阴影映射**: 将光源视角下的深度信息投影到屏幕空间
3. **软阴影**: 应用阴影过滤算法产生柔和的边缘效果

### 区域高亮效果

为重要区域（如宝箱、传送点）添加特殊的高亮效果：

#### 效果类型
- **脉冲高亮**: 周期性闪烁的高亮效果
- **追踪高亮**: 跟随目标移动的持续高亮
- **交互高亮**: 响应玩家操作的即时高亮

**章节来源**
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L198-L262)

## 最佳实践建议

### 开发规范

1. **组件分离**: 将光照效果与业务逻辑完全分离
2. **参数化设计**: 提供丰富的配置参数以便调整
3. **性能监控**: 实现运行时性能指标收集

### 测试策略

1. **多设备测试**: 在不同硬件配置下验证效果
2. **性能基准**: 建立性能基线用于回归测试
3. **用户体验测试**: 确保光照效果不会影响游戏体验

### 维护建议

1. **文档更新**: 及时更新光照系统的使用文档
2. **版本兼容**: 保持与引擎版本的兼容性
3. **社区反馈**: 积极响应开发者社区的需求

通过以上架构设计和实现方案，本光照效果系统能够满足肉鸽游戏的迷雾探索需求，同时具备良好的扩展性和性能表现。开发者可以根据具体项目需求选择合适的实现方案，并在此基础上进行功能扩展和优化。