GitHub - maxpoletaev/nupsx: PlayStation 1 emulator

nuPSX is an experimental PlayStation 1 emulator and debugger written in Zig, built as a learning exercise to explore Zig's capabilities and PSX hardware architecture. While I'm super proud of how far it has come, this is by no means an emulator that most would consider usable and complete. If you've come here for learning about emulation, this is probably a good project to dig into. If you are looking for the emulator to play games, better to check out DuckStation.

State

Can boot and play lots of commercial games (notably Crash Bandicoot and MGS) and homebrew demos. Some things are still missing or incomplete. Tested 2D games are mostly fine, 3D games may have minor graphical glitches. Sound system lacks certain effects but is functional enough to play music and most of sound effects in tested games.

🟥 Nothing - Doesn't boot or crashes the emulator
🟧 Intro - Boots into the title screen or main menu but doesn't get past it
🟨 InGame - Boots into the game but has major issues
🟩 Playable - Boots into the game with minor or no issues

Download

Below are links to the latest prebuilt binaries. I don't have enough computers so not all of them are tested.

• nupsx-aarch64-linux-gnu.zip
• nupsx-x86_64-linux-gnu.zip
• nupsx-macos.dmg (universal)
• nupsx-aarch64-macos.zip
• nupsx-x86_64-macos.zip
• nupsx-x86_64-windows.zip

Note for macOS users: macOS will quarantine downloaded binaries by default. If you get a warning that the app is damaged or cannot be opened, remove the quarantine attribute with: xattr -d com.apple.quarantine nupsx

Build & Run

git clone https://github.com/maxpoletaev/nupsx.git
cd nupsx
zig build --release=safe
./zig-out/bin/nupsx --bios SCPH1001.bin

Command Line Options

nuPSX - A PlayStation emulator

Usage: nupsx --bios <path> [options]

Options:
  --bios <path>        Path to BIOS file (required)
  --exe <path>         Path to executable file to run
  --cdrom <path>       Path to CD-ROM image file (.cue)
  --memcard <path>     Path to memory card image (default: ~/.nupsx/memcard.mcd)
  --debug              Enable debug user interface
  --disasm             Enable disassembly output
  --breakpoint <addr>  Set a breakpoint at the specified address (hexadecimal)
  --uncapped           Run the emulator without frame rate limiting
  --no-shader          Disable the CRT/NTSC shader
  --upscale <n>        Internal resolution scale, 1-4 (default: 1)
  -h, --help           Show this help message

Controls

    [ Q ]                    [ O ]
  _/[ E ]\_       ┆┆       _/[ U ]\_
 /         \--------------/         \
|    [W]    |            |    [I]    |
| [A]   [D] |            | [J]   [L] |
|    [S]    | SHFT ENTR⟩ |    [K]    |
|\_________/--------------\_________/|
|       /                    \       |
|      /                      \      |
 \____/                        \____/

  ↑ = W     △ = I     [START]  = Enter
  ← = A     ◻ = J     [SELECT] = R-Shift
  ↓ = S     × = K     [L1] = E  [R1] = U
  → = D     ◯ = L     [L2] = Q  [R2] = O

Dependencies

nuPSX relies on zig-gamedev libraries for graphics, audio and ImGui bindings.

Credits

Most of the knowledge comes from PSX-SPX Playstation Specifications by Martin "nocash" Korth.

Also special thanks to folks in EmuDev Discord for sharing tons of undocumented knowledge and getting me unstuck countless times.

Readings:

• PlayStation Emulation blog post series by James Groth
• PlayStation Emulation Guide (PDF) by Lionel "simias" Flandrin
• The PS1 GPU texture pipeline and how to emulate it reddit post by an unknown author

Tests and Demos:

• https://psx.amidog.se/doku.php
• https://github.com/PeterLemon/PSX
• https://github.com/JaCzekanski/ps1-tests

Referenced Projects:

• https://github.com/allkern/psxe
• https://github.com/stenzek/duckstation
• https://github.com/JaCzekanski/Avocado
• https://github.com/allkern/iris (shaders)