# retroportingtoolkit/psxrecomp architecture

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

- Interactive diagram: https://gitdiagram.com/retroportingtoolkit/psxrecomp
- Repository: https://github.com/retroportingtoolkit/psxrecomp

## Overview

PSXRecomp is a framework that turns a PlayStation disc into a native game executable linked to a hardware-accurate PS1 runtime. The main workflow verifies and prepares a disc, parses its executable, analyzes MIPS code and emits native C; the runtime executes that code alongside BIOS and hardware services. Separate branches provide ahead-of-time overlay sharding, interpreter fallback, widescreen and mod support, and multiplayer. The README documents these capabilities; unsampled source limits detailed call wiring, so the graph shows only the documented workflow and clear runtime responsibilities.

Main entry points: [`runtime/src/main.cpp`](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/main.cpp) (Runtime entry), [`psxrecomp_cli.py`](https://github.com/retroportingtoolkit/psxrecomp/blob/master/psxrecomp_cli.py) (Game CLI), [`recompiler/src/ps1_exe_parser.cpp`](https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/ps1_exe_parser.cpp) (EXE parser), [`recompiler/src/function_analysis.cpp`](https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/function_analysis.cpp) (Code analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recomp["Recompilation"]
  node_cli["Game CLI<br/>[psxrecomp_cli.py]"]
  node_exe["EXE parser<br/>[ps1_exe_parser.cpp]"]
  node_analysis["Code analysis"]
  node_discovery["Function discovery"]
  node_generator["C code generator<br/>[code_generator.cpp]"]
end

subgraph group_execution["Runtime execution"]
  node_runtime["Runtime entry<br/>[main.cpp]"]
  node_bios["BIOS backends<br/>[psx_bios_backend.c]"]
  node_hardware["PS1 hardware<br/>[psx_interpreter.c]"]
  node_interpreter["MIPS fallback<br/>[psx_interpreter.c]"]
  node_overlay["Overlay capture<br/>[autocompile.c]"]
end

subgraph group_enhancements["Game enhancements"]
  node_sharding["AOT sharding"]
  node_widescreen["Widescreen"]
  node_mods["Mod runtime<br/>[mod_runtime.cpp]"]
end

subgraph group_multiplayer["Multiplayer"]
  node_netplay["Netplay<br/>[psx_netplay.c]"]
  node_lobby["Lobby client<br/>[psx_lobby_client.c]"]
end

node_developer(("Game developer"))
node_disc["PS1 disc"]
node_output["Native game"]
node_player(("Player"))
node_lobby_service(("Lobby service"))

node_developer -->|"runs generation"| node_cli
node_disc -->|"provides input"| node_cli
node_cli -->|"prepares executable"| node_exe
node_exe -->|"supplies code"| node_analysis
node_analysis -->|"informs discovery"| node_discovery
node_discovery -->|"identifies functions"| node_generator
node_generator -->|"emits native code"| node_output
node_player -->|"runs game"| node_runtime
node_output -->|"executes in"| node_runtime
node_runtime -->|"selects BIOS"| node_bios
node_runtime -->|"uses hardware services"| node_hardware
node_runtime -->|"falls back to"| node_interpreter
node_runtime -->|"captures streamed code"| node_overlay
node_overlay -.->|"feeds compilation"| node_sharding
node_runtime -->|"applies display changes"| node_widescreen
node_runtime -->|"loads modifications"| node_mods
node_runtime -->|"runs multiplayer"| node_netplay
node_netplay -->|"uses matchmaking"| node_lobby
node_lobby -.->|"communicates with"| node_lobby_service

click node_cli "https://github.com/retroportingtoolkit/psxrecomp/blob/master/psxrecomp_cli.py"
click node_exe "https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/ps1_exe_parser.cpp"
click node_analysis "https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/function_analysis.cpp"
click node_discovery "https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/function_discovery.cpp"
click node_generator "https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/code_generator.cpp"
click node_runtime "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/main.cpp"
click node_bios "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_bios_backend.c"
click node_hardware "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_interpreter.c"
click node_interpreter "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_interpreter.c"
click node_overlay "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/autocompile.c"
click node_sharding "https://github.com/retroportingtoolkit/psxrecomp/blob/master/tools/aot_overlay_pipeline.py"
click node_widescreen "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/ws_aspect_cone_math.c"
click node_mods "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/mod_runtime.cpp"
click node_netplay "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_netplay.c"
click node_lobby "https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_lobby_client.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_exe,node_analysis,node_discovery,node_generator toneBlue
class node_runtime,node_bios,node_hardware,node_interpreter,node_overlay toneAmber
class node_sharding,node_widescreen,node_mods toneMint
class node_netplay,node_lobby toneRose
class node_developer,node_disc,node_output,node_player,node_lobby_service toneIndigo
```

## Components

### Recompilation

- [Game CLI](https://github.com/retroportingtoolkit/psxrecomp/blob/master/psxrecomp_cli.py): `psxrecomp_cli.py`
- [EXE parser](https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/ps1_exe_parser.cpp): `recompiler/src/ps1_exe_parser.cpp`
- [Code analysis](https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/function_analysis.cpp): `recompiler/src/function_analysis.cpp`
- [Function discovery](https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/function_discovery.cpp): `recompiler/src/function_discovery.cpp`
- [C code generator](https://github.com/retroportingtoolkit/psxrecomp/blob/master/recompiler/src/code_generator.cpp): `recompiler/src/code_generator.cpp`

### Runtime execution

- [Runtime entry](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/main.cpp): `runtime/src/main.cpp`
- [BIOS backends](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_bios_backend.c): `runtime/src/psx_bios_backend.c`
- [PS1 hardware](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_interpreter.c): `runtime/src/psx_interpreter.c`
- [MIPS fallback](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_interpreter.c): `runtime/src/psx_interpreter.c`
- [Overlay capture](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/autocompile.c): `runtime/src/autocompile.c`

### Game enhancements

- [AOT sharding](https://github.com/retroportingtoolkit/psxrecomp/blob/master/tools/aot_overlay_pipeline.py): `tools/aot_overlay_pipeline.py`
- [Widescreen](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/ws_aspect_cone_math.c): `runtime/src/ws_aspect_cone_math.c`
- [Mod runtime](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/mod_runtime.cpp): `runtime/src/mod_runtime.cpp`

### Multiplayer

- [Netplay](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_netplay.c): `runtime/src/psx_netplay.c`
- [Lobby client](https://github.com/retroportingtoolkit/psxrecomp/blob/master/runtime/src/psx_lobby_client.c): `runtime/src/psx_lobby_client.c`

### Other components

- **Game developer**
- **PS1 disc**
- **Native game**
- **Player**
- **Lobby service**

## Connections

- Game developer → Game CLI: runs generation
- PS1 disc → Game CLI: provides input
- Game CLI → EXE parser: prepares executable
- EXE parser → Code analysis: supplies code
- Code analysis → Function discovery: informs discovery
- Function discovery → C code generator: identifies functions
- C code generator → Native game: emits native code
- Player → Runtime entry: runs game
- Native game → Runtime entry: executes in
- Runtime entry → BIOS backends: selects BIOS
- Runtime entry → PS1 hardware: uses hardware services
- Runtime entry → MIPS fallback: falls back to
- Runtime entry → Overlay capture: captures streamed code
- Overlay capture → AOT sharding: feeds compilation
- Runtime entry → Widescreen: applies display changes
- Runtime entry → Mod runtime: loads modifications
- Runtime entry → Netplay: runs multiplayer
- Netplay → Lobby client: uses matchmaking
- Lobby client → Lobby service: communicates with