# Gakumas纹理替换功能融合说明

## 概述

本项目已成功将 `gakumas-texture-TL` 项目的纹理替换功能完整集成到主项目中。现在只需要使用 `version.dll` 一个文件即可同时实现文字翻译和纹理替换功能。

## 主要改动

### 1. 新增模块

#### TextureReplace模块 (`src/GakumasLocalify/TextureReplace.h/cpp`)
- 负责纹理替换的核心功能
- 包含资源映射配置加载
- 图片文件加载和Unity Texture2D对象创建
- 待替换请求管理

### 2. Hook集成

#### 修改 `src/GakumasLocalify/Hook.cpp`
- 在 `AssetBundle_LoadAssetAsync` Hook中添加纹理替换检测
- 在 `AssetBundleRequest_GetResult` Hook中返回替换后的纹理
- 在初始化流程中调用 `TextureReplace::Initialize()`

### 3. 配置系统

#### Config配置项 (`src/GakumasLocalify/config/`)
- 添加 `enableTextureReplace` 配置项
- 在 `Config.hpp` 中声明
- 在 `Config.cpp` 中实现加载和保存

### 4. 资源目录结构

```
resource/local-files/textures/
├── asset_mapping.txt       # 资源映射配置文件
├── comic/                  # 漫画图片
│   ├── 1ko/               # 一格漫画
│   └── 4ko/               # 四格漫画
├── general_report/        # 好感度偶像档案
├── ui/                    # UI按钮图片
└── tutorial/              # 教程图片
```

## 使用方法

### 1. 启用纹理替换功能

编辑 `resource/localizationConfig.json`，添加或修改:
```json
{
  "enableTextureReplace": true
}
```

### 2. 配置资源映射

编辑 `resource/local-files/textures/asset_mapping.txt`:
```
# 格式: assetId=本地文件路径
img_general_comic_0001=comic/1ko/img_general_comic_0001.png
img_general_comic4_0000=comic/4ko/img_general_comic4_0000.png
img_general_report_akapen_amao-001=general_report/amao/img_general_report_akapen_amao-001.png
```

### 3. 放置图片文件

将替换用的图片文件放置到对应的子目录中:
- `comic/1ko/` - 一格漫画
- `comic/4ko/` - 四格漫画
- `general_report/` - 好感度档案
- `ui/` - UI按钮
- `tutorial/` - 教程图片

### 4. 启动游戏

只需要将编译生成的 `version.dll` 放到游戏目录即可,无需其他DLL文件。

## 技术细节

### Hook工作流程

1. **AssetBundle_LoadAssetAsync Hook**
   - 拦截Unity的资源加载请求
   - 检查资源名称是否在映射表中
   - 如果需要替换,加载本地图片文件
   - 创建Unity Texture2D对象
   - 将替换信息存储到待处理映射表中

2. **AssetBundleRequest_GetResult Hook**
   - 拦截Unity获取加载结果的请求
   - 检查是否有待替换的纹理
   - 如果有,返回替换后的纹理对象
   - 否则返回原始资源

3. **自动清理机制**
   - 每30秒自动清理超时(60秒)的待处理请求
   - 防止内存泄漏

### IL2CPP API使用

通过动态获取IL2CPP函数指针实现:
- `il2cpp_domain_get` - 获取应用域
- `il2cpp_class_from_name` - 查找类
- `il2cpp_object_new` - 创建对象
- `il2cpp_runtime_invoke` - 调用方法

### 与xinput1_3.dll版本的区别

| 特性 | xinput1_3.dll版本 | version.dll集成版本 |
|------|-------------------|---------------------|
| DLL数量 | 2个 (version.dll + xinput1_3.dll) | 1个 (version.dll) |
| 功能集成 | 分离 | 统一 |
| 配置管理 | 独立配置 | 统一配置系统 |
| 日志系统 | 独立日志 | 统一日志系统 |
| 维护性 | 需要维护两套代码 | 单一代码库 |

## 迁移指南

如果你之前使用xinput1_3.dll版本:

1. 备份你的图片文件和 `asset_mapping.txt`
2. 将 `asset_mapping.txt` 复制到 `resource/local-files/textures/`
3. 将所有图片文件按目录结构复制到 `resource/local-files/textures/` 对应子目录
4. 在 `resource/localizationConfig.json` 中设置 `"enableTextureReplace": true`
5. 删除游戏目录中的 `xinput1_3.dll`
6. 使用新编译的 `version.dll` 替换原有的文件

## 注意事项

1. **性能影响**: 纹理替换只对配置文件中列出的资源生效,不会影响其他资源的加载性能

2. **图片格式**: 支持PNG、JPG等Unity支持的常见图片格式

3. **路径分隔符**: 在 `asset_mapping.txt` 中,可以使用正斜杠(/)或反斜杠(\\)

4. **日志输出**: 纹理替换相关的日志会输出到控制台和日志文件中,前缀为 "TextureReplace:"

5. **错误处理**: 如果本地文件不存在或加载失败,会自动使用游戏原始资源

## 调试

启用调试模式查看详细日志:
```json
{
  "enableConsole": true,
  "dbgMode": true,
  "enableTextureReplace": true
}
```

日志会显示:
- 初始化过程
- 加载的映射数量
- 每次资源替换的详细信息
- 错误和警告信息

## 常见问题

**Q: 纹理没有被替换?**
A: 检查以下几点:
1. `enableTextureReplace` 是否设置为 `true`
2. `asset_mapping.txt` 中的资源ID是否正确
3. 图片文件是否存在于指定路径
4. 查看日志输出是否有错误信息

**Q: 游戏启动后控制台显示什么?**
A: 如果启用纹理替换,会看到:
```
TextureReplace: Initializing texture replacement system...
TextureReplace: Created texture directories at: ...
TextureReplace: IL2CPP API initialized successfully
TextureReplace: Loaded X asset mappings
TextureReplace: Texture replacement system initialized successfully
```

**Q: 可以动态添加新的替换图片吗?**
A: 可以,修改 `asset_mapping.txt` 并添加新图片后,重启游戏即可生效

## 开发者信息

- 原xinput1_3版本: gakumas-texture-TL项目
- 集成版本: 本项目
- 集成时间: 2025年11月26日

## 技术支持

如遇到问题,请:
1. 检查日志输出
2. 确认配置文件格式正确
3. 验证图片文件可以正常打开
4. 查看游戏目录权限设置