# LightMapSystem

**Repository Path**: tohand/light-map-system

## Basic Information

- **Project Name**: LightMapSystem
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-15
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LightMapSystem - 重构版本

## 概述

这是对原始 LightMap.cs 的完全重构版本，采用了更好的架构设计，提供了更好的性能、错误处理和可维护性。

## 文件结构

```
LightMapSystem/
├── Runtime/                          # 运行时代码
│   ├── LightMapData.cs              # 数据结构和枚举定义
│   ├── LightMapInterfaces.cs        # 接口定义
│   ├── LightMapLogger.cs            # 日志系统
│   ├── LightMapUtility.cs           # 工具方法集合
│   ├── LightMapComponent.cs         # 主要运行时组件
│   ├── ShaderHelper.cs              # 着色器和材质管理
│   └── LightMapDefaultsAsset.cs     # 默认设置管理
├── Editor/                          # 编辑器代码
│   ├── LightMapBaker.cs             # 烘焙功能
│   ├── LightMapEditor.cs            # 编辑器界面
│   ├── LightMapMigrationTool.cs     # 迁移工具
│   └── LightMapSystemTests.cs       # 测试工具
└── README.md                        # 本文档
```

## 核心组件

### 运行时组件

1. **LightMapComponent** - 主要的运行时组件
   - 替代原始的 LightMap MonoBehaviour
   - 实现 ILightMapProvider 接口
   - 提供缓存机制和错误处理
   - 支持自动备份和恢复原始设置

2. **LightMapData** - 数据结构定义
   - 包含所有枚举和数据结构
   - 添加了数据验证方法
   - 包含烘焙结果和设置类

3. **LightMapUtility** - 工具方法集合
   - 渲染器数据收集
   - 光照贴图数据提取
   - 着色器收集
   - 使用对象池减少内存分配

4. **ShaderHelper** - 着色器和材质管理
   - 智能材质刷新
   - 光照贴图属性处理
   - 着色器兼容性检查

5. **LightMapDefaultsAsset** - 默认设置管理
   - ScriptableObject 配置文件
   - 可视化编辑器
   - 设置捕获和重置功能

### 编辑器组件

6. **LightMapBaker** - 烘焙功能
   - 实现 ILightMapBaker 接口
   - 提供异步烘焙支持
   - 完整的事件系统和状态管理
   - 自动资源清理

7. **LightMapEditor** - 编辑器界面
   - 重构的 Inspector 界面
   - 更好的用户体验
   - 实时进度显示
   - 自动预制体更新

8. **LightMapMigrationTool** - 迁移工具
   - 从旧组件迁移到新组件
   - 批量迁移功能
   - 迁移报告生成

9. **LightMapSystemTests** - 测试工具
   - 基本功能验证
   - 组件创建测试
   - 数据结构测试

## 主要改进

### 1. 架构改进
- **单一职责原则**: 每个类只负责一个功能
- **接口分离**: 使用接口提高可测试性和扩展性
- **命名空间隔离**: 使用 `Qinyou.LightMapSystem` 命名空间

### 2. 性能优化
- **组件缓存**: 避免重复的 GetComponent 调用
- **对象池**: 减少临时对象分配
- **延迟加载**: 只在需要时创建对象

### 3. 错误处理
- **异常捕获**: 完整的 try-catch 块
- **参数验证**: 输入参数的空值检查
- **优雅降级**: 错误时的回退机制

### 4. 内存管理
- **IDisposable**: 正确的资源清理
- **事件取消订阅**: 防止内存泄漏
- **缓存机制**: 减少重复计算

### 5. 日志和调试
- **统一日志**: 一致的日志格式和级别
- **详细错误信息**: 包含上下文的错误消息
- **测试工具**: 内置的系统测试功能

## 使用方法

### 基本使用

1. 将 `LightMapComponent` 添加到 GameObject
2. 配置光照设置
3. 点击 "Bake Lightmaps" 开始烘焙
4. 烘焙完成后数据会自动应用

### 高级配置

1. 创建 `LightMapDefaultsAsset` 来管理默认设置
2. 使用不同的 `RecordShaderMode` 来控制着色器收集
3. 启用 `AttachToExistingLightmaps` 来与现有光照贴图合并

### 迁移工具

有两个迁移工具可供选择：

1. **完整迁移工具**: `Tools > Qinyou > LightMapSystem > Migration Tool`
   - 尝试迁移所有数据和设置
   - 使用反射技术访问旧组件数据
   - 可能需要手动调整某些设置

2. **简单迁移工具**: `Tools > Qinyou > LightMapSystem > Simple Migration Tool`
   - 只添加新的LightMapComponent组件
   - 不删除旧组件
   - 需要手动配置新组件的设置

## API 参考

### LightMapComponent 主要方法

```csharp
// 应用光照贴图
public void ApplyLightmaps(List<RendererData> rendererData, List<LightMapData> lightmapData, bool attachToExisting = false)

// 清除光照贴图
public void ClearLightmaps()

// 恢复原始设置
public void RestoreOriginalSettings()

// 刷新渲染器数据
public void RefreshRendererData()

// 刷新着色器列表
public void RefreshShaderList()
```

### LightMapBaker 事件

```csharp
// 烘焙完成事件
baker.OnBakeCompleted += (result) => { /* 处理结果 */ };

// 烘焙取消事件
baker.OnBakeCancelled += () => { /* 处理取消 */ };

// 烘焙错误事件
baker.OnBakeError += (error) => { /* 处理错误 */ };
```

## 兼容性

- Unity 2019.4 及以上版本
- 支持所有渲染管线 (Built-in, URP, HDRP)
- 向后兼容原始 LightMap 组件（通过迁移工具）

## 故障排除

### 常见问题

1. **烘焙失败**: 检查场景中是否有有效的光源和几何体
2. **材质未更新**: 确保着色器列表包含了所需的着色器
3. **预制体未保存**: 检查预制体是否处于编辑模式

### 调试技巧

1. 查看 Console 中的 `[LightMapSystem]` 日志
2. 使用 `Tools > Qinyou > LightMapSystem > System Tests` 运行测试
3. 使用迁移工具生成详细报告
4. 检查 LightMapDefaults 配置是否正确

## 版本历史

- **v2.0.0**: 完全重构，新的组件架构，独立文件夹结构
- **v1.x.x**: 原始版本 (已弃用，但保持兼容)

## 开发工具

### 菜单项

- `Tools > Qinyou > LightMapSystem > Migration Tool` - 完整迁移工具
- `Tools > Qinyou > LightMapSystem > Simple Migration Tool` - 简单迁移工具
- `Tools > Qinyou > LightMapSystem > System Tests` - 系统测试

### 创建菜单

- `Create > Qinyou > LightMapSystem > LightMap Defaults` - 创建默认设置资源

### 运行时测试

在任何包含 `LightMapSystemTest` 组件的GameObject上，可以通过右键菜单执行：
- `Test Basic Functionality` - 测试基本功能
- `Test Utility Methods` - 测试工具方法

## 贡献

如果发现问题或有改进建议，请：

1. 查看现有的日志输出
2. 运行系统测试工具
3. 创建详细的问题报告
4. 提供重现步骤和场景文件