Batchhh/il2cpp-bridge-rs
GitHub: Batchhh/il2cpp-bridge-rs
一个 Rust 编写的高性能 IL2CPP 运行时桥接库，用于从原生代码中解析 Unity 类型、调用方法和操作对象。
Stars: 1 | Forks: 0
# il2cpp-bridge-rs
`il2cpp-bridge-rs` 是一个 Rust 库，用于从 native 代码中探索和交互 Unity 的 IL2CPP runtime。它在运行时解析 IL2CPP 导出，构建 metadata 缓存，并为常见任务（如类查找、方法调用、metadata 导出和 Unity 对象访问）暴露了人性化的封装。
## 适用人群
本 crate 面向已经在 Unity 和 IL2CPP 已加载的 native 环境中工作的工程师：
- native 插件和注入库
- 运行时工具和诊断
- IL2CPP 内省工具
- 基于原始 IL2CPP metadata 构建的 Unity 封装
如果你需要一个通用的 Unity mod 加载器或独立的游戏补丁框架，这个 crate 是一个构建块，而不是一个完整的解决方案。
## 运行时假设
在使用 API 之前，请记住以下约束：
- 当前进程中必须已加载活动的 IL2CPP runtime。
- 在依赖缓存支持的查找（如 `api::cache::csharp()`）之前，必须调用 [`init`](src/init.rs)。
- 许多操作最终都会处理原始指针和 runtime 拥有的内存。该 crate 减少了易错点，但并没有使 IL2CPP 集成完全安全。
- 方法调用、字段访问和对象封装仅在目标 Unity runtime 处于活动状态且与预期的 metadata 兼容时才有意义。
- 某些操作需要当前线程附加到 IL2CPP VM。当你在初始化回调之外进行工作时，请使用 `api::Thread`。
## 安装
```
cargo add il2cpp-bridge-rs
```
## 构建与验证
仓库包含一个包含常见工作流的 `Makefile`：
```
make build
make check
make clippy
make doc
```
还提供了特定平台的 target，包括 `make build-ios`、`make build-macos`、`make build-linux`、`make build-android` 和 `make build-windows`。
## 首次成功流程
下面的代码片段展示了预期的顺畅路径：初始化 runtime，获取缓存的 assembly，解析类，检查方法，并在对象可用时调用实例方法。
此示例仅用于说明。它可以作为 Rust 代码编译，但需要一个活动的 Unity IL2CPP runtime 才能执行任何有用的操作。
```
use il2cpp_bridge_rs::{api, init};
use std::ffi::c_void;
init("GameAssembly", || {
let asm = api::cache::csharp();
let player_class = asm
.class("PlayerController")
.expect("PlayerController should exist after cache hydration");
let damage_method = player_class
.method(("TakeDamage", ["System.Single"]))
.expect("TakeDamage(float) should exist");
println!(
"Resolved {}::{} at RVA 0x{:X}",
player_class.name,
damage_method.name,
damage_method.rva
);
if let Some(player) = player_class.find_objects_of_type(false).into_iter().next() {
let bound_method = player
.method(("TakeDamage", ["System.Single"]))
.expect("instance method should bind automatically");
let damage: f32 = 25.0;
unsafe {
let _: Result<(), _> =
bound_method.call(&[&damage as *const f32 as *mut c_void]);
}
}
});
```
## 文档地图
Markdown 指南解释了工作流和注意事项。生成的 rustdoc 应被视为确切签名的真实来源。
- [入门指南](docs/getting-started.md)
- [核心工作流](docs/core-workflows.md)
- [平台与运行时说明](docs/platform-support.md)
- [架构](docs/architecture.md)
- [API 地图](docs/api-reference.md)
要在本地构建 rustdoc：
```
cargo doc --no-deps
```
## 主要入口点
大多数用户会首先在这些 API 上花费时间：
- `init`
- `api::cache`
- `api::Thread`
- `api::invoke_method`
- dump 辅助工具，如 `api::dump` 和 `api::dump_all_to`
- 封装器，如 `api::Application` 和 `api::Time`
- `structs` 下的 metadata 和对象封装
## 支持的目标
该项目目前提供以下构建目标：
- iOS: `aarch64-apple-ios`
- macOS: `aarch64-apple-darwin`
- Linux: `x86_64-unknown-linux-gnu`
- Android: `aarch64-linux-android`
- Windows: `x86_64-pc-windows-msvc`
有关符号解析详细信息、目标镜像命名指南以及线程/runtime 注意事项，请参阅 [平台与运行时说明](docs/platform-support.md)。
## 贡献
贡献期望和本地开发工作流记录在 [CONTRIBUTING.md](CONTRIBUTING.md) 中。
## 许可证
[MIT](LICENSE)
`il2cpp-bridge-rs` 是一个 Rust 库，用于从 native 代码中探索和交互 Unity 的 IL2CPP runtime。它在运行时解析 IL2CPP 导出，构建 metadata 缓存，并为常见任务（如类查找、方法调用、metadata 导出和 Unity 对象访问）暴露了人性化的封装。
## 适用人群
本 crate 面向已经在 Unity 和 IL2CPP 已加载的 native 环境中工作的工程师：
- native 插件和注入库
- 运行时工具和诊断
- IL2CPP 内省工具
- 基于原始 IL2CPP metadata 构建的 Unity 封装
如果你需要一个通用的 Unity mod 加载器或独立的游戏补丁框架，这个 crate 是一个构建块，而不是一个完整的解决方案。
## 运行时假设
在使用 API 之前，请记住以下约束：
- 当前进程中必须已加载活动的 IL2CPP runtime。
- 在依赖缓存支持的查找（如 `api::cache::csharp()`）之前，必须调用 [`init`](src/init.rs)。
- 许多操作最终都会处理原始指针和 runtime 拥有的内存。该 crate 减少了易错点，但并没有使 IL2CPP 集成完全安全。
- 方法调用、字段访问和对象封装仅在目标 Unity runtime 处于活动状态且与预期的 metadata 兼容时才有意义。
- 某些操作需要当前线程附加到 IL2CPP VM。当你在初始化回调之外进行工作时，请使用 `api::Thread`。
## 安装
```
cargo add il2cpp-bridge-rs
```
## 构建与验证
仓库包含一个包含常见工作流的 `Makefile`：
```
make build
make check
make clippy
make doc
```
还提供了特定平台的 target，包括 `make build-ios`、`make build-macos`、`make build-linux`、`make build-android` 和 `make build-windows`。
## 首次成功流程
下面的代码片段展示了预期的顺畅路径：初始化 runtime，获取缓存的 assembly，解析类，检查方法，并在对象可用时调用实例方法。
此示例仅用于说明。它可以作为 Rust 代码编译，但需要一个活动的 Unity IL2CPP runtime 才能执行任何有用的操作。
```
use il2cpp_bridge_rs::{api, init};
use std::ffi::c_void;
init("GameAssembly", || {
let asm = api::cache::csharp();
let player_class = asm
.class("PlayerController")
.expect("PlayerController should exist after cache hydration");
let damage_method = player_class
.method(("TakeDamage", ["System.Single"]))
.expect("TakeDamage(float) should exist");
println!(
"Resolved {}::{} at RVA 0x{:X}",
player_class.name,
damage_method.name,
damage_method.rva
);
if let Some(player) = player_class.find_objects_of_type(false).into_iter().next() {
let bound_method = player
.method(("TakeDamage", ["System.Single"]))
.expect("instance method should bind automatically");
let damage: f32 = 25.0;
unsafe {
let _: Result<(), _> =
bound_method.call(&[&damage as *const f32 as *mut c_void]);
}
}
});
```
## 文档地图
Markdown 指南解释了工作流和注意事项。生成的 rustdoc 应被视为确切签名的真实来源。
- [入门指南](docs/getting-started.md)
- [核心工作流](docs/core-workflows.md)
- [平台与运行时说明](docs/platform-support.md)
- [架构](docs/architecture.md)
- [API 地图](docs/api-reference.md)
要在本地构建 rustdoc：
```
cargo doc --no-deps
```
## 主要入口点
大多数用户会首先在这些 API 上花费时间：
- `init`
- `api::cache`
- `api::Thread`
- `api::invoke_method`
- dump 辅助工具，如 `api::dump` 和 `api::dump_all_to`
- 封装器，如 `api::Application` 和 `api::Time`
- `structs` 下的 metadata 和对象封装
## 支持的目标
该项目目前提供以下构建目标：
- iOS: `aarch64-apple-ios`
- macOS: `aarch64-apple-darwin`
- Linux: `x86_64-unknown-linux-gnu`
- Android: `aarch64-linux-android`
- Windows: `x86_64-pc-windows-msvc`
有关符号解析详细信息、目标镜像命名指南以及线程/runtime 注意事项，请参阅 [平台与运行时说明](docs/platform-support.md)。
## 贡献
贡献期望和本地开发工作流记录在 [CONTRIBUTING.md](CONTRIBUTING.md) 中。
## 许可证
[MIT](LICENSE)标签：Android, DSL, Hook技术, IL2CPP, iOS, Mod制作, Rust, Unity, 元数据解析, 内存操作, 内挂开发, 原生插件, 可视化界面, 游戏安全, 游戏开发工具, 游戏逆向, 系统编程, 网络流量审计, 跨语言桥接, 运行时劫持, 通知系统