nyaKazuha/BlueArchiveToolkit
1
0
Fork 0
mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-07-22 06:56:44 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
1bcb9c828a99a769dbfdea5482ac9ab1b1b2f93e
BlueArchiveToolkit/docs/archive/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md
T

18 KiB
Raw Blame History

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.5MB，596MB 总计）
    │   ├── 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 进行资源管理

证据：

{
  "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）

结构：

{
  "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 需要调整的设计

调整 1：Manifest Driver 需要支持 Addressables

原设计：

pub trait ManifestDriver {
    fn parse(&self, raw_data: &[u8]) -> Result<GenericManifest>;
}

pub struct GenericManifest {
    pub resources: Vec<ResourceEntry>,
}

调整后：

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：

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 类型

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 实现）

问题 2：AssetBundle 压缩算法是什么？

当前状态：未确认（可能是 LZ4 或 LZMA）
验证方法：使用 AssetStudio 分析，或查看文件头
优先级：Medium（有现成库支持）

问题 3：游戏是否有完整性检查？

当前状态：未确认
验证方法：修改一个 AssetBundle，启动游戏测试
优先级：High（影响方案可行性）

问题 4：TableBundles 的格式是什么？

当前状态：未确认（二进制格式，可能加密）
是否关键：⚠️ 可能不关键，如果文本在 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.56f2（LTS 稳定版）
  2. ✅ 资源管理：Unity Addressables 系统
  3. ✅ Catalog 格式：JSON（Addressables 标准格式）
  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 参考资料

A2. UnityFS 格式参考

A3. 推荐工具

  • AssetStudio：AssetBundle 查看和导出工具
  • UABE (Unity Assets Bundle Extractor)：另一个 AssetBundle 工具
  • dnSpy：.NET 反编译器（分析 GameAssembly.dll）

报告完成：✅
下一步：等待确认后开始 Phase 0.5 或 Phase 1
作者：Claude (Chief Architect)
版本：v1.0

Reference in New Issue View Git Blame Copy Permalink