Il2CppAssemblyUnhollower：构建IL2CPP代理程序集的实用指南

一、核心架构解析：如何理解项目的模块组成？

Il2CppAssemblyUnhollower作为Unity游戏逆向工程的关键工具，其架构设计如同精密的齿轮组，各模块协同工作将IL2CPP字节码转换为可交互的托管代码。项目采用分层设计，主要包含四大功能模块：元数据处理层、代码转换层、运行时支持层和辅助工具层。

1.1 项目目录结构概览

graph TD
    A[AssemblyUnhollower] -->|核心转换逻辑| A1(Contexts)
    A -->|处理流程| A2(Passes)
    A -->|工具类| A3(Utils)
    B[UnhollowerBaseLib] -->|基础类型| B1(Runtime)
    B -->|元数据映射| B2(Maps)
    C[UnhollowerPdbGen] -->|调试符号生成| C1(MsPdbCore)
    D[Documentation] -->|使用文档| D1(Command-Line-Usage.md)

1.2 关键模块功能解析

• AssemblyUnhollower：如同编译器的前端，负责解析IL2CPP元数据并执行代码转换。其中Passes目录下的20+个处理阶段（如Pass10CreateTypedefs创建类型定义、Pass50GenerateMethods生成方法体）构成了完整的编译流水线。

• UnhollowerBaseLib：作为运行时基石，提供Il2CppObjectBase等核心类型和ClassInjector等关键功能，相当于为生成的代理代码提供"操作系统"级别的支持。

• UnhollowerPdbGen：生成调试符号文件，其作用类似为机器添加"仪表盘"，使逆向分析者能在调试器中查看函数名和参数信息。

💡 小贴士：理解项目架构的快捷方式是查看AssemblyUnhollower/Program.cs中的Main方法，其中按顺序调用的PassXX系列方法清晰展示了代码转换的完整流程。

二、操作流程指南：如何从零开始生成代理程序集？

使用Il2CppAssemblyUnhollower就像组装家具——虽然零件众多，但按步骤操作就能顺利完成。以下是将IL2CPP程序集转换为托管代理的标准流程：

2.1 环境准备与前置工具

在开始前，请确保已准备好：

• 从Il2CppDumper获取的dummy assemblies（如同拆解家具所需的"零件图"）
• 目标运行时的mscorlib.dll（相当于"标准配件"）
• .NET Framework 4.7.2或更高版本环境

2.2 查找启动文件的3种方法

1. 解决方案入口法：打开AssemblyUnhollower.sln，启动项目通常标记为"启动项目"（默认是AssemblyUnhollower）
2. Program.cs定位法：在文件树中直接查找AssemblyUnhollower/Program.cs，包含Main方法的文件即为入口
3. csproj分析：查看.csproj文件中的<OutputType>Exe</OutputType>配置项确定可执行项目

2.3 基本命令执行步骤

# 1. 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/il/Il2CppAssemblyUnhollower

# 2. 构建项目（使用Visual Studio或dotnet CLI）
cd Il2CppAssemblyUnhollower
dotnet build

# 3. 执行转换命令
AssemblyUnhollower --input=<dummy目录> --output=<输出目录> --mscorlib=<mscorlib路径>

💡 小贴士：添加--verbose参数可查看详细处理过程，遇到问题时这是重要的调试手段。对于大型项目，建议使用--blacklist-assembly排除不需要处理的程序集以提高速度。

三、配置实践手册：如何优化工具参数设置？

Il2CppAssemblyUnhollower提供了丰富的配置选项，如同专业相机的参数调节，合理设置能显著提升转换质量和效率。

3.1 快速导航：关键配置文件与功能

文件路径	功能描述
AssemblyUnhollower/UnhollowerOptions.cs	定义所有可配置参数的数据结构
Documentation/Command-Line-Usage.md	完整命令行参数说明
UnhollowerBaseLib/UnityVersionHandler.cs	Unity版本兼容性配置
AssemblyUnhollower/Program.cs	参数解析与处理流程控制

3.2 常见配置项对比表

配置场景	推荐参数	效果说明
标准转换	--input=... --output=... --mscorlib=...	基础转换，适用于大多数情况
处理混淆代码	--obf-regex="^[a-zA-Z0-9]{1,4}$" --deobf-uniq-chars=3	重命名短名称标识符，提升可读性
性能优化	--blacklist-assembly=UnityEngine --no-xref-cache	排除Unity引擎程序集，禁用交叉引用缓存
调试支持	--verbose	输出详细处理日志，便于问题定位

