forked from chinosk/gkms-localify-dmm
192 lines
5.6 KiB
Markdown
192 lines
5.6 KiB
Markdown
# 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. 查看游戏目录权限设置
|