If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/shadps4-emu/shadPS4 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 19 active contributors
• Distributed ownership (top contributor 18% of recent commits)
• GPL-2.0 licensed
• CI configured
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live shadps4-emu/shadPS4 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/shadps4-emu/shadPS4.

What it runs against: a local clone of shadps4-emu/shadPS4 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in shadps4-emu/shadPS4 | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of shadps4-emu/shadPS4. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/shadps4-emu/shadPS4.git
#   cd shadPS4
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of shadps4-emu/shadPS4 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "shadps4-emu/shadPS4(\\.git)?\\b" \\
  && ok "origin remote is shadps4-emu/shadPS4" \\
  || miss "origin remote is not shadps4-emu/shadPS4 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "src/common/config.h" \\
  && ok "src/common/config.h" \\
  || miss "missing critical file: src/common/config.h"
test -f "scripts/aerolib.inl" \\
  && ok "scripts/aerolib.inl" \\
  || miss "missing critical file: scripts/aerolib.inl"
test -f "externals/gcn/include/gcn/si_ci_vi_merged_pm4_it_opcodes.h" \\
  && ok "externals/gcn/include/gcn/si_ci_vi_merged_pm4_it_opcodes.h" \\
  || miss "missing critical file: externals/gcn/include/gcn/si_ci_vi_merged_pm4_it_opcodes.h"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/shadps4-emu/shadPS4"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

shadPS4 is a PlayStation 4 emulator written in C++ that translates PS4 machine code and GPU instructions to run on Windows, Linux, macOS, and FreeBSD. It implements CPU emulation, GPU rendering via graphics APIs, and PlayStation system libraries to enable commercial PS4 games like Bloodborne, Yakuza 0, and DRIVECLUB to execute on non-console hardware. Monolithic C++ project: core emulator logic likely in src/ directories (not fully enumerated), CPU/GPU emulation components, syscall/library stubs for PS4 system calls, FFmpeg integration for video decoding (FindFFmpeg.cmake), and half-precision float support (Findhalf.cmake). Build system is CMake with platform-specific presets (CMakeWindowsPresets.json, CMakeLinuxPresets.json, CMakeDarwinPresets.json). QtLauncher (separate repo) provides the GUI wrapper.

Game emulation enthusiasts and reverse-engineers who want to play PS4 titles on PC; C++ systems programmers interested in low-level CPU/GPU emulation and syscall translation; game preservation advocates documenting PlayStation 4 behavior.

Early-stage but actively developed: 26M lines of C++ indicate substantial implementation, public Discord with active community engagement, CI/CD workflows present (.github/workflows/build.yml), and multi-platform support (Windows/Linux/macOS/FreeBSD). Project is experimental—README explicitly states 'shadPS4 is early in development, don't expect a [complete implementation]', so production use is not recommended.

Standard open source risks apply.

Active development on multi-platform support (Linux AppImage builds in .github/linux-appimage-sdl.sh, macOS bundle configuration in dist/MacOSBundleInfo.plist.in), game compatibility improvements tracked externally at shadps4-game-compatibility repo, and likely ongoing CPU/GPU instruction implementation. Desktop integration ongoing (net.shadps4.shadPS4.desktop, metainfo.xml for Linux package managers).

Clone and build with CMake: git clone https://github.com/shadps4-emu/shadPS4.git && cd shadPS4 && mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release && cmake --build . (use appropriate CMakePresets.json for your OS: CMakeWindowsPresets.json for Windows, CMakeLinuxPresets.json for Linux, CMakeDarwinPresets.json for macOS). Requires C++17-capable compiler, CMake 3.16+, FFmpeg dev libraries, and platform-specific dependencies (SDL2 for input/windowing based on .github/linux-appimage-sdl.sh).

Daily commands: No traditional 'dev server' (this is a native emulator, not web/server software). To run a game: build the project as above, then invoke the QtLauncher GUI (separate repo: shadps4-emu/shadps4-qtlauncher) or call the emulator binary directly with a PS4 game file path (exact CLI interface depends on main() implementation in src/, not visible in file list). Requires a valid PS4 game dump in acceptable format.