3.3 高级配置技巧

• 重命名映射：通过--rename-map=map.txt导入自定义重命名规则，格式为原名称;新名称
• 命名空间前缀：使用--add-prefix-to=UnityEngine为特定命名空间添加Il2Cpp前缀避免冲突
• Unity版本适配：调用UnityVersionHandler.Initialize("2020.3.0")设置目标Unity版本

💡 小贴士：当处理大型项目时，建议先使用--deobf-analyze参数分析最优的混淆处理参数，格式如下：

AssemblyUnhollower --input=... --deobf-analyze

该命令会输出不同--deobf-uniq-chars和--deobf-uniq-max组合的去混淆效果数据。

四、技术原理揭秘：工具如何实现IL2CPP与托管代码的桥接？

Il2CppAssemblyUnhollower的核心价值在于构建了IL2CPP原生代码与.NET托管环境之间的"翻译器"。这个过程涉及两个关键技术：元数据重映射和方法体生成。

4.1 元数据重映射机制

如同外交翻译需要建立词汇对照表，工具通过RewriteGlobalContext维护IL2CPP类型与托管类型的映射关系。在Pass10CreateTypedefs阶段，系统会为每个IL2CPP类型创建对应的C#类型定义，并处理名称冲突（如添加_Il2Cpp后缀）。

4.2 方法体生成策略

生成的代理方法采用"间接调用"模式，类似电话转接系统：

1. 托管代码调用代理方法
2. 代理方法通过IL2CPP类的静态方法（如il2cpp_method_get_from_reflection_data）获取原生函数指针
3. 使用Marshal.GetDelegateForFunctionPointer创建委托并调用

关键代码示例（简化版）：

// 生成的代理方法
public void SetActive(bool value) {
    IL2CPP.il2cpp_runtime_invoke(
        methodPtr, this.Pointer, new IntPtr[] { value ? (IntPtr)1 : (IntPtr)0 }, 
        out var exception
    );
    if (exception != IntPtr.Zero) throw new Il2CppException(exception);
}

4.3 跨域内存管理

工具通过Il2CppObjectBase实现托管对象与IL2CPP对象的生命周期绑定，这是一种双向引用机制：

• 托管对象持有IL2CPP对象的指针（IntPtr Pointer字段）
• IL2CPP对象通过GC句柄引用托管对象

这种设计解决了跨运行时内存管理的难题，但需注意避免创建引用循环（如IL2CPP列表包含自身引用）。

💡 小贴士：理解生成代码的最佳方式是查看输出目录中的Il2CppSystem.Object.cs等基础类型文件，这些文件展示了IL2CPP类型如何被映射为C#类。

五、常见问题诊断：如何解决转换过程中的典型错误？

即使遵循标准流程，转换过程中仍可能遇到各种问题。以下是三类常见错误的诊断与解决方法：

5.1 元数据解析错误

症状：CecilMetadataAccess抛出异常，提示"Invalid metadata token" 原因：dummy assemblies损坏或版本不匹配 解决：

1. 使用最新版Il2CppDumper重新生成dummy文件
2. 检查--mscorlib参数是否指向正确版本的运行时库

5.2 方法生成失败

症状：日志中出现"Failed to generate method body"警告 原因：复杂泛型方法或非 blittable 类型处理不支持 解决：

1. 使用--blacklist-assembly排除问题程序集
2. 尝试添加--no-xref-cache禁用交叉引用分析

5.3 运行时类型转换异常

症状：运行时抛出InvalidCastException 原因：IL2CPP类型必须使用专用转换方法 解决：

1. 将C#风格转换(TargetType)obj替换为obj.Cast<TargetType>()
2. 使用Il2CppType.Of<T>()替代typeof(T)获取IL2CPP类型

💡 小贴士：项目文档Documentation/Common-Problems.md维护了已知问题列表，遇到错误时建议先查阅该文件。对于复杂问题，可尝试在命令中添加--verbose获取详细日志。

通过本文的指南，您应该能够掌握Il2CppAssemblyUnhollower的核心功能和使用方法。无论是逆向分析还是插件开发，这个工具都能为您架起通往IL2CPP世界的桥梁。记住，如同任何强大的工具，熟练掌握它需要实践和耐心，但一旦掌握，您将获得操控IL2CPP程序集的强大能力。