Overview

Relevant source files

ScePSX is a cross-platform PlayStation 1 emulator written entirely in C#. It provides cycle-accurate emulation of the original PlayStation hardware while offering modern enhancements such as resolution scaling, precision geometry improvements (PGXP), and multiple GPU rendering backends.

This documentation covers the complete emulator architecture, from the user interface layer down to the core hardware emulation. For platform-specific UI details, see User Interface. For core emulation components, see Core Emulation. For graphics subsystem details, see Graphics Subsystem.

Sources: README.md151-152 AvaloniaUI/UI/MainWindow.axaml.cs20

Project Scope

ScePSX emulates the following PlayStation hardware components:

Component	Implementation	Documentation
MIPS R3000A CPU	Full instruction set execution	CPU Emulation
GTE (Geometry Transform Engine)	3D transformation coprocessor	GTE
GPU	Command processing + multiple backends	Graphics Subsystem
SPU	24-voice audio synthesis with reverb	SPU
CD-ROM Drive	Disc reading with multiple format support	CD-ROM Subsystem
MDEC	Video decompression	MDEC
Controllers	Digital and analog controller emulation	Input and Controllers
Memory Cards	Save data management	Memory Card Management

Sources: README.md154-167

Key Features

Feature	Description	Implementation
Cross-Platform	Windows, Linux, macOS, Android	Avalonia UI + platform-specific renderers
Multiple GPU Backends	Software, OpenGL, Vulkan	Runtime-switchable via `GPUBackend` abstraction
PGXP Enhancement	Sub-pixel precision geometry	`PGXPVector` cache system
Save States	Full emulation state serialization	MessagePack-based compression
Resolution Scaling	Up to 4K internal resolution	Hardware backends only
Cheat Engine	Memory patching support	Cheat Code System
Memory Tools	Live memory editing and search	MemEdit
Netplay	Online multiplayer	NetPlayFrm
ReShade Integration	Post-processing effects	OpenGL/Vulkan backends

Sources: README.md154-167 AvaloniaUI/Utils/PSXHandler.cs32-33

System Architecture

ScePSX follows a layered architecture with clear separation between platform-specific UI code, orchestration logic, and the core emulation engine.

Three-Tier Architecture

Key Design Principles:

Platform Independence: Core emulation (ScePSX/Core.csproj) has no UI dependencies
Handler Pattern: PSXHandler implements callback interfaces (IRenderHandler, IAudioHandler, IRumbleHandler)
Backend Abstraction: GPU implementations share IGPU interface for runtime switching
Unified Settings: IniFile class provides consistent configuration across platforms

Sources: AvaloniaUI/UI/MainWindow.axaml.cs23-94 AvaloniaUI/Utils/PSXHandler.cs10-46 AvaloniaUI/ScePSX.csproj1-44

Core Component Relationships

The following diagram maps the major emulation components to their source files:

Component Responsibilities:

PSXCore: Main execution loop, frame timing, component lifecycle management
BUS: Memory address decoding using jump tables, memory-mapped I/O routing
CPU: MIPS R3000A instruction fetch, decode, execute, exception handling
GTE: 3D geometry transformations, lighting calculations, PGXP integration
GPU: GP0/GP1 command parsing, VRAM management, backend coordination
GPUBackend: Runtime backend selection and initialization
DMA: Block data transfers between memory regions and peripherals
SPU: 24-channel ADPCM audio, reverb processing, CD-DA mixing

Sources: AvaloniaUI/Utils/PSXHandler.cs299

Platform Support Matrix

ScePSX runs on multiple operating systems through different UI implementations:

Platform	UI Framework	Architectures	GPU Backends	Notes
Windows	Windows Forms	x86, x64, arm	Software, D2D, D3D, OpenGL, Vulkan	Most feature-complete
Windows	Avalonia	x64	Software, OpenGL, Vulkan	Single-file deployment
Linux	Avalonia	x64, arm, arm64, riscv64, loongarch64	Software, OpenGL, Vulkan	Requires OpenGL 3.3+ or Vulkan 1.1+
macOS	Avalonia	x64, arm64	Software, OpenGL, Vulkan	Vulkan via MoltenVK (not recommended)
Android	Avalonia Mobile	arm64-v8a, armeabi-v7a, x64	Software, OpenGL, Vulkan	Requires Android 5.0+

Build Configuration:

Core Library: ScePSX/Core.csproj (platform-agnostic, .NET 8.0)
Avalonia UI: AvaloniaUI/ScePSX.csproj (cross-platform desktop/mobile)
Windows Forms: WinUI/*.csproj (.NET Framework, Windows only)
Android: Android/*.csproj (.NET MAUI with Avalonia)

Sources: README.md247-256 AvaloniaUI/ScePSX.csproj1-44 .github/workflows/build-core.yml1-35

Technology Stack

Frameworks and Languages

Key Dependencies:

Modified MessagePack: Custom fork at ScePSX/Utils/MessagePack for save state compression (do not install via NuGet)
SDL2: Precompiled binaries in SDLLib directory for input and audio handling
Avalonia UI 11.3.11: Cross-platform XAML framework for desktop and mobile
Android SDK 33: Required for Android builds with .NET MAUI

Sources: README.md258-266 AvaloniaUI/ScePSX.csproj26-31

Emulation Accuracy

ScePSX implements cycle-accurate emulation of PlayStation hardware:

Timing Model

CPU Clock: 33.8688 MHz (NTSC) / 33.8580 MHz (PAL)
Frame Rate: 60 Hz (NTSC) / 50 Hz (PAL)
Cycles Per Frame: 564,480 (NTSC)
Sync Interval: Every 42 CPU cycles (configurable via SYNC_CPU_TICK)

The emulator synchronizes CPU, GPU, SPU, CDROM, and DMA operations at regular intervals to maintain timing accuracy while balancing performance.

Precision Enhancements

PGXP (Precision Geometry Extension for PlayStation):

Maintains high-precision vertex coordinates in PGXPVector cache
Reduces polygon wobble caused by integer vertex snapping
Configurable options:
- Base PGXP (use_pgxp)
- High precision mode (use_pgxp_highpos)
- Memory capture (use_pgxp_memcap)
- Affine correction (use_pgxp_aff)
- Perspective correction (use_perspective_correction)

Sources: AvaloniaUI/Utils/PSXHandler.cs273-283

Configuration System

Settings are stored in ScePSX.ini using the IniFile class:

Per-Game Configuration: Settings can be overridden on a per-game basis by creating section [GameID] in the INI file.

Sources: AvaloniaUI/Utils/PSXHandler.cs13 AvaloniaUI/Utils/PSXHandler.cs48-77 AvaloniaUI/Utils/PSXHandler.cs317-328

Main Execution Flow

The following diagram shows the startup sequence and main emulation loop:

Key Methods:

PSXHandler.LoadGame(): Initializes PSXCore with ROM and BIOS AvaloniaUI/Utils/PSXHandler.cs285-342
PSXCore.Start(): Launches the main emulation thread
PSXCore.PSX_EXECUTE(): Inner loop executing CPU cycles and synchronizing peripherals
PSXHandler.RenderFrame(): Callback receiving completed frame data
PSXHandler.PlaySamples(): Callback receiving audio samples

Sources: AvaloniaUI/UI/MainWindow.axaml.cs443-453 AvaloniaUI/Utils/PSXHandler.cs285-342

File Organization

The repository is organized by subsystem:

ScePSX/
├── ScePSX/                    # Core emulation library
│   ├── PSXCore.cs            # Main orchestrator
│   ├── Core/                 # Hardware components
│   │   ├── CPU.cs           # MIPS R3000A
│   │   ├── BUS.cs           # Memory management
│   │   ├── DMA.cs           # DMA controller
│   │   ├── GPU/             # Graphics subsystem
│   │   ├── SPU.cs           # Audio
│   │   └── CDROM.cs         # Disc drive
│   └── Utils/               # Helper classes
├── AvaloniaUI/               # Cross-platform UI
│   ├── UI/                  # XAML views
│   └── Utils/               # PSXHandler, rendering
├── WinUI/                    # Windows Forms UI
├── Android/                  # Android mobile UI
└── SDLLib/                   # SDL2 precompiled binaries

For detailed project structure and module relationships, see Project Structure.

Sources: AvaloniaUI/ScePSX.csproj42

Performance Characteristics

Memory Footprint (Windows)

Configuration	Memory Usage	Target Hardware
Software + D2D	~32 MB	Low-end systems
Software + D3D	~52 MB	Low-end systems
Software + OpenGL	~86 MB	Mainstream systems
Hardware OpenGL	~138 MB	Mainstream systems
Hardware Vulkan	~143 MB	High-end systems

Minimum System Requirements

CPU: Intel Celeron 3215U or equivalent (stable 60 FPS without enhancements)
GPU: OpenGL 3.3+ or Vulkan 1.1+ for hardware rendering
RAM: 512 MB minimum, 1 GB recommended
Storage: 10-30 MB depending on UI version

Sources: README.md169-187

Getting Started

To begin using ScePSX:

Installation: See Installation and Requirements for platform-specific setup
BIOS Setup: Place PlayStation BIOS file in bios/ directory
Load Games: See Loading and Playing Games
Configure Settings: See Configuration and Settings

For development information, see Development Guide.

Sources: README.md188-213

Overview

Relevant source files

Sources: README.md151-152 AvaloniaUI/UI/MainWindow.axaml.cs20

Project Scope

ScePSX emulates the following PlayStation hardware components:

Component	Implementation	Documentation
MIPS R3000A CPU	Full instruction set execution	CPU Emulation
GTE (Geometry Transform Engine)	3D transformation coprocessor	GTE
GPU	Command processing + multiple backends	Graphics Subsystem
SPU	24-voice audio synthesis with reverb	SPU
CD-ROM Drive	Disc reading with multiple format support	CD-ROM Subsystem
MDEC	Video decompression	MDEC
Controllers	Digital and analog controller emulation	Input and Controllers
Memory Cards	Save data management	Memory Card Management

Sources: README.md154-167

Key Features

Feature	Description	Implementation
Cross-Platform	Windows, Linux, macOS, Android	Avalonia UI + platform-specific renderers
Multiple GPU Backends	Software, OpenGL, Vulkan	Runtime-switchable via `GPUBackend` abstraction
PGXP Enhancement	Sub-pixel precision geometry	`PGXPVector` cache system
Save States	Full emulation state serialization	MessagePack-based compression
Resolution Scaling	Up to 4K internal resolution	Hardware backends only
Cheat Engine	Memory patching support	Cheat Code System
Memory Tools	Live memory editing and search	MemEdit
Netplay	Online multiplayer	NetPlayFrm
ReShade Integration	Post-processing effects	OpenGL/Vulkan backends

Sources: README.md154-167 AvaloniaUI/Utils/PSXHandler.cs32-33

System Architecture

ScePSX follows a layered architecture with clear separation between platform-specific UI code, orchestration logic, and the core emulation engine.

Three-Tier Architecture

Key Design Principles:

Platform Independence: Core emulation (ScePSX/Core.csproj) has no UI dependencies
Handler Pattern: PSXHandler implements callback interfaces (IRenderHandler, IAudioHandler, IRumbleHandler)
Backend Abstraction: GPU implementations share IGPU interface for runtime switching
Unified Settings: IniFile class provides consistent configuration across platforms

Sources: AvaloniaUI/UI/MainWindow.axaml.cs23-94 AvaloniaUI/Utils/PSXHandler.cs10-46 AvaloniaUI/ScePSX.csproj1-44

Core Component Relationships

The following diagram maps the major emulation components to their source files:

Component Responsibilities:

PSXCore: Main execution loop, frame timing, component lifecycle management
BUS: Memory address decoding using jump tables, memory-mapped I/O routing
CPU: MIPS R3000A instruction fetch, decode, execute, exception handling
GTE: 3D geometry transformations, lighting calculations, PGXP integration
GPU: GP0/GP1 command parsing, VRAM management, backend coordination
GPUBackend: Runtime backend selection and initialization
DMA: Block data transfers between memory regions and peripherals
SPU: 24-channel ADPCM audio, reverb processing, CD-DA mixing

Sources: AvaloniaUI/Utils/PSXHandler.cs299

Platform Support Matrix

ScePSX runs on multiple operating systems through different UI implementations:

Platform	UI Framework	Architectures	GPU Backends	Notes
Windows	Windows Forms	x86, x64, arm	Software, D2D, D3D, OpenGL, Vulkan	Most feature-complete
Windows	Avalonia	x64	Software, OpenGL, Vulkan	Single-file deployment
Linux	Avalonia	x64, arm, arm64, riscv64, loongarch64	Software, OpenGL, Vulkan	Requires OpenGL 3.3+ or Vulkan 1.1+
macOS	Avalonia	x64, arm64	Software, OpenGL, Vulkan	Vulkan via MoltenVK (not recommended)
Android	Avalonia Mobile	arm64-v8a, armeabi-v7a, x64	Software, OpenGL, Vulkan	Requires Android 5.0+

Build Configuration:

Core Library: ScePSX/Core.csproj (platform-agnostic, .NET 8.0)
Avalonia UI: AvaloniaUI/ScePSX.csproj (cross-platform desktop/mobile)
Windows Forms: WinUI/*.csproj (.NET Framework, Windows only)
Android: Android/*.csproj (.NET MAUI with Avalonia)

Sources: README.md247-256 AvaloniaUI/ScePSX.csproj1-44 .github/workflows/build-core.yml1-35

Technology Stack

Frameworks and Languages

Key Dependencies:

Modified MessagePack: Custom fork at ScePSX/Utils/MessagePack for save state compression (do not install via NuGet)
SDL2: Precompiled binaries in SDLLib directory for input and audio handling
Avalonia UI 11.3.11: Cross-platform XAML framework for desktop and mobile
Android SDK 33: Required for Android builds with .NET MAUI

Sources: README.md258-266 AvaloniaUI/ScePSX.csproj26-31

Emulation Accuracy

ScePSX implements cycle-accurate emulation of PlayStation hardware:

Timing Model

CPU Clock: 33.8688 MHz (NTSC) / 33.8580 MHz (PAL)
Frame Rate: 60 Hz (NTSC) / 50 Hz (PAL)
Cycles Per Frame: 564,480 (NTSC)
Sync Interval: Every 42 CPU cycles (configurable via SYNC_CPU_TICK)

The emulator synchronizes CPU, GPU, SPU, CDROM, and DMA operations at regular intervals to maintain timing accuracy while balancing performance.

Precision Enhancements

PGXP (Precision Geometry Extension for PlayStation):

Maintains high-precision vertex coordinates in PGXPVector cache
Reduces polygon wobble caused by integer vertex snapping
Configurable options:
- Base PGXP (use_pgxp)
- High precision mode (use_pgxp_highpos)
- Memory capture (use_pgxp_memcap)
- Affine correction (use_pgxp_aff)
- Perspective correction (use_perspective_correction)

Sources: AvaloniaUI/Utils/PSXHandler.cs273-283

Configuration System

Settings are stored in ScePSX.ini using the IniFile class:

Per-Game Configuration: Settings can be overridden on a per-game basis by creating section [GameID] in the INI file.

Sources: AvaloniaUI/Utils/PSXHandler.cs13 AvaloniaUI/Utils/PSXHandler.cs48-77 AvaloniaUI/Utils/PSXHandler.cs317-328

Main Execution Flow

The following diagram shows the startup sequence and main emulation loop:

Key Methods:

PSXHandler.LoadGame(): Initializes PSXCore with ROM and BIOS AvaloniaUI/Utils/PSXHandler.cs285-342
PSXCore.Start(): Launches the main emulation thread
PSXCore.PSX_EXECUTE(): Inner loop executing CPU cycles and synchronizing peripherals
PSXHandler.RenderFrame(): Callback receiving completed frame data
PSXHandler.PlaySamples(): Callback receiving audio samples

Sources: AvaloniaUI/UI/MainWindow.axaml.cs443-453 AvaloniaUI/Utils/PSXHandler.cs285-342

File Organization

The repository is organized by subsystem:

ScePSX/
├── ScePSX/                    # Core emulation library
│   ├── PSXCore.cs            # Main orchestrator
│   ├── Core/                 # Hardware components
│   │   ├── CPU.cs           # MIPS R3000A
│   │   ├── BUS.cs           # Memory management
│   │   ├── DMA.cs           # DMA controller
│   │   ├── GPU/             # Graphics subsystem
│   │   ├── SPU.cs           # Audio
│   │   └── CDROM.cs         # Disc drive
│   └── Utils/               # Helper classes
├── AvaloniaUI/               # Cross-platform UI
│   ├── UI/                  # XAML views
│   └── Utils/               # PSXHandler, rendering
├── WinUI/                    # Windows Forms UI
├── Android/                  # Android mobile UI
└── SDLLib/                   # SDL2 precompiled binaries

For detailed project structure and module relationships, see Project Structure.

Sources: AvaloniaUI/ScePSX.csproj42

Performance Characteristics

Memory Footprint (Windows)

Configuration	Memory Usage	Target Hardware
Software + D2D	~32 MB	Low-end systems
Software + D3D	~52 MB	Low-end systems
Software + OpenGL	~86 MB	Mainstream systems
Hardware OpenGL	~138 MB	Mainstream systems
Hardware Vulkan	~143 MB	High-end systems

Minimum System Requirements

CPU: Intel Celeron 3215U or equivalent (stable 60 FPS without enhancements)
GPU: OpenGL 3.3+ or Vulkan 1.1+ for hardware rendering
RAM: 512 MB minimum, 1 GB recommended
Storage: 10-30 MB depending on UI version

Sources: README.md169-187

Getting Started

To begin using ScePSX:

Installation: See Installation and Requirements for platform-specific setup
BIOS Setup: Place PlayStation BIOS file in bios/ directory
Load Games: See Loading and Playing Games
Configure Settings: See Configuration and Settings

For development information, see Development Guide.

Sources: README.md188-213

Overview

Project Scope

Key Features

System Architecture

Three-Tier Architecture

Core Component Relationships

Platform Support Matrix

Technology Stack

Frameworks and Languages

Emulation Accuracy

Timing Model

Precision Enhancements

Configuration System

Main Execution Flow

File Organization

Performance Characteristics

Memory Footprint (Windows)

Minimum System Requirements

Getting Started

On this page

Overview

Project Scope

Key Features

System Architecture

Three-Tier Architecture

Core Component Relationships

Platform Support Matrix

Technology Stack

Frameworks and Languages

Emulation Accuracy

Timing Model

Precision Enhancements

Configuration System

Main Execution Flow

File Organization

Performance Characteristics

Memory Footprint (Windows)

Minimum System Requirements

Getting Started

On this page