il2cpp-bridge-rs 0.1.3

Rust library for Unity IL2CPP runtime introspection — resolve classes, invoke methods, and interact with the IL2CPP VM at runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# Architecture

This crate is intentionally layered so most users can stay in cache/object/wrapper APIs while contributors can reason about the lower-level runtime boundary.

This page explains how the crate is organized. Use generated rustdoc for detailed API information on the public modules, structs, and methods referenced here.

## Layered View

```text
init
  -> runtime symbol loading
  -> thread attachment
  -> assembly cache load
  -> class hydration
  -> user callbacks

api
  -> raw IL2CPP bindings
  -> cache helpers
  -> method invocation
  -> thread management
  -> dump helpers
  -> small Unity wrappers

structs
  -> metadata wrappers (Assembly, Class, Method, Field, Property, Type)
  -> object wrappers (Object, GameObject, Transform, MonoBehaviour, ...)
  -> collection and math helpers

memory
  -> symbol resolution
  -> image base lookup
  -> raw memory read/write
```

## Initialization Flow

`init` is the front door for the crate.

During initialization the crate:

1. resolves exported IL2CPP functions
2. loads the FFI function table
3. attaches the worker thread to the IL2CPP VM
4. enumerates assemblies into a global cache
5. hydrates classes, methods, fields, and properties
6. runs queued callbacks

If symbol resolution or cache initialization fails, the state resets so initialization can be attempted again.

## Cache Design

The cache exists to make repeated metadata lookup cheap and predictable.

- assemblies are stored as `Arc<Assembly>`
- classes are stored in a global lookup map
- methods are indexed for fast reuse
- class hydration is guarded so it only runs once per successful initialization cycle

For most users, `api::cache` is the only cache surface they should touch directly.

## Invocation Model

Invocation is split across two layers:

- `api::invoke_method` is the raw pointer-level helper
- `Method::call<T>` is the normal user-facing path

`Method::call<T>` validates the argument count, handles instance binding, differentiates reference vs value-type returns, and converts managed exceptions into `Err(String)`.

## Thread Model

IL2CPP is thread-sensitive. The crate exposes `api::Thread` as the explicit mechanism for attaching and detaching threads outside the initialization path.

This is a design choice, not just a convenience wrapper. The thread boundary is one of the main correctness constraints in the entire crate.

## Wrapper Philosophy

Wrappers under `api::wrappers` and `structs::components` exist to make common Unity tasks less repetitive:

- `Application` and `Time` expose familiar Unity concepts
- `GameObject`, `Transform`, `MonoBehaviour`, and related types layer on top of `Object` and `Method`

These wrappers should stay thin. If a behavior belongs to core runtime or metadata semantics, it should live in the lower layer first.

When you need exact signatures or item-level semantics for any layer described above, consult rustdoc rather than this architecture overview.