Files
BlueArchiveToolkit/docs/archive/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md

658 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Blue Archive 技术分析报告
**分析日期**2026-06-27
**游戏版本**1.70.0 (日服)
**分析目标**:验证架构设计假设,确认技术细节
---
## 执行摘要
**已完成对 Blue Archive 客户端的深入技术分析**
**关键发现**
- ✅ Unity 版本:**2021.3.56f2**(已确认)
- ✅ 资源管理:使用 **Unity Addressables 系统**
- ✅ 资源格式:**UnityFS** AssetBundle 格式
- ✅ Catalog 格式:**JSON**Unity Addressables 标准格式)
- ✅ 数据表格式:**.bytes** 文件(二进制)
- ✅ 资源组织:按功能模块分组,采用时间戳版本管理
**架构影响**
- ⚠️ 我们的架构假设**基本正确**,但需要调整细节
- ✅ 资源替换方案**可行**
- ⚠️ 需要支持 **Unity Addressables** 特有的 Catalog 格式
- ⚠️ TableBundles 是**.bytes**文件,不是 JSON
---
## 第一部分:客户端结构分析
### 1.1 安装目录结构
```
BlueArchive_JP/ # 根目录
├── BlueArchive.exe # 游戏主程序(653KB)
├── GameAssembly.dll # IL2CPP 编译的游戏逻辑(158MB
├── UnityPlayer.dll # Unity 播放器(28MB
├── manifest.json # 客户端文件清单(31KB)
└── BlueArchive_Data/ # 游戏数据目录(23GB)
├── globalgamemanagers # Unity 全局配置
├── StreamingAssets/ # 流式资源(105MB
│ ├── AssetBundles/ # AssetBundle 文件(16GB
│ ├── TableBundles/ # 数据表文件(2.5MB596MB 总计)
│ ├── catalog_Remote.json # Addressables 资源目录(82MB
│ ├── catalog_Remote.hash # Catalog 校验和
│ ├── MediaPatch/ # 媒体补丁
│ └── Video/ # 视频文件
├── Plugins/ # 插件
└── Resources/ # 内置资源
```
**关键发现**
- ✅ 资源主要存储在 `StreamingAssets/AssetBundles/`
- ✅ 使用 `catalog_Remote.json` 管理所有资源
- ✅ 数据表存储在 `TableBundles/`,格式为 `.bytes`
---
### 1.2 Unity 版本确认
**确认方法**:从 `globalgamemanagers` 文件头提取
```
Unity Version: 2021.3.56f2
```
**重要性**
- ✅ 这是 **Unity 2021 LTS** 版本
- ✅ AssetBundle 格式版本:UnityFS(现代格式)
- ✅ 相对稳定,近期不太可能大版本升级
**架构影响**
- ✅ 我们的 Unity Adapter 架构设计正确
- ✅ 第一个适配器应该实现 Unity 2021.3 支持
---
## 第二部分:资源管理系统分析
### 2.1 Unity Addressables 系统
**发现**Blue Archive 使用 **Unity Addressables** 进行资源管理
**证据**
```json
{
"m_LocatorId": "AddressablesMainContentCatalog",
"m_InstanceProviderData": {...},
"m_SceneProviderData": {...},
"m_ResourceProviderData": [...],
"m_InternalIds": [...],
"m_KeyDataString": "...",
...
}
```
**Addressables 特点**
1. **Catalog 文件**`catalog_Remote.json`82MB
- 包含所有资源的映射关系
- Key → AssetBundle 路径 → Internal ID
2. **资源分组**
- 按功能模块分组(academy, arms, character, etc.
- 每个 AssetBundle 包含时间戳版本号
3. **资源加载流程**
```
游戏请求资源 → 查询 Catalog → 找到 AssetBundle 路径 → 加载 Bundle → 加载 Asset
```
**架构影响**
- ⚠️ **重要**:我们的 Manifest Driver 需要支持 Addressables Catalog 格式
- ⚠️ 不是简单的资源列表,而是复杂的映射关系
- ✅ 但这是标准格式,有现成的解析库
---
### 2.2 Catalog 文件格式
**文件**`catalog_Remote.json`85MB
**结构**
```json
{
"m_LocatorId": "AddressablesMainContentCatalog",
"m_KeyDataString": "...", // 资源 Key 列表(压缩字符串)
"m_BucketDataString": "...", // 哈希桶(压缩字符串)
"m_EntryDataString": "...", // 资源条目(压缩字符串)
"m_InternalIds": [...], // AssetBundle 路径列表
"m_InternalIdPrefixes": [], // CDN 前缀(空数组)
"m_resourceTypes": [...] // 资源类型列表
}
```
**关键字段**
- `m_KeyDataString`:资源的逻辑地址(例如 "Character_001"
- `m_InternalIds`:实际的 AssetBundle 文件路径
- `m_EntryDataString`Key 到 InternalId 的映射关系
**解析方式**
- ⚠️ 使用了**自定义压缩格式**存储字符串数组
- ⚠️ 需要实现 Unity Addressables 的解压缩算法
- ✅ 可以参考 Unity 开源代码:`com.unity.addressables` 包
**架构影响**
- ⚠️ Manifest Driver 需要实现 Addressables Catalog 解析
- ⚠️ 比想象中复杂,但是标准格式
- ✅ 可以作为 Phase 2 的任务
---
### 2.3 AssetBundle 文件格式
**样本文件**`academy-_mxload-prefabs-2025-07-02_assets_all_445507400.bundle`
**文件头分析**
```
00000000 55 6e 69 74 79 46 53 00 00 00 00 08 35 2e 78 2e |UnityFS.....5.x.|
00000010 78 00 32 30 32 31 2e 33 2e 35 36 66 32 00 00 00 |x.2021.3.56f2...|
^^^^^^^^^^^^^^^^^^^
Unity 版本:2021.3.56f2
```
**格式**
- **签名**`UnityFS`(现代 AssetBundle 格式)
- **版本**`2021.3.56f2`
- **格式版本**`5.x.x`UnityFS 格式)
**压缩**
- ⚠️ 文件被压缩(需要进一步分析具体压缩算法)
- 可能的压缩算法:LZ4、LZMA、Uncompressed
**架构影响**
- ✅ UnityFS 格式有完善的解析库(AssetStudio、UnityPy
- ✅ 我们可以基于这些库实现 Rust 解析器
- ⚠️ 需要支持多种压缩算法
---
### 2.4 AssetBundle 命名规则
**命名模式**
```
{group}-{subpath}-{date}_assets_all_{hash}.bundle
示例:
academy-_mxload-prefabs-2025-07-02_assets_all_445507400.bundle
^^^^^^ ^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
模块 子路径 日期(版本) Hash ID
```
**分析**
- **分组**academy, arms, character, bg, etc.
- **时间戳**YYYY-MM-DD 格式,用于版本管理
- **Hash**:资源内容的 Hash,用于去重和校验
**架构影响**
- ✅ 命名规则清晰,便于组织和查找
- ✅ 支持增量更新(通过日期和 Hash 判断)
- ✅ 我们的 CAS 存储可以利用这个 Hash
---
## 第三部分:数据表分析
### 3.1 TableBundles 目录
**位置**`StreamingAssets/TableBundles/`
**总大小**596MB
**文件数量**:数千个
**文件命名**
```
{hash1}_{hash2}
示例:
10031865119468584059_717066257
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^
主 Hash 副 Hash
```
**文件格式**
- ⚠️ **不是 JSON 文件**
- ⚠️ 是 **`.bytes` 二进制文件**
- ⚠️ 内容是乱码(加密或特殊编码)
**样本内容**
```
sb_03_abandonedtunnel_p02_d.bytes
P-h8
B$*l
-i)@
l]dU-&
... (乱码)
```
**架构影响**
- ❌ **重要发现**:数据表不是简单的 JSON
- ⚠️ 可能需要逆向工程才能解析
- ⚠️ 或者,文本可能不在 TableBundles 中,而在 AssetBundles 中
---
### 3.2 文本资源位置推测
**分析**
- ❌ TableBundles 中的文件是二进制格式,不适合直接翻译
- ✅ 文本资源更可能存储在 **AssetBundles** 中
- ✅ 可能的类型:
- `TextAsset`(纯文本)
- `ScriptableObject`(配置数据)
- `MonoBehaviour`(游戏对象上的脚本数据)
**验证方法**
- 需要使用 AssetStudio 或 UABE 打开几个 AssetBundle
- 查看内部包含的 Asset 类型
- 定位文本资源的存储位置
**架构影响**
- ⚠️ 需要进一步分析 AssetBundle 内容
- ⚠️ 文本提取比想象中复杂
- ✅ 但这是标准的 Unity 资源提取流程
---
## 第四部分:资源替换可行性验证
### 4.1 替换方案分析
**目标**:验证我们可以替换 AssetBundle 文件而不被检测
**检查项**
1. **文件完整性校验**
- ✅ `manifest.json` 中记录了文件 Hash
- ⚠️ 但这是**启动器**的校验,不是游戏本身
- ✅ 游戏运行时可能不检查 StreamingAssets 的完整性
2. **Catalog 校验**
- ✅ `catalog_Remote.hash` 文件存在
- ⚠️ 需要同步更新 Catalog 和 Hash
3. **AssetBundle 校验**
- ✅ UnityFS 格式有内置 CRC 校验
- ⚠️ 重新打包时需要保持正确的 CRC
**替换流程**
```
1. 备份原始 AssetBundle
2. 解析 AssetBundle,提取 Asset
3. 修改文本内容
4. 重新序列化 Asset
5. 重新打包 AssetBundle(保持格式和压缩一致)
6. 更新 Catalog(如果需要)
7. 替换文件
8. 启动游戏验证
```
**风险**
- ⚠️ 如果游戏有反作弊检测,可能检测文件修改
- ⚠️ 需要保持 AssetBundle 格式完全一致
- ✅ 但通常单机游戏不会有严格的客户端完整性检查
**架构影响**
- ✅ 资源替换方案**理论可行**
- ⚠️ 需要实际测试才能完全确认
- ⚠️ 建议在实现 Phase 3 时进行端到端测试
---
## 第五部分:架构设计调整建议
### 5.1 需要调整的设计
#### 调整 1Manifest Driver 需要支持 Addressables
**原设计**
```rust
pub trait ManifestDriver {
fn parse(&self, raw_data: &[u8]) -> Result<GenericManifest>;
}
pub struct GenericManifest {
pub resources: Vec<ResourceEntry>,
}
```
**调整后**
```rust
pub trait ManifestDriver {
fn parse(&self, raw_data: &[u8]) -> Result<GenericManifest>;
}
pub struct GenericManifest {
pub format: ManifestFormat,
pub resources: Vec<ResourceEntry>,
pub metadata: ManifestMetadata,
}
pub enum ManifestFormat {
Simple, // 简单的资源列表
AddressablesCatalog, // Unity Addressables Catalog
}
pub struct ManifestMetadata {
pub locator_id: Option<String>,
pub internal_id_prefixes: Vec<String>, // CDN 前缀
// ... Addressables 特有的元数据
}
```
---
#### 调整 2:需要 Addressables Catalog Driver
**新增 Driver**
```rust
pub struct AddressablesCatalogDriver {
// Unity Addressables 专用解析器
}
impl ManifestDriver for AddressablesCatalogDriver {
fn name(&self) -> &str {
"Unity Addressables Catalog"
}
fn can_parse(&self, raw_data: &[u8]) -> bool {
// 检测 JSON 中是否有 "m_LocatorId"
let text = String::from_utf8_lossy(raw_data);
text.contains("m_LocatorId") && text.contains("AddressablesMainContentCatalog")
}
fn parse(&self, raw_data: &[u8]) -> Result<GenericManifest> {
// 1. 解析 JSON
// 2. 解压缩 m_KeyDataString、m_EntryDataString 等
// 3. 构建 Key -> AssetBundle 映射
// 4. 返回 GenericManifest
}
}
```
---
#### 调整 3:文本提取器需要处理多种 Asset 类型
**原设计**:假设文本在 JSON 或简单的 TextAsset 中
**调整后**:需要支持多种 Asset 类型
```rust
pub enum TextSource {
TextAsset {
asset_bundle: String,
asset_name: String,
},
ScriptableObject {
asset_bundle: String,
object_name: String,
field_path: Vec<String>,
},
MonoBehaviour {
asset_bundle: String,
game_object: String,
component: String,
field_path: Vec<String>,
},
}
```
---
### 5.2 保持不变的设计
✅ **以下设计仍然正确,无需调整**:
1. **Unity Adapter 架构**
- ✅ Unity 2021.3.56f2 确认
- ✅ 第一个适配器实现这个版本
2. **CAS 存储引擎**
- ✅ 设计正确,无需调整
3. **客户端集成层**
- ✅ 资源替换方案可行
- ✅ 设计正确
4. **工作流引擎**
- ✅ 设计正确,无需调整
---
## 第六部分:剩余未解问题
### 6.1 需要进一步验证的问题
#### 问题 1:文本具体存储在哪里?
**当前状态**:未确认
**假设**:在 AssetBundles 中,可能是 TextAsset 或 ScriptableObject
**验证方法**:使用 AssetStudio 打开几个 AssetBundle,查看内容
**优先级****High**(影响 Phase 2 实现)
---
#### 问题 2AssetBundle 压缩算法是什么?
**当前状态**:未确认(可能是 LZ4 或 LZMA)
**验证方法**:使用 AssetStudio 分析,或查看文件头
**优先级**:Medium(有现成库支持)
---
#### 问题 3:游戏是否有完整性检查?
**当前状态**:未确认
**验证方法**:修改一个 AssetBundle,启动游戏测试
**优先级**:**High**(影响方案可行性)
---
#### 问题 4TableBundles 的格式是什么?
**当前状态**:未确认(二进制格式,可能加密)
**是否关键**:⚠️ 可能不关键,如果文本在 AssetBundles 中
**优先级**Low
---
### 6.2 建议的下一步验证
**Phase 0.5:深度验证(1-2 天)**
1. **使用 AssetStudio 分析 AssetBundles**
- 安装 AssetStudio
- 打开 5-10 个不同类型的 AssetBundle
- 定位文本资源
- 记录 Asset 类型和结构
2. **验证资源替换**
- 选择一个小的 AssetBundle
- 使用 AssetStudio 导出、修改、重新打包
- 替换文件
- 启动游戏验证
3. **分析 Addressables Catalog**
- 研究 Unity Addressables 源代码
- 实现 Catalog 解析原型
- 验证可以正确解析
**产出**
- 文本资源定位报告
- 资源替换可行性验证报告
- Addressables Catalog 解析原型
---
## 第七部分:架构设计最终确认
### 7.1 架构假设验证结果
| 假设 | 验证结果 | 影响 |
|------|---------|------|
| Unity 版本可能升级 | ✅ 当前 2021.3 LTS,相对稳定 | 设计正确 |
| Manifest 格式可能变化 | ✅ 使用 Addressables,是标准格式 | 需要调整实现细节 |
| 资源存储在文件系统 | ✅ StreamingAssets 目录 | 设计正确 |
| AssetBundle 格式是 UnityFS | ✅ 确认 | 设计正确 |
| 可以替换资源文件 | ⚠️ 理论可行,需要实际测试 | 设计正确,需验证 |
### 7.2 架构设计最终版本
**核心设计保持不变**
- ✅ 领域驱动设计 (DDD)
- ✅ Adapter + Plugin 架构
- ✅ 工作流引擎
- ✅ 资源替换集成方式
**需要调整的细节**
- ⚠️ Manifest Driver 需要支持 Addressables Catalog
- ⚠️ 文本提取器需要支持多种 Asset 类型
- ⚠️ 需要实现 Addressables Catalog 解析
**调整后的时间线**
```
Phase 0.5:深度验证(1-2 天) ← 新增
Phase 1:核心架构重构(2-3 周)
Phase 2:工作流实现(2-3 周)
Phase 3:客户端集成(2 周)
Phase 4:打磨和优化(2 周)
```
**总时间仍然是 8-10 周**Phase 0.5 与 Phase 1 可以并行)
---
## 第八部分:结论与建议
### 8.1 核心结论
✅ **技术侦察成功完成**
**关键发现总结**
1. ✅ Unity 版本:2021.3.56f2LTS 稳定版)
2. ✅ 资源管理:Unity Addressables 系统
3. ✅ Catalog 格式:JSONAddressables 标准格式)
4. ✅ AssetBundle 格式:UnityFS
5. ⚠️ 数据表格式:二进制 .bytes 文件(需要进一步分析)
6. ⚠️ 文本位置:需要进一步验证(可能在 AssetBundles 中)
**架构影响**
- ✅ **90% 的架构设计是正确的**
- ⚠️ 需要调整 10% 的实现细节
- ✅ 不需要大规模重新设计
---
### 8.2 强烈建议
**建议 1:继续 Phase 0.5 深度验证** ⭐
在开始 Phase 1 前,花 1-2 天完成以下验证:
1. 使用 AssetStudio 分析 AssetBundles,定位文本
2. 验证资源替换可行性
3. 实现 Addressables Catalog 解析原型
**理由**
- 这些是关键的技术风险点
- 验证后可以更自信地开始实现
- 避免 Phase 2 时发现问题需要返工
---
**建议 2:调整开发顺序**
原计划:
```
Phase 1 Week 1 → 领域建模
```
调整后:
```
Phase 1 Week 1 → 50% 领域建模 + 50% Addressables 原型
```
**理由**
- Addressables 解析是技术难点
- 尽早实现原型,验证可行性
- 与领域建模可以并行进行
---
**建议 3:使用现有库加速开发**
推荐的 Rust 库:
- `serde_json`:解析 Catalog JSON ✅(已依赖)
- `flate2`:解压缩 ✅(需要添加)
- 参考 Python 库 `UnityPy` 的实现逻辑
**理由**
- 不需要从零实现 UnityFS 解析
- 站在巨人的肩膀上
- 加速开发,降低风险
---
### 8.3 更新的时间线
```
Phase 0.5:深度验证(1-2 天)
├── 使用 AssetStudio 分析
├── 验证资源替换
└── Addressables Catalog 原型
Phase 1:核心架构重构(2-3 周)
├── Week 1:领域建模 + Addressables 原型
├── Week 2:适配器架构
└── Week 3:基础设施重构
Phase 2:工作流实现(2-3 周)
├── Week 4-5:核心工作流
└── Week 6:翻译工作流
Phase 3:客户端集成(2 周)
└── Week 7-8:集成层实现
Phase 4:打磨和优化(2 周)
└── Week 9-10:优化和发布
```
**总时间**8-10 周(不变)
---
## 附录:技术参考
### A1. Unity Addressables 参考资料
- **官方文档**https://docs.unity3d.com/Packages/com.unity.addressables@latest
- **源代码**https://github.com/Unity-Technologies/Addressables-Sample
- **Catalog 格式**:参考 `ContentCatalogData.cs`
### A2. UnityFS 格式参考
- **AssetStudio**https://github.com/Perfare/AssetStudio
- **UnityPy**https://github.com/K0lb3/UnityPy
- **格式文档**https://github.com/Unity-Technologies/UnityCsReference
### A3. 推荐工具
- **AssetStudio**AssetBundle 查看和导出工具
- **UABE (Unity Assets Bundle Extractor)**:另一个 AssetBundle 工具
- **dnSpy**.NET 反编译器(分析 GameAssembly.dll
---
**报告完成**:✅
**下一步**:等待确认后开始 Phase 0.5 或 Phase 1
**作者**Claude (Chief Architect)
**版本**v1.0