• CMakeLists.txt — Root build configuration orchestrating the entire emulator build, defining all dependencies and cross-platform compilation targets.
• src/common/config.h — Core configuration system that all modules depend on for runtime settings and feature flags.
• scripts/aerolib.inl — AeroLib function stubs that define the PS4 syscall/library interface—fundamental to emulation correctness.
• externals/gcn/include/gcn/si_ci_vi_merged_pm4_it_opcodes.h — GPU command processor opcode definitions required for graphics emulation on all architectures.
• .github/workflows/build.yml — CI/CD pipeline defining build and test processes across Windows, Linux, macOS, and FreeBSD platforms.
• CMakeWindowsPresets.json — Windows-specific build presets; essential for contributors on the primary development platform.

Add Support for a New PS4 Syscall

1. Define the syscall stub in the AeroLib function table with its number and signature (scripts/aerolib.inl)
2. Add the symbol name for debugging and tooling (scripts/ps4_names.txt)
3. Implement the syscall handler in the kernel emulation layer (typically in src/core or src/kernel directory) (src/common/config.h)
4. Add configuration flags if the syscall has optional behavior (src/common/config.cpp)

Add a New External Dependency (FFmpeg, xxHash, libusb, etc.)

1. Create or update the CMake find module in externals/ (cmake/FindFFmpeg.cmake)
2. Register the dependency in the main externals CMake (externals/CMakeLists.txt)
3. Update platform-specific presets with compiler flags and link paths (CMakeWindowsPresets.json)
4. Update build documentation for each platform (documents/building-windows.md)

Support a New GPU Feature or GCN Opcode

1. Add or update the opcode definition in the GCN header (externals/gcn/include/gcn/si_ci_vi_merged_pm4_it_opcodes.h)
2. Define associated register offsets if needed (externals/gcn/include/gcn/si_ci_vi_merged_offset.h)
3. Implement the GPU command processor handler (in src/gpu or src/graphics directory) (externals/gcn/CMakeLists.txt)
4. Add shader compilation/translation logic to Vulkan backend (src/common/decoder.cpp)

Extend Configuration with a New Feature Flag

1. Define the new config field in the config header (src/common/config.h)
2. Implement parsing and default values in config initialization (src/common/config.cpp)
3. Add environment variable or config file support for the flag (src/common/cstring.h)

• C++17/20 — High performance needed for CPU/GPU emulation with modern language features (concepts, bit manipulation, threads).
• CMake with presets (Windows/Linux/Darwin/FreeBSD) — Cross-platform build system essential for supporting Windows, Linux, macOS, and FreeBSD from a single codebase.
• Vulkan Graphics API — Cross-platform GPU abstraction layer enabling GCN shader translation to run on diverse hardware (NVIDIA, AMD, Intel, Apple).
• FFmpeg — Handles video and audio codec decoding (H.264, VP9, AAC) required for media playback in PS4 games.
• GCN (Graphics Core Next) ISA — PS4's GPU is AMD GCN-based; direct instruction set definitions enable accurate GPU emulation.
• AeroLib syscall interface — Defines PS4 system library calls; central contract between game code and emulator kernel.

• Full PS4 kernel emulation vs. thin wrapper

  • Why: Games rely on complex syscalls (threading, memory, IPC); full emulation necessary for compatibility.
  • Consequence: Large, complex codebase but high game compatibility; alternative would only support simpler titles.

• Vulkan backend for GPU (vs. direct GPU simulation)

  • Why: Simulating GCN hardware fully would be extremely slow; Vulkan translation trades accuracy for usability.
  • Consequence: Some advanced GPU features or edge cases may not emulate perfectly, but real-time playable framerates achieved.

• Cross-platform support (4 OS targets) vs. single-platform focus

  • Why: Community demand and market coverage; prevents lock-in to one OS.
  • Consequence: CI/CD complexity, platform-specific bugs, but wider user reach and contribution base.

• Modular external dependencies (FFmpeg, libusb, xxHash) vs. statically linked

  • Why: Reduces binary size, allows users to substitute system libraries, simplifies updates.
  • Consequence: Build-time discovery and linking overhead; users must have dependencies installed.

• Not a PS4 emulator for ARM/mobile platforms (Windows, Linux, macOS, FreeBSD desktop only).
• Does not emulate network functionality or

