|
Astro Bot
|
Saros
|
|
Neptunia ReVerse
|
SILENT HILL: The Short Message
|
|
Demon's Souls
|
UFC 6
|
And many more...
## Contributing Testing games and submitting detailed bug reports are useful ways to contribute. Search existing issues first, then use the **Game Emulation Status Report** template and attach the complete log file. **Pull requests for general fixes, architectural changes, or refactoring that do not address a concrete bug or launch problem in a specific game will be automatically closed.** **Large, unfocused commits or pull requests that bundle unrelated changes without a clear purpose or game-related benefit will also be automatically closed.** Keep each PR focused. Name the affected game, describe the exact problem, and provide evidence showing what the change fixes. Windows and Linux are the primary target platforms, so changes to shared code should not introduce regressions on either platform. Changes confined to a platform's own code paths only need to build on that platform. Because KytyPS5 is still evolving quickly, consider opening an issue before starting a large change. ### Formatting Set up the clang-format hook after cloning. Install `pre-commit` using the method appropriate for your platform: - **Arch Linux / CachyOS:** `sudo pacman -S pre-commit` - **Other Linux / macOS / Windows:** `python -m pip install pre-commit` Then install the Git hook: ```bash python -m pre_commit install --install-hooks ``` It formats staged `.cpp`, `.h`, and `.inc` files in `src`. ## Developer Information The PS5 graphics architecture is based on AMD RDNA 2. Use AMD's [RDNA 2 Instruction Set Architecture Reference Guide (document 70648)](https://docs.amd.com/v/u/en-US/rdna2-shader-instruction-set-architecture) as the primary instruction-encoding reference when working on shader decoding and recompilation. Important areas of the codebase: - [`src/graphics/shader/recompiler`](src/graphics/shader/recompiler) — instruction decoding, intermediate representation, control flow, resource tracking, and SPIR-V emission - [`src/graphics/guest_gpu`](src/graphics/guest_gpu) — PS5 (Prospero) GPU formats and command processing - [`src/graphics/host_gpu`](src/graphics/host_gpu) — Vulkan host backend and resource management - [`tests`](tests) — focused memory, shader, and resource-tracking regression tests The renderer targets Vulkan 1.3. Keep shader changes aligned with both the RDNA 2 ISA semantics and the Vulkan/SPIR-V validation rules. ## Building ### System requirements - Windows 10 version 1803, a current Linux distribution, or macOS on Apple Silicon - A 64-bit x86 processor (on macOS, an Apple Silicon processor with Rosetta 2) - A Vulkan 1.3-capable GPU with current drivers (on macOS, Vulkan is provided by the bundled MoltenVK) ### Build requirements (Windows) - Git - CMake 3.22.1 or newer - Ninja - Visual Studio 2022 or Build Tools 2022 with the **Desktop development with C++** workload and **C++ Clang tools for Windows** component - Qt 6 for MSVC 2022 64-bit, including Concurrent, Network, and Widgets - [glslang](https://github.com/KhronosGroup/glslang/releases) (`glslang` or `glslangValidator`) on `PATH` - Python 3 on `PATH`; the bundled SPIRV-Tools runs it at configure time The Microsoft C++ compiler (`cl.exe`) is not supported; use `clang-cl`. Open an **x64 Native Tools Command Prompt for Visual Studio 2022** (or the equivalent Developer PowerShell), change to the repository root, and initialize the dependencies: ```powershell git submodule update --init --recursive ``` Configure the project. Replace the Qt path with the version installed on your system: ```powershell cmake -S . -B _Build/windows -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_PREFIX_PATH="C:/Qt/6.x.x/msvc2022_64" ``` Build the launcher and stage a runnable installation: ```powershell cmake --build _Build/windows --target launcher cmake --install _Build/windows --prefix _Build/windows/install ``` The finished application and its runtime dependencies will be placed in `_Build/windows/install`. ### Building on Linux Install the toolchain and the libraries the bundled SDL3 needs. Without the audio, Wayland, and udev development packages, SDL3 quietly configures itself without those backends, and the resulting build has no working audio or gamepad hotplug support: ```bash sudo apt-get install --no-install-recommends \ clang lld ninja-build cmake git glslang-tools python3 pkg-config \ libgl1-mesa-dev libx11-dev libxcursor-dev libxext-dev libxfixes-dev \ libxi-dev libxrandr-dev libxss-dev libxtst-dev libxkbcommon-dev \ libasound2-dev libpulse-dev libudev-dev libdbus-1-dev libwayland-dev wayland-protocols ``` Qt 6 (Concurrent, Network, and Widgets) is required for the launcher. Use your distribution's packages (`qt6-base-dev`) or an official Qt installation. ```bash git submodule update --init --recursive cmake -S . -B _Build/linux -G Ninja -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ -DCMAKE_PREFIX_PATH="$Qt6_DIR" cmake --build _Build/linux --target launcher --parallel cmake --install _Build/linux --prefix _Build/linux/install ``` The install step copies the Qt libraries and plugins next to the binaries, so `_Build/linux/install` runs without a matching system Qt installation. FFmpeg is linked statically from the pinned [KytyPS5 FFmpeg core](https://github.com/KytyPS5/ext-ffmpeg-core) release, including VP9 and WebM support. System FFmpeg packages are not required. To build `kyty_emulator` and the `kyty_tests` target without Qt, use a separate build directory: ```bash git submodule update --init --recursive cmake -S . -B _Build/linux-no-qt -G Ninja -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ -DKYTY_BUILD_LAUNCHER=OFF cmake --build _Build/linux-no-qt --target kyty_emulator kyty_tests --parallel ``` As on Windows, the MSVC compiler is not used; Clang is required. `cl.exe` is rejected at configure time. The CMake source root is the repository root. ### Building on NixOS A development shell provides Clang, CMake, Ninja, Qt 6, the Vulkan headers, and the SDL3 backend libraries. Enter it and configure exactly as on other Linux distributions; the shell exports `CMAKE_PREFIX_PATH` and `QT_PLUGIN_PATH`, so the `-DCMAKE_PREFIX_PATH="$Qt6_DIR"` argument is not needed: ```bash nix-shell # or: nix develop git submodule update --init --recursive cmake -S . -B _Build/linux -G Ninja -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ cmake --build _Build/linux --target launcher --parallel cmake --install _Build/linux --prefix _Build/linux/install ``` The configure step downloads the FFmpeg prebuilts and the `xbyak`, `zydis`, `zstd`, and ZArchive sources, so it needs network access; a fully sandboxed `nix build` would require vendoring those inputs. A Vulkan 1.3 driver must be available at runtime (on NixOS, `hardware.graphics.enable = true`). ### Building on Fedora and Fedora Atomic (Bazzite, Bluefin, Silverblue) On regular Fedora, install dependencies on the host. On Fedora Atomic variants such as Bazzite, Bluefin and Silverblue, use [Distrobox](https://distrobox.it/) and run the install and build steps inside the container. Keep the checkout in your home directory so it is shared with the container. Add `--nvidia` to the create command for hosts using the proprietary NVIDIA driver: ```bash distrobox create --name kyty-build --image registry.fedoraproject.org/fedora:latest distrobox enter kyty-build ``` Install the toolchain, Qt 6 and SDL3 dependencies: ```bash sudo dnf install -y \ clang lld ninja-build cmake git glslang python3 pkgconf-pkg-config \ mesa-libGL-devel libX11-devel libXcursor-devel libXext-devel libXfixes-devel \ libXi-devel libXrandr-devel libXScrnSaver-devel libXtst-devel libxkbcommon-devel \ alsa-lib-devel pulseaudio-libs-devel systemd-devel dbus-devel \ wayland-devel wayland-protocols-devel qt6-qtbase-devel ``` From the repository root, follow the launcher configure, build and install steps in [Building on Linux](#building-on-linux), omitting `-DCMAKE_PREFIX_PATH="$Qt6_DIR"`; CMake finds Fedora's packaged Qt 6 automatically. Run `./_Build/linux/install/launcher` on regular Fedora or inside the container. To launch a container build from the host, leave the container with `exit`, then run from the repository root: ```bash distrobox enter kyty-build -- ./_Build/linux/install/launcher ``` Qt libraries and plugins are bundled. You can also launch directly on a Fedora Atomic host if its other system libraries are compatible with the container build. ### Building on macOS macOS builds target x86-64 and run under Rosetta 2 on Apple Silicon, so the PS5's x86-64 game code executes through the same translation layer as the emulator itself. Prebuilt archives are attached to releases; the steps below are for building from source. Requirements: - An Apple Silicon Mac with Rosetta 2 installed (`softwareupdate --install-rosetta`) - Xcode (or the Command Line Tools) - Homebrew packages: `brew install cmake ninja glslang python` - Qt 6 (Concurrent, Network, and Widgets) with x86-64 support. The official Qt installation is universal and works; Homebrew's Qt is arm64-only and will not link ```bash git submodule update --init --recursive cmake -S . -B _Build/macos -G Ninja -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_OSX_ARCHITECTURES=x86_64 \ -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \ -DCMAKE_PREFIX_PATH="$Qt6_DIR" cmake --build _Build/macos --target launcher --parallel cmake --install _Build/macos --prefix _Build/macos/install ``` The build re-signs `kyty_emulator` with the JIT entitlements it needs to execute translated guest code; no manual signing step is required. When the launcher is built, the installation also produces `_Build/macos/install/KytyPS5.app` — double-click to launch the GUI. A flat `kyty_emulator` is kept for CLI usage. Vulkan comes from MoltenVK. Download `MoltenVK-macos.tar` from the [MoltenVK releases](https://github.com/KhronosGroup/MoltenVK/releases), then copy `MoltenVK/dynamic/dylib/macOS/libMoltenVK.dylib` next to the flat `kyty_emulator` (and, for the bundle, into `KytyPS5.app/Contents/Frameworks/`) and sign it with an ad hoc signature: ```bash codesign --force --sign - _Build/macos/install/libMoltenVK.dylib # For the bundle (if present): codesign --force --sign - _Build/macos/install/KytyPS5.app/Contents/Frameworks/libMoltenVK.dylib codesign --force --sign - _Build/macos/install/KytyPS5.app ``` Release archives already include a signed `libMoltenVK.dylib` (both flat and inside the bundle). ### Regression tests Build every regression executable and run the registered tests with: ```powershell cmake --build _Build/windows --target kyty_tests ctest --test-dir _Build/windows --output-on-failure ``` Use `_Build/linux` instead of `_Build/windows` for a Linux build. ### Visual Studio Code A ready-made Visual Studio Code setup is included in [`.vscode`](.vscode). It configures CMake Tools to build the project with Ninja and `clang-cl` and provides launch profiles for both `launcher.exe` and `kyty_emulator.exe`. It is Windows-only: VS Code settings cannot select a compiler per platform, so on Linux configure from the command line as shown above. Before using it: 1. Install the **CMake Tools** and **C/C++** extensions in Visual Studio Code. 2. Update `CMAKE_PREFIX_PATH` in [`.vscode/settings.json`](.vscode/settings.json) to point to your Qt 6 MSVC installation. 3. Update the `--game` path in [`.vscode/launch.json`](.vscode/launch.json) for the **Debug kyty_emulator** profile. 4. Open the repository in an x64 Visual Studio developer environment, configure the CMake project, and select a launch profile from **Run and Debug**. ## Running Update your graphics driver before reporting rendering problems. To use the graphical launcher: ```powershell .\_Build\windows\install\launcher.exe ``` ```bash ./_Build/linux/install/launcher ``` ```bash open _Build/macos/install/KytyPS5.app # or double-click in Finder ``` On first launch, add one or more game folders in the global settings. The launcher searches those folders recursively for game directories containing `eboot.bin` and ZArchive (`.zar`) game dumps whose archive root contains `eboot.bin`. Select a detected game and run it from the game list. ZArchive dumps are mounted read-only and streamed directly; they do not need to be extracted first. Official release builds include a built-in updater. Leave **Check for updates on startup** enabled, or click **Check for updates**, then choose **Install Update**. The launcher downloads the package for your platform from GitHub, checks its SHA-256 checksum, and restarts after installation. Close any running games first. Settings, saves, patches, and other files outside the release package are preserved; replacement failures restore the previous files. The installation folder must be writable. If a package cannot be installed automatically, the updater offers the GitHub release page. Source builds and builds from forks do not replace themselves with official releases. The emulator can also be started directly with a legally obtained game directory, ELF file, or ZArchive dump: ```powershell .\_Build\windows\install\kyty_emulator.exe --game "D:\Games\ExampleGame" .\_Build\windows\install\kyty_emulator.exe --game "D:\Games\ExampleGame.zar" ``` ```bash ./_Build/linux/install/kyty_emulator --game "/games/ExampleGame" ./_Build/linux/install/kyty_emulator --game "/games/ExampleGame.zar" ``` On macOS, the adjacent flat or app-bundled `libMoltenVK.dylib` is found automatically; no environment variable is required: ```bash ./_Build/macos/install/kyty_emulator --game "/games/ExampleGame" ``` To override the Vulkan loader, set `SDL_VULKAN_LIBRARY`: ```bash SDL_VULKAN_LIBRARY=/path/to/libMoltenVK.dylib ./kyty_emulator --game "/games/ExampleGame" ``` Run `kyty_emulator --help` to see the available graphics, logging, validation, profiling, and debugging options. ### AI Use AI tools may be used for research, reverse engineering, and development assistance. Contributors must fully understand, review, and test all code they submit and remain responsible for its correctness. Repository communication, including pull-request descriptions, code comments, and issue comments, must come from the human contributor rather than an autonomous AI agent. Pull requests that include AI-assisted or AI-generated work should disclose the scope of the AI involvement and describe the human review and testing performed before submission. Unverified or untested generated changes may be closed without review. ## License KytyPS5 is licensed under the [GNU General Public License version 2](LICENSE) (`GPL-2.0-only`). This project is based on the original [Kyty](https://github.com/InoriRus/Kyty), which was released under the MIT License. Kyty's original copyright and license notice are preserved in [`LICENSES/Kyty-MIT.txt`](LICENSES/Kyty-MIT.txt). Third-party components remain subject to the licenses included with those components. ## Special Thanks - [InoriRus/Kyty](https://github.com/InoriRus/Kyty) — KytyPS5 is based on a heavily modified version of the original Kyty project. - [shadps4-emu/shadPS4](https://github.com/shadps4-emu/shadPS4) — reference for understanding PS4 memory behavior, GPU resource aliasing, cache coherency, and the AVPlayer implementation.