# shadps4-emu/shadps4 architecture

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

- Interactive diagram: https://gitdiagram.com/shadps4-emu/shadps4
- Repository: https://github.com/shadps4-emu/shadps4

## Overview

shadPS4 is a cross-platform PlayStation 4 emulator. The documented user workflow is to launch a game by title ID or provide a PS4 ELF; the command-line entry point then starts emulation. The architecture separates guest execution, PS4-compatible services, host input and rendering, and persistent configuration/cache. Edges are limited to relationships visible in the README, the main.cpp reference index, or sampled Vulkan/cache excerpts; unsampled runtime wiring is left unconnected or marked unverified.

Main entry points: [`src/main.cpp`](https://github.com/shadps4-emu/shadps4/blob/main/src/main.cpp) (CLI Entry), [`src/emulator.cpp`](https://github.com/shadps4-emu/shadps4/blob/main/src/emulator.cpp) (Emulator Runtime), [`src/video_core/renderer_vulkan/vk_pipeline_cache.cpp`](https://github.com/shadps4-emu/shadps4/blob/main/src/video_core/renderer_vulkan/vk_pipeline_cache.cpp) (Pipeline Cache), [`src/core/ipc/ipc.cpp`](https://github.com/shadps4-emu/shadps4/blob/main/src/core/ipc/ipc.cpp) (Guest IPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and Control"]
  node_cli["CLI Entry<br/>[main.cpp]"]
  node_settings["Emulator Settings"]
end

subgraph group_execution["Guest Execution"]
  node_emulator["Emulator Runtime<br/>[emulator.cpp]"]
  node_state["Emulator State<br/>[emulator_state.cpp]"]
  node_address["Guest Address Space<br/>[address_space.cpp]"]
  node_elf["ELF Metadata<br/>[elf_info.h]"]
end

subgraph group_services["PS4 Services"]
  node_filesystem["Virtual Filesystem<br/>[fs.cpp]"]
  node_ipc["Guest IPC<br/>[ipc.cpp]"]
  node_libraries["PS4 Libraries<br/>[libs.cpp]"]
  node_users["User Services<br/>[userservice.h]"]
end

subgraph group_graphics["Graphics"]
  node_shader["Shader Compiler<br/>[program.cpp]"]
  node_pipeline["Vulkan Pipelines"]
  node_pipeline_cache["Pipeline Cache"]
  node_cache[("Cache Storage<br/>[cache_storage.cpp]")]
end

subgraph group_host["Host Integration"]
  node_input["Controller Input<br/>[controller.cpp]"]
  node_window["SDL Window<br/>[sdl_window.cpp]"]
  node_debugger["Debugger<br/>[debugger.cpp]"]
end

node_user(("Player"))

node_user -->|"launches"| node_cli
node_cli -->|"starts"| node_emulator
node_cli -->|"configures"| node_filesystem
node_cli -->|"configures"| node_settings
node_cli -->|"configures"| node_debugger
node_emulator -.->|"uses"| node_state
node_emulator -.->|"uses"| node_address
node_emulator -.->|"reads metadata"| node_elf
node_emulator -.->|"dispatches"| node_ipc
node_ipc -.->|"dispatches"| node_libraries
node_libraries -.->|"provides"| node_users
node_input -->|"uses user IDs"| node_users
node_pipeline_cache -->|"requests compilation"| node_shader
node_pipeline_cache -->|"loads and saves"| node_cache
node_pipeline_cache -.->|"creates pipelines"| node_pipeline
node_user -.->|"interacts"| node_window

click node_cli "https://github.com/shadps4-emu/shadps4/blob/main/src/main.cpp"
click node_settings "https://github.com/shadps4-emu/shadps4/blob/main/src/core/emulator_settings.h"
click node_input "https://github.com/shadps4-emu/shadps4/blob/main/src/input/controller.cpp"
click node_emulator "https://github.com/shadps4-emu/shadps4/blob/main/src/emulator.cpp"
click node_state "https://github.com/shadps4-emu/shadps4/blob/main/src/core/emulator_state.cpp"
click node_address "https://github.com/shadps4-emu/shadps4/blob/main/src/core/address_space.cpp"
click node_elf "https://github.com/shadps4-emu/shadps4/blob/main/src/common/elf_info.h"
click node_filesystem "https://github.com/shadps4-emu/shadps4/blob/main/src/core/file_sys/fs.cpp"
click node_ipc "https://github.com/shadps4-emu/shadps4/blob/main/src/core/ipc/ipc.cpp"
click node_libraries "https://github.com/shadps4-emu/shadps4/blob/main/src/core/libraries/libs.cpp"
click node_users "https://github.com/shadps4-emu/shadps4/blob/main/src/core/libraries/system/userservice.h"
click node_shader "https://github.com/shadps4-emu/shadps4/blob/main/src/shader_recompiler/ir/program.cpp"
click node_pipeline "https://github.com/shadps4-emu/shadps4/blob/main/src/video_core/renderer_vulkan/vk_graphics_pipeline.cpp"
click node_pipeline_cache "https://github.com/shadps4-emu/shadps4/blob/main/src/video_core/renderer_vulkan/vk_pipeline_cache.cpp"
click node_cache "https://github.com/shadps4-emu/shadps4/blob/main/src/video_core/cache_storage.cpp"
click node_window "https://github.com/shadps4-emu/shadps4/blob/main/src/sdl_window.cpp"
click node_debugger "https://github.com/shadps4-emu/shadps4/blob/main/src/core/debugger.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_cli,node_settings toneBlue
class node_emulator,node_state,node_address,node_elf toneAmber
class node_filesystem,node_ipc,node_libraries,node_users toneMint
class node_shader,node_pipeline,node_pipeline_cache,node_cache toneRose
class node_input,node_window,node_debugger,node_user toneIndigo
```

## Components

### Launch and Control

- [CLI Entry](https://github.com/shadps4-emu/shadps4/blob/main/src/main.cpp): `src/main.cpp`
- [Emulator Settings](https://github.com/shadps4-emu/shadps4/blob/main/src/core/emulator_settings.h): `src/core/emulator_settings.h`

### Guest Execution

- [Emulator Runtime](https://github.com/shadps4-emu/shadps4/blob/main/src/emulator.cpp): `src/emulator.cpp`
- [Emulator State](https://github.com/shadps4-emu/shadps4/blob/main/src/core/emulator_state.cpp): `src/core/emulator_state.cpp`
- [Guest Address Space](https://github.com/shadps4-emu/shadps4/blob/main/src/core/address_space.cpp): `src/core/address_space.cpp`
- [ELF Metadata](https://github.com/shadps4-emu/shadps4/blob/main/src/common/elf_info.h): `src/common/elf_info.h`

### PS4 Services

- [Virtual Filesystem](https://github.com/shadps4-emu/shadps4/blob/main/src/core/file_sys/fs.cpp): `src/core/file_sys/fs.cpp`
- [Guest IPC](https://github.com/shadps4-emu/shadps4/blob/main/src/core/ipc/ipc.cpp): `src/core/ipc/ipc.cpp`
- [PS4 Libraries](https://github.com/shadps4-emu/shadps4/blob/main/src/core/libraries/libs.cpp): `src/core/libraries/libs.cpp`
- [User Services](https://github.com/shadps4-emu/shadps4/blob/main/src/core/libraries/system/userservice.h): `src/core/libraries/system/userservice.h`

### Graphics

- [Shader Compiler](https://github.com/shadps4-emu/shadps4/blob/main/src/shader_recompiler/ir/program.cpp): `src/shader_recompiler/ir/program.cpp`
- [Vulkan Pipelines](https://github.com/shadps4-emu/shadps4/blob/main/src/video_core/renderer_vulkan/vk_graphics_pipeline.cpp): `src/video_core/renderer_vulkan/vk_graphics_pipeline.cpp`
- [Pipeline Cache](https://github.com/shadps4-emu/shadps4/blob/main/src/video_core/renderer_vulkan/vk_pipeline_cache.cpp): `src/video_core/renderer_vulkan/vk_pipeline_cache.cpp`
- [Cache Storage](https://github.com/shadps4-emu/shadps4/blob/main/src/video_core/cache_storage.cpp): `src/video_core/cache_storage.cpp`

### Host Integration

- [Controller Input](https://github.com/shadps4-emu/shadps4/blob/main/src/input/controller.cpp): `src/input/controller.cpp`
- [SDL Window](https://github.com/shadps4-emu/shadps4/blob/main/src/sdl_window.cpp): `src/sdl_window.cpp`
- [Debugger](https://github.com/shadps4-emu/shadps4/blob/main/src/core/debugger.cpp): `src/core/debugger.cpp`

### Other components

- **Player**

## Connections

- Player → CLI Entry: launches (evidence: `README.md`)
- CLI Entry → Emulator Runtime: starts (evidence: `src/main.cpp`)
- CLI Entry → Virtual Filesystem: configures (evidence: `src/main.cpp`)
- CLI Entry → Emulator Settings: configures (evidence: `src/main.cpp`)
- CLI Entry → Debugger: configures (evidence: `src/main.cpp`)
- Emulator Runtime → Emulator State: uses
- Emulator Runtime → Guest Address Space: uses
- Emulator Runtime → ELF Metadata: reads metadata
- Emulator Runtime → Guest IPC: dispatches
- Guest IPC → PS4 Libraries: dispatches
- PS4 Libraries → User Services: provides
- Controller Input → User Services: uses user IDs (evidence: `src/input/controller.cpp`)
- Pipeline Cache → Shader Compiler: requests compilation (evidence: `src/video_core/renderer_vulkan/vk_pipeline_cache.cpp`)
- Pipeline Cache → Cache Storage: loads and saves (evidence: `src/video_core/renderer_vulkan/vk_pipeline_cache.cpp`)
- Pipeline Cache → Vulkan Pipelines: creates pipelines
- Player → SDL Window: interacts