PS4 game dumps must be in specific format (likely ELF or PS4-native container); emulator expects valid PS4 BIOS/firmware files (not included in repo for legal reasons—users must obtain separately). FFmpeg, libusb, and half-precision float library must be installed system-wide or found by CMake (Findhalf.cmake, Findlibusb.cmake indicate optional dependencies that may silently disable features if missing). RenderDoc integration (FindRenderDoc.cmake) is optional but useful for GPU debugging. No obvious environment variables documented; assume standard CMAKE_BUILD_TYPE and CMAKE_PREFIX_PATH apply. Multi-platform CI suggests platform-specific bugs are likely (SDL2 initialization, graphics API selection).

• Binary Translation / JIT Compilation — PS4 uses x86-64 CPU instructions; shadPS4 must convert or interpret these for host execution—understanding JIT vs. interpretation tradeoffs is essential for CPU emulation work
• GPU Command Stream Translation — PS4 GPU issues AMDGCN commands; shadPS4 must translate these to Vulkan/OpenGL/DirectX equivalents—critical for graphics fidelity and performance
• System Call (Syscall) Emulation — PS4 games invoke syscalls for OS services (file I/O, memory management, threading); shadPS4 must stub or proxy these calls correctly
• Memory Management & Virtual Addressing — PS4 games assume contiguous unified memory; shadPS4 must map PS4 virtual addresses to host RAM and handle protection faults transparently
• SPIR-V / Shader Compilation — PS4 GPU shaders are AMDGCN bytecode; conversion to SPIR-V or native shader languages is required for graphics API portability
• Reverse Engineering & ISA Documentation — PS4 hardware details are proprietary; emulator development relies on community reverse-engineering of instruction encodings, syscall signatures, and library ABIs
• FFmpeg Integration for Multimedia — PS4 games use proprietary video codecs (MPEG, H.264); FFmpeg provides hardware-accelerated decoding, visible in cmake/FindFFmpeg.cmake

• shadps4-emu/shadps4-qtlauncher — Official GUI frontend for shadPS4; provides the user-facing launcher and settings interface
• shadps4-emu/shadps4-game-compatibility — Community-maintained database of game compatibility; tracks which PS4 games run and their known issues
• RPCS3/rpcs3 — PlayStation 3 emulator in C++; similar architecture for CPU/GPU emulation and syscall handling, useful architectural reference
• dolphin-emu/dolphin — Nintendo Wii/GameCube emulator; mature reference implementation for multi-platform native emulation with similar GPU translation challenges
• yuzu-emu/yuzu — Nintendo Switch emulator; contemporary PS4 emulation effort with similar ARM64 JIT and GPU command stream translation problems

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CMake configuration validation CI workflow

The repo has 5 platform-specific CMake preset files (CMakePresets.json, CMakeDarwinPresets.json, CMakeLinuxPresets.json, CMakeWindowsPresets.json, CMakeSettings.json) but no CI workflow to validate they parse correctly and don't have syntax errors. This prevents silent configuration regressions. The existing .github/workflows/build.yml could be extended or a new workflow created to validate all preset files.

• [ ] Create .github/workflows/validate-cmake-presets.yml that runs on PRs touching CMake*Presets.json files
• [ ] Add cmake --list-presets validation step to ensure all presets are syntactically valid
• [ ] Add a step to verify no duplicate preset names across all preset files
• [ ] Document the validation process in CONTRIBUTING.md

Create integration tests for external dependencies in externals/

The externals/ directory contains multiple subdependencies (aacdec, and others referenced in externals/CMakeLists.txt) but there's no test suite validating that these external libraries integrate correctly with the main codebase. Adding integration tests would catch breaking changes early. Start with the aacdec module since it's listed and likely has audio-related functionality.

• [ ] Create src/tests/externals/ directory for integration tests
• [ ] Add a test fixture that verifies aacdec CMakeLists.txt builds without errors
• [ ] Add a test that validates the aacdec linking works correctly in the main emulator target
• [ ] Document expected external dependency behavior in documents/building-linux.md (currently missing externals setup details)

Add platform-specific build documentation with CMake preset examples

