# eysap/il2bridge architecture

> Architecture diagram of the GitHub repository eysap/il2bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eysap/il2bridge
- Repository: https://github.com/eysap/il2bridge

## Overview

IL2Bridge injects a native loader into a Unity IL2CPP process and uses a separate broker CLI to discover targets, inspect metadata, resolve methods, manage hooks, and read hook events. The README documents the loader, reversible trampoline and breakpoint hooks, and bounded resumable event streaming. Source excerpts confirm parts of broker session handling, metadata decoding, loader dispatch, and trampoline installation; links for unsampled subsystems follow documented behavior and are limited accordingly.

Main entry points: [`src/loader/ipc_server.c`](https://github.com/eysap/il2bridge/blob/main/src/loader/ipc_server.c) (IPC server), [`src/broker/cli/main.cpp`](https://github.com/eysap/il2bridge/blob/main/src/broker/cli/main.cpp) (Broker commands), [`src/broker/client/target_session.cpp`](https://github.com/eysap/il2bridge/blob/main/src/broker/client/target_session.cpp) (Target session), [`src/loader/init.c`](https://github.com/eysap/il2bridge/blob/main/src/loader/init.c) (Loader initialization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_broker["Broker CLI"]
  node_cli["Broker commands<br/>[main.cpp]"]
  node_selector["Method selectors<br/>[client_models.cpp]"]
  node_metadata["Metadata parser<br/>[metadata_file.cpp]"]
end

subgraph group_discovery["Target Discovery"]
  node_unity["Unity discovery"]
  node_targets["Target discovery"]
  node_session["Target session<br/>[target_session.cpp]"]
  node_transport["IPC transport<br/>[ipc_transport.cpp]"]
end

subgraph group_loader["Loader Runtime"]
  node_init["Loader initialization<br/>[init.c]"]
  node_discovery_loader["Runtime discovery<br/>[discovery.c]"]
  node_bridge["IL2CPP bridge<br/>[bridge.c]"]
  node_server["IPC server<br/>[ipc_server.c]"]
end

subgraph group_instrumentation["Hooks and Events"]
  node_hooks["Hook registry<br/>[registry.c]"]
  node_trampoline["Trampoline hooks<br/>[trampoline.c]"]
  node_breakpoint["Breakpoint hooks<br/>[breakpoint.c]"]
  node_handlers["Hook handlers<br/>[registry.c]"]
  node_events["Event ring<br/>[events.c]"]
end

node_operator(("Engineer"))
node_target["Unity target process"]
node_runtime["IL2CPP runtime"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"discovers targets"| node_targets
node_cli -->|"inspects metadata"| node_metadata
node_cli -->|"parses selectors"| node_selector
node_cli -->|"manages hooks"| node_session
node_unity -->|"locates metadata"| node_metadata
node_targets -->|"selects target"| node_session
node_session -->|"sends requests"| node_transport
node_transport -->|"exchanges socket data"| node_server
node_target -->|"loads via LD_PRELOAD"| node_init
node_init -->|"starts discovery"| node_discovery_loader
node_discovery_loader -->|"waits for mapping"| node_runtime
node_init -->|"initializes API"| node_bridge
node_bridge -->|"resolves IL2CPP API"| node_runtime
node_server -->|"resolves methods"| node_bridge
node_server -->|"installs or removes"| node_hooks
node_server -->|"looks up handler"| node_handlers
node_hooks -->|"installs transport"| node_trampoline
node_hooks -->|"installs transport"| node_breakpoint
node_trampoline -->|"publishes hook hits"| node_events
node_server -->|"streams events"| node_events
node_session -->|"requests hook and event data"| node_server

click node_cli "https://github.com/eysap/il2bridge/blob/main/src/broker/cli/main.cpp"
click node_selector "https://github.com/eysap/il2bridge/blob/main/src/broker/client/client_models.cpp"
click node_metadata "https://github.com/eysap/il2bridge/blob/main/src/broker/metadata/metadata_file.cpp"
click node_unity "https://github.com/eysap/il2bridge/blob/main/src/broker/metadata/unity_discovery.cpp"
click node_targets "https://github.com/eysap/il2bridge/blob/main/src/broker/client/target_discovery.cpp"
click node_session "https://github.com/eysap/il2bridge/blob/main/src/broker/client/target_session.cpp"
click node_transport "https://github.com/eysap/il2bridge/blob/main/src/broker/client/ipc_transport.cpp"
click node_init "https://github.com/eysap/il2bridge/blob/main/src/loader/init.c"
click node_discovery_loader "https://github.com/eysap/il2bridge/blob/main/src/loader/discovery.c"
click node_bridge "https://github.com/eysap/il2bridge/blob/main/src/loader/bridge.c"
click node_server "https://github.com/eysap/il2bridge/blob/main/src/loader/ipc_server.c"
click node_hooks "https://github.com/eysap/il2bridge/blob/main/src/loader/hooks/registry.c"
click node_trampoline "https://github.com/eysap/il2bridge/blob/main/src/loader/hooks/trampoline.c"
click node_breakpoint "https://github.com/eysap/il2bridge/blob/main/src/loader/hooks/breakpoint.c"
click node_handlers "https://github.com/eysap/il2bridge/blob/main/src/loader/handlers/registry.c"
click node_events "https://github.com/eysap/il2bridge/blob/main/src/loader/events.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_selector,node_metadata toneBlue
class node_unity,node_targets,node_session,node_transport toneAmber
class node_init,node_discovery_loader,node_bridge,node_server toneMint
class node_hooks,node_trampoline,node_breakpoint,node_handlers,node_events toneRose
class node_operator,node_target,node_runtime toneIndigo
```

## Components

### Broker CLI

- [Broker commands](https://github.com/eysap/il2bridge/blob/main/src/broker/cli/main.cpp): `src/broker/cli/main.cpp`
- [Method selectors](https://github.com/eysap/il2bridge/blob/main/src/broker/client/client_models.cpp): `src/broker/client/client_models.cpp`
- [Metadata parser](https://github.com/eysap/il2bridge/blob/main/src/broker/metadata/metadata_file.cpp): `src/broker/metadata/metadata_file.cpp`

### Target Discovery

- [Unity discovery](https://github.com/eysap/il2bridge/blob/main/src/broker/metadata/unity_discovery.cpp): `src/broker/metadata/unity_discovery.cpp`
- [Target discovery](https://github.com/eysap/il2bridge/blob/main/src/broker/client/target_discovery.cpp): `src/broker/client/target_discovery.cpp`
- [Target session](https://github.com/eysap/il2bridge/blob/main/src/broker/client/target_session.cpp): `src/broker/client/target_session.cpp`
- [IPC transport](https://github.com/eysap/il2bridge/blob/main/src/broker/client/ipc_transport.cpp): `src/broker/client/ipc_transport.cpp`

### Loader Runtime

- [Loader initialization](https://github.com/eysap/il2bridge/blob/main/src/loader/init.c): `src/loader/init.c`
- [Runtime discovery](https://github.com/eysap/il2bridge/blob/main/src/loader/discovery.c): `src/loader/discovery.c`
- [IL2CPP bridge](https://github.com/eysap/il2bridge/blob/main/src/loader/bridge.c): `src/loader/bridge.c`
- [IPC server](https://github.com/eysap/il2bridge/blob/main/src/loader/ipc_server.c): `src/loader/ipc_server.c`

### Hooks and Events

- [Hook registry](https://github.com/eysap/il2bridge/blob/main/src/loader/hooks/registry.c): `src/loader/hooks/registry.c`
- [Trampoline hooks](https://github.com/eysap/il2bridge/blob/main/src/loader/hooks/trampoline.c): `src/loader/hooks/trampoline.c`
- [Breakpoint hooks](https://github.com/eysap/il2bridge/blob/main/src/loader/hooks/breakpoint.c): `src/loader/hooks/breakpoint.c`
- [Hook handlers](https://github.com/eysap/il2bridge/blob/main/src/loader/handlers/registry.c): `src/loader/handlers/registry.c`
- [Event ring](https://github.com/eysap/il2bridge/blob/main/src/loader/events.c): `src/loader/events.c`

### Other components

- **Engineer**
- **Unity target process**
- **IL2CPP runtime**

## Connections

- Engineer → Broker commands: runs commands
- Broker commands → Target discovery: discovers targets
- Broker commands → Metadata parser: inspects metadata
- Broker commands → Method selectors: parses selectors
- Broker commands → Target session: manages hooks
- Unity discovery → Metadata parser: locates metadata
- Target discovery → Target session: selects target
- Target session → IPC transport: sends requests
- IPC transport → IPC server: exchanges socket data
- Unity target process → Loader initialization: loads via LD_PRELOAD
- Loader initialization → Runtime discovery: starts discovery
- Runtime discovery → IL2CPP runtime: waits for mapping
- Loader initialization → IL2CPP bridge: initializes API
- IL2CPP bridge → IL2CPP runtime: resolves IL2CPP API
- IPC server → IL2CPP bridge: resolves methods
- IPC server → Hook registry: installs or removes
- IPC server → Hook handlers: looks up handler
- Hook registry → Trampoline hooks: installs transport
- Hook registry → Breakpoint hooks: installs transport
- Trampoline hooks → Event ring: publishes hook hits
- IPC server → Event ring: streams events
- Target session → IPC server: requests hook and event data