# omonkeyz/xbox-emulator architecture

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

- Interactive diagram: https://gitdiagram.com/omonkeyz/xbox-emulator
- Repository: https://github.com/omonkeyz/xbox-emulator

## Overview

TomBox is an Xbox Series X|S compatibility runtime: it runs already-decrypted game builds as Windows processes while reimplementing console-specific platform APIs. The main path is a game process loading compatibility libraries, which provide Xbox system/GDK behavior and Xbox-flavored graphics and audio; shader translation supports rendering. The README also documents online login and title progress, while the tree shows online-service implementations. Edges are limited to README statements and source-index references; unsampled implementation details are not inferred.

Main entry points: [`crates/compat/compat-common/src/os_host/routes_rt.rs`](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/os_host/routes_rt.rs) (DLL routing and hooks), [`crates/compat/xcrdapi/src/xcrd2_storage.rs`](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xcrdapi/src/xcrd2_storage.rs) (Console storage API), [`crates/compat/d3d12_xs/src/device_wrap.rs`](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/d3d12_xs/src/device_wrap.rs) (Xbox D3D12 runtime), [`crates/compat/xaudio2_9/src/engine.rs`](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xaudio2_9/src/engine.rs) (XAudio engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime compatibility"]
  node_winproc["Windows process"]
  node_routing["DLL routing and hooks<br/>[routes_rt.rs]"]
  node_route_table["Host route selection<br/>[routes.rs]"]
  node_patch["Image patching<br/>[patch.rs]"]
  node_gdk_fs["GDK file services<br/>[fs.rs]"]
  node_xcrd_storage["Console storage API<br/>[xcrd2_storage.rs]"]
  node_xcrd_core["Storage core<br/>[xcrd_core.rs]"]
  node_xcrd_adapter["Storage adapter<br/>[xcrd_a.rs]"]
end

subgraph group_graphics["Graphics and shaders"]
  node_d3d["Xbox D3D12 runtime<br/>[device_wrap.rs]"]
  node_shader["RDNA2 to HLSL<br/>[hlsl.rs]"]
end

subgraph group_media["Media"]
  node_audio["XAudio engine<br/>[engine.rs]"]
  node_xma["XMA voice support<br/>[xma_voice.rs]"]
end

subgraph group_online["Online services"]
  node_online["Title online APIs"]
end

node_game(("Decrypted game"))
node_services(("Online services"))

node_game -->|"runs as"| node_winproc
node_winproc -.->|"loads through"| node_routing
node_routing -->|"consults routes"| node_route_table
node_routing -->|"uses hooks"| node_patch
node_gdk_fs -->|"uses routing"| node_routing
node_xcrd_storage -->|"uses adapter"| node_xcrd_adapter
node_xcrd_storage -->|"uses core"| node_xcrd_core
node_winproc -->|"uses console graphics"| node_d3d
node_d3d -.->|"uses translated shaders"| node_shader
node_winproc -.->|"uses audio APIs"| node_audio
node_audio -->|"dispatches XMA voices"| node_xma
node_winproc -.->|"uses title services"| node_online
node_online -.->|"communicates with"| node_services

click node_routing "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/os_host/routes_rt.rs"
click node_route_table "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/os_host/routes.rs"
click node_patch "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/os_host/patch.rs"
click node_gdk_fs "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/gdk/fs.rs"
click node_xcrd_storage "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xcrdapi/src/xcrd2_storage.rs"
click node_xcrd_core "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xcrdapi/src/xcrd_core.rs"
click node_xcrd_adapter "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xcrdapi/src/xcrd_a.rs"
click node_d3d "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/d3d12_xs/src/device_wrap.rs"
click node_shader "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/tombox-xshader/src/hlsl.rs"
click node_audio "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xaudio2_9/src/engine.rs"
click node_xma "https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xaudio2_9/src/xma_voice.rs"
click node_online "https://github.com/omonkeyz/xbox-emulator/tree/main/crates/compat/compat-common/src/online"

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_winproc,node_routing,node_route_table,node_patch,node_gdk_fs,node_xcrd_storage,node_xcrd_core,node_xcrd_adapter toneBlue
class node_d3d,node_shader toneAmber
class node_audio,node_xma toneMint
class node_online toneRose
class node_game,node_services toneIndigo
```

## Components

### Runtime compatibility

- **Windows process**
- [DLL routing and hooks](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/os_host/routes_rt.rs): `crates/compat/compat-common/src/os_host/routes_rt.rs`
- [Host route selection](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/os_host/routes.rs): `crates/compat/compat-common/src/os_host/routes.rs`
- [Image patching](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/os_host/patch.rs): `crates/compat/compat-common/src/os_host/patch.rs`
- [GDK file services](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/compat-common/src/gdk/fs.rs): `crates/compat/compat-common/src/gdk/fs.rs`
- [Console storage API](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xcrdapi/src/xcrd2_storage.rs): `crates/compat/xcrdapi/src/xcrd2_storage.rs`
- [Storage core](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xcrdapi/src/xcrd_core.rs): `crates/compat/xcrdapi/src/xcrd_core.rs`
- [Storage adapter](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xcrdapi/src/xcrd_a.rs): `crates/compat/xcrdapi/src/xcrd_a.rs`

### Graphics and shaders

- [Xbox D3D12 runtime](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/d3d12_xs/src/device_wrap.rs): `crates/compat/d3d12_xs/src/device_wrap.rs`
- [RDNA2 to HLSL](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/tombox-xshader/src/hlsl.rs): `crates/tombox-xshader/src/hlsl.rs`

### Media

- [XAudio engine](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xaudio2_9/src/engine.rs): `crates/compat/xaudio2_9/src/engine.rs`
- [XMA voice support](https://github.com/omonkeyz/xbox-emulator/blob/main/crates/compat/xaudio2_9/src/xma_voice.rs): `crates/compat/xaudio2_9/src/xma_voice.rs`

### Online services

- [Title online APIs](https://github.com/omonkeyz/xbox-emulator/tree/main/crates/compat/compat-common/src/online): `crates/compat/compat-common/src/online`

### Other components

- **Decrypted game**
- **Online services**

## Connections

- Decrypted game → Windows process: runs as (evidence: `README.md`)
- Windows process → DLL routing and hooks: loads through
- DLL routing and hooks → Host route selection: consults routes (evidence: `crates/compat/compat-common/src/os_host/routes_rt.rs`)
- DLL routing and hooks → Image patching: uses hooks (evidence: `crates/compat/compat-common/src/os_host/routes_rt.rs`)
- GDK file services → DLL routing and hooks: uses routing (evidence: `crates/compat/compat-common/src/gdk/fs.rs`)
- Console storage API → Storage adapter: uses adapter (evidence: `crates/compat/xcrdapi/src/xcrd2_storage.rs`)
- Console storage API → Storage core: uses core (evidence: `crates/compat/xcrdapi/src/xcrd2_storage.rs`)
- Windows process → Xbox D3D12 runtime: uses console graphics (evidence: `README.md`)
- Xbox D3D12 runtime → RDNA2 to HLSL: uses translated shaders
- Windows process → XAudio engine: uses audio APIs
- XAudio engine → XMA voice support: dispatches XMA voices (evidence: `crates/compat/xaudio2_9/src/engine.rs`)
- Windows process → Title online APIs: uses title services
- Title online APIs → Online services: communicates with