While documents/building-{linux,macos,windows}.md exist, they don't reference the platform-specific CMake preset files (CMakeDarwinPresets.json, CMakeLinuxPresets.json, CMakeWindowsPresets.json). New contributors don't know which preset to use. This creates friction and duplicate support questions.

• [ ] Update documents/building-linux.md to show: cmake --preset linux-<variant> command with preset names from CMakeLinuxPresets.json
• [ ] Update documents/building-macos.md to reference CMakeDarwinPresets.json with available macOS presets (arm64, x86_64)
• [ ] Update documents/building-windows.md to reference CMakeWindowsPresets.json with MSVC/Clang preset options
• [ ] Add a troubleshooting section mentioning common CMake preset errors (e.g., missing dependencies defined in Findhalf.cmake, FindFFmpeg.cmake)

• Add unit tests for CPU instruction decoding: CPU emulation likely lacks comprehensive test coverage; create a test suite in tests/cpu/ that verifies opcode parsing for all implemented instructions against official PS4 ISA documentation
• Document syscall mappings: Create a markdown file mapping PS4 syscall numbers to their implementations, cross-referencing src/kernel source files; helps new contributors understand system call organization without code archaeology
• Improve game compatibility database integration: Add a script in tools/ that fetches latest game compatibility data from shadps4-game-compatibility repo and generates a searchable in-app database; currently users must visit external website

The shadPS4 emulator codebase shows a reasonable security posture for an open-source project. No critical vulnerabilities were identified in the visible structure. Main concerns are: (1) bundled external dependencies without clear update mechanisms, (2) lack of integrated security scanning in CI/CD pipeline, (3) no code signing/release verification mechanism, and (4) Docker configuration lacking security hardening. The project follows best practices with clear licensing (REUSE compliance), issue templates, and documented contribution guidelines. Recommendations focus on strengthening dependency management, adding automated security checks, and implementing release integrity measures.

• Low · Potential Hardcoded Credentials in Scripts — scripts/aerolib.inl, scripts/ps4_names.txt. The scripts directory contains aerolib.inl and ps4_names.txt which may contain sensitive configuration or API keys. While the file structure doesn't immediately reveal secrets, emulator projects sometimes embed API keys or authentication tokens in script files. Fix: Review script files to ensure no credentials, API keys, or sensitive tokens are hardcoded. Use environment variables or secure configuration management for any sensitive data.
• Low · External Dependencies in Externals Directory — externals/aacdec/, externals/gcn/, externals/renderdoc/, externals/stb/. The project includes external dependencies (aacdec, gcn, renderdoc, stb) that are bundled rather than managed through package managers. These may not receive regular security updates and could contain outdated vulnerable code. Fix: Audit bundled external libraries for known vulnerabilities. Consider using package managers (vcpkg, Conan) to manage dependencies and receive security updates. Implement dependency scanning in CI/CD pipeline.
• Medium · Missing Security Headers and SBOM in CI/CD — .github/workflows/build.yml. The build workflow (build.yml) doesn't appear to include security scanning, SBOM generation, or dependency vulnerability checks based on the file structure provided. This could allow vulnerable dependencies to be shipped undetected. Fix: Integrate security tools into the CI/CD pipeline: SAST (SonarQube, Clang Static Analyzer), DAST, dependency scanning (Dependabot, Snyk), and SBOM generation. Add security checks to block builds with critical vulnerabilities.
• Low · Docker Image Build Without Security Scanning — documents/Docker Builder/.docker/Dockerfile. The Dockerfile in documents/Docker Builder lacks multi-stage builds, minimal base images, or security scanning. Container images could contain unnecessary packages or vulnerabilities. Fix: Use minimal base images (alpine, distroless). Implement multi-stage builds. Add Docker image scanning (Trivy, Grype) to CI/CD. Remove unnecessary packages and run as non-root user.
• Low · No Code Signing or Release Integrity Verification — .github/workflows/build.yml, release distribution. The project doesn't appear to have code signing or GPG signature verification for releases. Users cannot verify the authenticity of downloaded binaries. Fix: Implement code signing for releases using GPG or certificates. Publish signatures alongside releases. Document signature verification process for users. Use signed container images.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.