# r0y00/xbox2windows architecture

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

- Interactive diagram: https://gitdiagram.com/r0y00/xbox2windows
- Repository: https://github.com/r0y00/xbox2windows

## Overview

Xbox2Windows is a research toolkit for translating and validating selected Xbox Scarlett CPU and GPU behavior on Windows, alongside desktop compatibility shims. The main workflows begin with inspecting PE/resources or shader code, then produce a bounded translation or replay and compare results against references. Separate branches cover CPU lifting, shader translation and GPU resource analysis, and Windows memory/GPU compatibility. The graph reflects README-described capabilities even where implementation details were not sampled; those broader links are omitted when no relationship is evidenced.

Main entry points: [`tools/resource_inventory.py`](https://github.com/r0y00/xbox2windows/blob/main/tools/resource_inventory.py) (Resource inventory), [`tools/cpu_leaf_aot.py`](https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_leaf_aot.py) (Leaf lifting), [`tools/pixel_aot.py`](https://github.com/r0y00/xbox2windows/blob/main/tools/pixel_aot.py) (Pixel translation), [`src/era_title_gpu.cpp`](https://github.com/r0y00/xbox2windows/blob/main/src/era_title_gpu.cpp) (Title GPU memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Package analysis"]
  node_pe_inventory["PE inventory<br/>[pe_inventory.py]"]
  node_resource_inventory["Resource inventory"]
  node_call_evidence["Call evidence<br/>[call_evidence.py]"]
  node_shader_extract["Shader extraction<br/>[extract_shaders.py]"]
end

subgraph group_cpu["CPU translation"]
  node_cpu_ranges["CPU ranges<br/>[cpu_ranges.py]"]
  node_cpu_leaf["Leaf lifting<br/>[cpu_leaf_aot.py]"]
  node_cpu_calls["Call lifting<br/>[cpu_call_aot.py]"]
  node_cpu_chained["Chained lifting<br/>[cpu_chained_aot.py]"]
  node_cpu_switch["Switch lifting<br/>[cpu_switch_aot.py]"]
  node_ffx_query["FidelityFX query"]
  node_x87["x87 lowering<br/>[x87_lower.py]"]
end

subgraph group_gpu["GPU and shaders"]
  node_shader_scan["Shader scan"]
  node_pixel_translate["Pixel translation<br/>[pixel_aot.py]"]
  node_sampled_coverage["Coverage translation"]
  node_mesh_translate["Mesh translation<br/>[mesh_entry_aot.py]"]
  node_dxil_retarget["DXIL retargeting<br/>[dxil_retarget.py]"]
  node_dispatch_translate["FSR dispatch"]
  node_bc7["BC7 blocks<br/>[bc7_blocks.py]"]
end

subgraph group_compat["Windows compatibility"]
  node_title_gpu["Title GPU memory<br/>[era_title_gpu.cpp]"]
  node_gpu_alias["GPU heap aliases<br/>[era_gpu_alias.cpp]"]
  node_title_va["GPU address map<br/>[era_title_va.cpp]"]
  node_query["Virtual memory query<br/>[era_query.cpp]"]
  node_xmem["XMem shim<br/>[xmem_shim.cpp]"]
  node_heap["Windows heap<br/>[era_heap.cpp]"]
end

node_researcher(("Researcher"))

node_researcher -->|"inspects PE"| node_pe_inventory
node_researcher -->|"inspects resources"| node_resource_inventory
node_researcher -->|"translates functions"| node_cpu_leaf
node_researcher -->|"translates shaders"| node_pixel_translate
node_researcher -->|"extracts shaders"| node_shader_extract
node_call_evidence -->|"uses inventory"| node_pe_inventory
node_call_evidence -->|"uses inventory"| node_resource_inventory
node_shader_extract -->|"uses inventory"| node_resource_inventory
node_cpu_leaf -->|"reads ranges"| node_cpu_ranges
node_cpu_calls -->|"uses lifting"| node_cpu_leaf
node_cpu_chained -->|"uses lifting"| node_cpu_leaf
node_cpu_chained -->|"reads ranges"| node_cpu_ranges
node_cpu_switch -->|"uses lifting"| node_cpu_leaf
node_cpu_switch -->|"reads ranges"| node_cpu_ranges
node_ffx_query -->|"uses lifting"| node_cpu_leaf
node_ffx_query -->|"reads ranges"| node_cpu_ranges
node_ffx_query -->|"uses lowering"| node_x87
node_shader_scan -->|"uses inventory"| node_resource_inventory
node_shader_scan -->|"uses translator"| node_pixel_translate
node_pixel_translate -->|"uses inventory"| node_resource_inventory
node_sampled_coverage -->|"uses decoder"| node_pixel_translate
node_sampled_coverage -->|"uses inventory"| node_resource_inventory
node_mesh_translate -->|"uses decoder"| node_pixel_translate
node_mesh_translate -->|"uses inventory"| node_resource_inventory
node_dxil_retarget -->|"uses inventory"| node_resource_inventory
node_dxil_retarget -->|"uses evidence"| node_call_evidence
node_dxil_retarget -->|"uses probes"| node_shader_scan
node_dispatch_translate -->|"uses translator"| node_pixel_translate
node_title_gpu -->|"opens aliases"| node_gpu_alias
node_title_gpu -->|"maps addresses"| node_title_va
node_title_gpu -->|"registers regions"| node_query
node_xmem -->|"uses heap"| node_heap
node_xmem -->|"uses query"| node_query
node_xmem -->|"routes graphics memory"| node_title_gpu

click node_pe_inventory "https://github.com/r0y00/xbox2windows/blob/main/tools/pe_inventory.py"
click node_resource_inventory "https://github.com/r0y00/xbox2windows/blob/main/tools/resource_inventory.py"
click node_call_evidence "https://github.com/r0y00/xbox2windows/blob/main/tools/call_evidence.py"
click node_shader_extract "https://github.com/r0y00/xbox2windows/blob/main/tools/extract_shaders.py"
click node_cpu_ranges "https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_ranges.py"
click node_cpu_leaf "https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_leaf_aot.py"
click node_cpu_calls "https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_call_aot.py"
click node_cpu_chained "https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_chained_aot.py"
click node_cpu_switch "https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_switch_aot.py"
click node_ffx_query "https://github.com/r0y00/xbox2windows/blob/main/tools/ffx_version_query.py"
click node_x87 "https://github.com/r0y00/xbox2windows/blob/main/tools/x87_lower.py"
click node_shader_scan "https://github.com/r0y00/xbox2windows/blob/main/tools/scan_unsupported_shaders.py"
click node_pixel_translate "https://github.com/r0y00/xbox2windows/blob/main/tools/pixel_aot.py"
click node_sampled_coverage "https://github.com/r0y00/xbox2windows/blob/main/tools/sampled_coverage_aot.py"
click node_mesh_translate "https://github.com/r0y00/xbox2windows/blob/main/tools/mesh_entry_aot.py"
click node_dxil_retarget "https://github.com/r0y00/xbox2windows/blob/main/tools/dxil_retarget.py"
click node_dispatch_translate "https://github.com/r0y00/xbox2windows/blob/main/tools/ffx_dispatch_aot.py"
click node_bc7 "https://github.com/r0y00/xbox2windows/blob/main/tools/bc7_blocks.py"
click node_title_gpu "https://github.com/r0y00/xbox2windows/blob/main/src/era_title_gpu.cpp"
click node_gpu_alias "https://github.com/r0y00/xbox2windows/blob/main/src/era_gpu_alias.cpp"
click node_title_va "https://github.com/r0y00/xbox2windows/blob/main/src/era_title_va.cpp"
click node_query "https://github.com/r0y00/xbox2windows/blob/main/src/era_query.cpp"
click node_xmem "https://github.com/r0y00/xbox2windows/blob/main/src/xmem_shim.cpp"
click node_heap "https://github.com/r0y00/xbox2windows/blob/main/src/era_heap.cpp"

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_pe_inventory,node_resource_inventory,node_call_evidence,node_shader_extract toneBlue
class node_cpu_ranges,node_cpu_leaf,node_cpu_calls,node_cpu_chained,node_cpu_switch,node_ffx_query,node_x87 toneAmber
class node_shader_scan,node_pixel_translate,node_sampled_coverage,node_mesh_translate,node_dxil_retarget,node_dispatch_translate,node_bc7 toneMint
class node_title_gpu,node_gpu_alias,node_title_va,node_query,node_xmem,node_heap toneRose
class node_researcher toneIndigo
```

## Components

### Package analysis

- [PE inventory](https://github.com/r0y00/xbox2windows/blob/main/tools/pe_inventory.py): `tools/pe_inventory.py`
- [Resource inventory](https://github.com/r0y00/xbox2windows/blob/main/tools/resource_inventory.py): `tools/resource_inventory.py`
- [Call evidence](https://github.com/r0y00/xbox2windows/blob/main/tools/call_evidence.py): `tools/call_evidence.py`
- [Shader extraction](https://github.com/r0y00/xbox2windows/blob/main/tools/extract_shaders.py): `tools/extract_shaders.py`

### CPU translation

- [CPU ranges](https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_ranges.py): `tools/cpu_ranges.py`
- [Leaf lifting](https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_leaf_aot.py): `tools/cpu_leaf_aot.py`
- [Call lifting](https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_call_aot.py): `tools/cpu_call_aot.py`
- [Chained lifting](https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_chained_aot.py): `tools/cpu_chained_aot.py`
- [Switch lifting](https://github.com/r0y00/xbox2windows/blob/main/tools/cpu_switch_aot.py): `tools/cpu_switch_aot.py`
- [FidelityFX query](https://github.com/r0y00/xbox2windows/blob/main/tools/ffx_version_query.py): `tools/ffx_version_query.py`
- [x87 lowering](https://github.com/r0y00/xbox2windows/blob/main/tools/x87_lower.py): `tools/x87_lower.py`

### GPU and shaders

- [Shader scan](https://github.com/r0y00/xbox2windows/blob/main/tools/scan_unsupported_shaders.py): `tools/scan_unsupported_shaders.py`
- [Pixel translation](https://github.com/r0y00/xbox2windows/blob/main/tools/pixel_aot.py): `tools/pixel_aot.py`
- [Coverage translation](https://github.com/r0y00/xbox2windows/blob/main/tools/sampled_coverage_aot.py): `tools/sampled_coverage_aot.py`
- [Mesh translation](https://github.com/r0y00/xbox2windows/blob/main/tools/mesh_entry_aot.py): `tools/mesh_entry_aot.py`
- [DXIL retargeting](https://github.com/r0y00/xbox2windows/blob/main/tools/dxil_retarget.py): `tools/dxil_retarget.py`
- [FSR dispatch](https://github.com/r0y00/xbox2windows/blob/main/tools/ffx_dispatch_aot.py): `tools/ffx_dispatch_aot.py`
- [BC7 blocks](https://github.com/r0y00/xbox2windows/blob/main/tools/bc7_blocks.py): `tools/bc7_blocks.py`

### Windows compatibility

- [Title GPU memory](https://github.com/r0y00/xbox2windows/blob/main/src/era_title_gpu.cpp): `src/era_title_gpu.cpp`
- [GPU heap aliases](https://github.com/r0y00/xbox2windows/blob/main/src/era_gpu_alias.cpp): `src/era_gpu_alias.cpp`
- [GPU address map](https://github.com/r0y00/xbox2windows/blob/main/src/era_title_va.cpp): `src/era_title_va.cpp`
- [Virtual memory query](https://github.com/r0y00/xbox2windows/blob/main/src/era_query.cpp): `src/era_query.cpp`
- [XMem shim](https://github.com/r0y00/xbox2windows/blob/main/src/xmem_shim.cpp): `src/xmem_shim.cpp`
- [Windows heap](https://github.com/r0y00/xbox2windows/blob/main/src/era_heap.cpp): `src/era_heap.cpp`

### Other components

- **Researcher**

## Connections

- Researcher → PE inventory: inspects PE (evidence: `README.md`)
- Researcher → Resource inventory: inspects resources (evidence: `README.md`)
- Researcher → Leaf lifting: translates functions (evidence: `README.md`)
- Researcher → Pixel translation: translates shaders (evidence: `README.md`)
- Researcher → Shader extraction: extracts shaders (evidence: `README.md`)
- Call evidence → PE inventory: uses inventory (evidence: `tools/call_evidence.py`)
- Call evidence → Resource inventory: uses inventory (evidence: `tools/call_evidence.py`)
- Shader extraction → Resource inventory: uses inventory (evidence: `tools/extract_shaders.py`)
- Leaf lifting → CPU ranges: reads ranges (evidence: `tools/cpu_leaf_aot.py`)
- Call lifting → Leaf lifting: uses lifting (evidence: `tools/cpu_call_aot.py`)
- Chained lifting → Leaf lifting: uses lifting (evidence: `tools/cpu_chained_aot.py`)
- Chained lifting → CPU ranges: reads ranges (evidence: `tools/cpu_chained_aot.py`)
- Switch lifting → Leaf lifting: uses lifting (evidence: `tools/cpu_switch_aot.py`)
- Switch lifting → CPU ranges: reads ranges (evidence: `tools/cpu_switch_aot.py`)
- FidelityFX query → Leaf lifting: uses lifting (evidence: `tools/ffx_version_query.py`)
- FidelityFX query → CPU ranges: reads ranges (evidence: `tools/ffx_version_query.py`)
- FidelityFX query → x87 lowering: uses lowering (evidence: `tools/ffx_version_query.py`)
- Shader scan → Resource inventory: uses inventory (evidence: `tools/scan_unsupported_shaders.py`)
- Shader scan → Pixel translation: uses translator (evidence: `tools/scan_unsupported_shaders.py`)
- Pixel translation → Resource inventory: uses inventory (evidence: `tools/pixel_aot.py`)
- Coverage translation → Pixel translation: uses decoder (evidence: `tools/sampled_coverage_aot.py`)
- Coverage translation → Resource inventory: uses inventory (evidence: `tools/sampled_coverage_aot.py`)
- Mesh translation → Pixel translation: uses decoder (evidence: `tools/mesh_entry_aot.py`)
- Mesh translation → Resource inventory: uses inventory (evidence: `tools/mesh_entry_aot.py`)
- DXIL retargeting → Resource inventory: uses inventory (evidence: `tools/dxil_retarget.py`)
- DXIL retargeting → Call evidence: uses evidence (evidence: `tools/dxil_retarget.py`)
- DXIL retargeting → Shader scan: uses probes (evidence: `tools/dxil_retarget.py`)
- FSR dispatch → Pixel translation: uses translator (evidence: `tools/ffx_dispatch_aot.py`)
- Title GPU memory → GPU heap aliases: opens aliases (evidence: `src/era_title_gpu.cpp`)
- Title GPU memory → GPU address map: maps addresses
- Title GPU memory → Virtual memory query: registers regions (evidence: `src/era_title_gpu.cpp`)
- XMem shim → Windows heap: uses heap (evidence: `src/xmem_shim.cpp`)
- XMem shim → Virtual memory query: uses query (evidence: `src/xmem_shim.cpp`)
- XMem shim → Title GPU memory: routes graphics memory
