GO — Healthy across the board

• Last commit today
• 20 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• GPL-2.0 licensed
• CI configured
• Tests present
• ⚠ GPL-2.0 is copyleft — check downstream compatibility

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

RPCS3 is a free, open-source PlayStation 3 emulator and debugger written in C++ that runs PS3 games on Windows, Linux, macOS, and FreeBSD. It translates PS3 CPU (PPU/SPU) and GPU instructions to x86-64 and modern graphics APIs (Vulkan/OpenGL), enabling full game execution with debugger support for reverse-engineering and development. Monolithic C++ application with modular subsystems: rpcs3/ contains the main emulator, .ci/ holds cross-platform CI scripts, 3rdparty/ vendors dependencies (7zip, OpenAL, MoltenVK, SoundTouch, GPUOpen), and .github/ defines workflows. Architecture separates CPU emulation (PPU/SPU cores), GPU backend (Vulkan/OpenGL renderers), audio (OpenAL), and UI (Qt) into distinct modules.

Game developers debugging PS3 titles, emulation enthusiasts testing game compatibility, reverse engineers studying PS3 architecture, and contributors maintaining the emulator across multiple platforms. Users range from casual testers validating game support to serious developers working on core CPU/GPU emulation subsystems.

RPCS3 is actively developed with continuous CI/CD across all major platforms (.ci/ contains build scripts for Linux, Windows, macOS, FreeBSD, and ARM), structured issue templates, and a large C++ codebase (17.4M lines). It has Discord/forum communities and a Patreon-supported team, indicating sustained production-grade effort, though PS3 emulation remains inherently complex and some games have compatibility gaps.

The codebase is heavy (17.4M C++ lines) with dependency complexity including Qt, Vulkan, OpenAL, and custom LLVM integration; single point of failure in core PPU/SPU emulation logic could break many games. The project depends on reverse-engineered PS3 firmware and closed-source graphics APIs, which creates legal ambiguity and maintenance brittleness when Sony updates security patches or driver incompatibilities emerge.

Active development on CPU/GPU accuracy, graphics API updates (Vulkan/OpenGL shader compilation), and platform-specific optimizations (macOS MoltenVK integration, Linux aarch64 support visible in .ci/build-linux-aarch64.sh). Recent CI additions show investment in LLVM setup (.ci/setup-llvm.sh, .ci/deploy-llvm.sh) and Qt translation updates (.ci/generate-qt-ts.sh).

git clone https://github.com/RPCS3/rpcs3.git && cd rpcs3 && git submodule update --init --recursive. Then see BUILDING.md for platform-specific build (CMake on Linux/Mac, Visual Studio on Windows, or clang via .ci/build-windows-clang.sh). Dependencies managed via CMake in 3rdparty/CMakeLists.txt.

Daily commands: After build: ./rpcs3 (Linux/Mac) or rpcs3.exe (Windows) with a valid PS3 game file. Debug builds via CMake with -DBUILD_TESTING=ON; use .gdbinit for GDB debugging. Run CI locally with .ci/build-linux.sh or .ci/build-windows.sh.

• .ci/build-windows.sh — Primary Windows build orchestration script; defines compiler flags, dependencies, and build configurations that all Windows contributors must understand
• .ci/build-linux.sh — Primary Linux build orchestration script; establishes Linux-specific toolchain setup and compilation strategy essential for cross-platform developers
• 3rdparty/CMakeLists.txt — Central third-party dependency management; controls compilation of 25+ external libraries (LLVM, OpenGL, audio, input) that the emulator depends on
• .github/workflows/rpcs3.yml — CI/CD pipeline definition; orchestrates automated builds across Windows, Linux, macOS, FreeBSD—critical for understanding release and validation flow
• .clang-format — Code style and formatting standard enforced across all contributions; non-compliance blocks merges
• .gitmodules — Git submodule configuration tracking external dependencies (asmjit, glslang, MoltenVK); necessary for proper repository initialization

Add Support for a New Graphics Backend

1. Update 3rdparty/CMakeLists.txt to conditionally include new graphics API (e.g., DirectX 12, Metal native) and link required libraries (3rdparty/CMakeLists.txt)
2. Create platform-specific build flag detection in CI scripts (e.g., add -DGRAPHICS_BACKEND=VK flag parsing in build-linux.sh) (.ci/build-linux.sh)
3. Update .github/workflows/rpcs3.yml to test new backend across all four platforms (Windows/Linux/macOS/FreeBSD matrix) (.github/workflows/rpcs3.yml)
4. Add backend-specific shader compilation logic referencing 3rdparty/glslang if cross-compilation needed (3rdparty/glslang/CMakeLists.txt)

Add Support for a New Input Device or Controller

1. Update libSDL wrapper in 3rdparty/libsdl-org/CMakeLists.txt to enable new input device codecs (3rdparty/libsdl-org/CMakeLists.txt)
2. Add HID API support or extend hidapi configuration in 3rdparty/hidapi/CMakeLists.txt for raw device communication (3rdparty/hidapi/CMakeLists.txt)
3. Update platform-specific build scripts (.ci/build-*.sh) to link new device driver libraries and set platform-specific USB/HID flags (.ci/build-windows.sh)

Add a New Audio Processing Feature

1. Extend OpenAL configuration or add SoundTouch (tempo/pitch) library in 3rdparty/OpenAL/CMakeLists.txt and 3rdparty/SoundTouch/CMakeLists.txt (3rdparty/OpenAL/CMakeLists.txt)
2. Update cubeb audio sink configuration in 3rdparty/cubeb/CMakeLists.txt to expose new audio driver options (WASAPI on Windows, PulseAudio on Linux, etc.) (3rdparty/cubeb/CMakeLists.txt)
3. Add audio backend feature flag to CI matrix in .github/workflows/rpcs3.yml and verify across platforms (.github/workflows/rpcs3.yml)

Add Support for a New Platform (e.g., ARM Linux)

1. Create new build script .ci/build-linux-aarch64.sh modeled after .ci/build-linux.sh but with ARM-specific compiler flags and asmjit cross-compilation (.ci/build-linux-aarch64.sh)
2. Update 3rdparty/DetectArchitecture.cmake to identify ARM/AArch64 and conditionally disable or adapt JIT recompilation for target architecture (3rdparty/DetectArchitecture.cmake)
3. Add new platform job to GitHub Actions workflow .github/workflows/rpcs3.yml with architecture-specific runners and build matrix (.github/workflows/rpcs3.yml)

• CMake + C++ — Cross-platform build orchestration essential for supporting Windows (MSVC/Clang), Linux (GCC/Clang), macOS (Clang), and FreeBSD; C++ enables direct PS3 CPU/GPU emulation with JIT recompilation (asmjit)
• asmjit (x86/x64 JIT) — Dynamic recompilation of PS3 PowerPC instructions to native host CPU (x86-64 or ARM); critical for playable emulation performance
• Vulkan + MoltenVK + OpenGL — Abstracts graphics API across platforms; MoltenVK bridges Vulkan to Metal on macOS, enabling unified shader compilation via glslang
• OpenAL + cubeb — Cross-platform audio output supporting WASAPI (Windows), PulseAudio (Linux), Core Audio (macOS), etc.; decouples emulator from OS audio stack
• libSDL + hidapi — Unified input device abstraction (controllers, Move, light gun) across all platforms; hidapi enables raw USB/HID communication for obscure devices
• GitHub Actions CI Matrix — Automated multi-platform testing (Windows, Linux, macOS, FreeBSD) on every commit; prevents platform-specific regressions

• Vendored third-party libraries (asmjit, glslang, libusb, curl, etc.) instead of system packages

  • Why: Ensures reproducible builds and consistent feature sets across all platforms/distributions; avoids version skew and compatibility matrix explosion
  • Consequence: Larger repository size (~600 files) and build time; easier onboarding for new contributors (no system package discovery needed)

• CMake-based build instead of hand-written Makefiles or Meson

  • Why: Native Visual Studio project generation (.vcxproj) on Windows; simpler conditional logic for platform-specific dependencies
  • Consequence: CMake learning curve for contributors; configuration errors can be cryptic; slower incremental rebuilds vs monolithic Makefiles

• Single emulator binary supporting all games (no game-specific profiles)

  • Why: Simplifies maintenance and QA; forces generic, robust implementation of PS3 syscalls and hardware semantics
  • Consequence: Performance optimization per-game requires runtime detection and per-game config files; adds complexity to core emulation logic

• undefined

  • Why: undefined
  • Consequence: undefined

Submodules must be initialized (git submodule update --init --recursive) or build will fail silently. CMake requires specific LLVM version compatibility; see .ci/setup-llvm.sh for version pins. macOS builds need MoltenVK specifically configured (3rdparty/MoltenVK/CMakeLists.txt). Qt translation generation required before GUI build (see .ci/generate-qt-ts.sh). Platform-specific environment variables set in .ci/setup-windows-ci-vars.sh are not automatically inherited on local builds.

• Just-In-Time (JIT) Compilation — RPCS3 recompiles PS3 CPU instructions (PPU/SPU) to x86-64 at runtime for performance; understanding JIT trade-offs (compile time vs. execution speed) is essential for CPU emulation work
• Instruction Set Architecture (ISA) Translation — The core challenge: converting PS3 Cell processor ISA (64-bit PowerPC) to x86-64; requires deep knowledge of both architectures and register allocation
• Graphics API Abstraction Layer — RPCS3 emulates PS3's RSX (NVIDIA graphics) by translating to Vulkan/OpenGL; understanding API agnosticity prevents vendor lock-in and enables platform portability
• Memory-Mapped I/O — PS3 hardware (SPU local storage, GPU registers) uses memory-mapped interfaces; RPCS3 must virtualize this for safe emulation without direct hardware access
• Cell Processor Architecture (PPU/SPU) — PS3's heterogeneous CPU (1 PPU + 7 SPUs) requires emulating both scalar and vector execution; SPU local storage and PPU coherency are emulation bottlenecks
• Shader Compilation and Caching — RPCS3 converts PS3 GPU shaders (RSX microcode) to GLSL/SPIR-V; caching prevents recompilation stalls and is critical for frame rate consistency
• Cross-Platform Binary Compatibility — RPCS3 supports 5+ platforms (Windows, Linux, macOS, FreeBSD, aarch64) with divergent ABIs; CMake and conditional compilation (.ci/ scripts) manage this complexity

• dolphin-emu/dolphin — GameCube/Wii emulator with similar JIT recompilation and graphics backend architecture; useful for studying CPU emulation patterns
• RetroArch/RetroArch — Multi-system emulator framework with modular core design; RPCS3 contributors reference for UI and plugin systems
• KHRONOS-Group/Vulkan-ValidationLayers — Critical for validating Vulkan rendering correctness in RPCS3's GPU emulation pipeline
• RPCS3/llvm-mirror — Forked LLVM used by RPCS3 for PPU/SPU JIT compilation; custom patches for PS3 instruction set support
• libav/libav — Video codec support for PS3 game cutscenes and streaming features in emulator

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 comprehensive CI workflow for FreeBSD builds

The repo has .ci/build-freebsd.sh and .ci/install-freebsd.sh scripts but no corresponding GitHub Actions workflow file (unlike rpcs3.yml for main platforms). This creates a maintenance gap where FreeBSD compatibility can regress undetected. Adding a .github/workflows/freebsd.yml would ensure FreeBSD builds are tested on every commit, improving platform coverage.

• [ ] Create .github/workflows/freebsd.yml following the pattern from .github/workflows/rpcs3.yml
• [ ] Configure FreeBSD runner to execute .ci/build-freebsd.sh and .ci/install-freebsd.sh
• [ ] Add build status badge to README.md for FreeBSD platform parity with other platforms
• [ ] Test workflow triggers on pull requests and master branch commits

Add unit tests for architecture detection module

The file 3rdparty/DetectArchitecture.cmake is a critical build-time dependency that determines platform-specific compilation flags across all platforms (Windows, Linux, macOS, FreeBSD, ARM). Currently there appear to be no dedicated tests validating correct detection of various CPU architectures. Adding CMake-based unit tests would prevent regressions in cross-platform builds, especially for less common architectures like ARM64.

• [ ] Create 3rdparty/tests/CMakeLists.txt for architecture detection tests
• [ ] Add test cases in 3rdparty/tests/test_detect_architecture.cmake covering x86_64, x86, ARM64, ARM, and PowerPC detection
• [ ] Integrate test execution into .github/workflows/rpcs3.yml build matrix
• [ ] Document expected behavior for edge cases in .github/CONTRIBUTING.md

Create deployment verification workflow for release artifacts

Multiple deployment scripts exist (.ci/deploy-windows.sh, .ci/deploy-mac.sh, .ci/deploy-linux.sh, .ci/github-upload.sh) but no GitHub Actions workflow validates that artifacts are correctly deployed and accessible post-release. This creates risk of broken releases going undetected. Adding a .github/workflows/verify-deployment.yml would test artifact integrity, checksums, and availability on release tags.

• [ ] Create .github/workflows/verify-deployment.yml triggered on release creation
• [ ] Add validation steps: verify artifact checksums, test download links, validate executable signatures for macOS/Windows
• [ ] Integrate with existing .ci/github-upload.sh to post verification results as release comments
• [ ] Document release process updates in .github/CONTRIBUTING.md

• Add unit tests for PPU/SPU instruction decoding in core emulation (rpcs3/Emu/CPU/) — currently missing explicit test coverage visible in file list, critical for regression detection
• Improve cmake error messages in 3rdparty/DetectArchitecture.cmake when architecture detection fails on ARM64 systems — currently vague, blocks aarch64 contributors
• Document expected LLVM versions and binary locations in BUILDING.md — .ci/setup-llvm.sh and .ci/deploy-llvm.sh show complexity but setup guide lacks concrete version constraints

RPCS3 demonstrates moderate security practices for an open-source C++ project. The codebase shows good separation of concerns with clear CI/CD pipelines and documented build processes. However, key concerns include: (1) potential credential exposure in CI/CD scripts, (2) extensive third-party dependencies requiring proactive scanning, (3) shell script security in build automation, and (4) absence of formal security disclosure policy. The project would benefit from automated dependency scanning, environment variable validation, and formal security documentation. As a desktop emulator, the primary attack surface is through malicious PS3 game images and memory corruption vulnerabilities, which require fuzzing and memory safety analysis beyond static analysis scope.

• Medium · Potential Hardcoded Credentials in CI/CD Scripts — .ci/get_keys-windows.sh. File '.ci/get_keys-windows.sh' suggests key retrieval logic that may expose sensitive credentials or API keys. If keys are hardcoded or stored in version control, this poses a credential exposure risk. Fix: Use secure credential management systems (GitHub Secrets, HashiCorp Vault, or environment variables). Never commit keys or credentials to version control. Implement secret scanning tools in CI/CD pipeline.
• Medium · Unvalidated Environment Configuration — .ci/docker.env, .ci/setup-windows-ci-vars.sh, .ci/setup-windows.sh. Multiple CI/CD environment files (.ci/docker.env, .ci/setup-windows-ci-vars.sh) are present. If these files contain unvalidated environment variables used in build processes, they could be exploited for injection attacks or misconfiguration. Fix: Validate and sanitize all environment variables before use. Document required variables. Use strong typing for configuration. Avoid eval() or similar dynamic code execution on environment variables.
• Medium · Third-Party Dependency Management Risks — 3rdparty/ directory (all subdirectories). The repository includes numerous third-party libraries (asmjit, glslang, cubeb, curl, OpenAL, etc.) as submodules or vendored code. Without visible dependency scanning and version pinning, there's risk of using vulnerable versions of dependencies. Fix: Implement automated dependency scanning (OWASP Dependency-Check, Snyk, or GitHub Dependabot). Pin all dependency versions explicitly. Regularly audit and update dependencies. Maintain a Software Bill of Materials (SBOM).
• Low · No Visible Security Policy — .github/. While CONTRIBUTING.md exists, there's no evidence of a SECURITY.md file or security disclosure policy in the visible repository structure. Fix: Create a SECURITY.md file outlining vulnerability disclosure procedures, responsible reporting guidelines, and security contact information.
• Low · Multi-Platform Build Scripts with Potential Shell Injection — .ci/*.sh files (build-*.sh, deploy-*.sh, setup-*.sh, etc.). Numerous shell scripts (.sh files) in .ci/ directory execute build and deployment commands. Without proper input validation, these could be vulnerable to shell injection if parameters are user-controlled. Fix: Use shellcheck to identify vulnerabilities. Quote all variable expansions. Avoid eval() or dynamic code execution. Validate input parameters strictly. Consider using Python or Go for cross-platform automation instead of bash.
• Low · Missing Security Headers Configuration — Build configuration (implicit). No visible security headers or CORS configuration in the build artifacts. If the emulator includes web-based components or API endpoints, this could be a risk. Fix: If any web interface exists, implement proper security headers (CSP, X-Frame-Options, X-Content-Type-Options, HSTS). Document all network endpoints and authentication mechanisms.

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

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

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/RPCS3/rpcs3 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.

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

What it runs against: a local clone of RPCS3/rpcs3 — 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 RPCS3/rpcs3 | 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 master 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 RPCS3/rpcs3. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/RPCS3/rpcs3.git
#   cd rpcs3
#
# 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 RPCS3/rpcs3 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "RPCS3/rpcs3(\\.git)?\\b" \\
  && ok "origin remote is RPCS3/rpcs3" \\
  || miss "origin remote is not RPCS3/rpcs3 (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f ".ci/build-windows.sh" \\
  && ok ".ci/build-windows.sh" \\
  || miss "missing critical file: .ci/build-windows.sh"
test -f ".ci/build-linux.sh" \\
  && ok ".ci/build-linux.sh" \\
  || miss "missing critical file: .ci/build-linux.sh"
test -f "3rdparty/CMakeLists.txt" \\
  && ok "3rdparty/CMakeLists.txt" \\
  || miss "missing critical file: 3rdparty/CMakeLists.txt"
test -f ".github/workflows/rpcs3.yml" \\
  && ok ".github/workflows/rpcs3.yml" \\
  || miss "missing critical file: .github/workflows/rpcs3.yml"
test -f ".clang-format" \\
  && ok ".clang-format" \\
  || miss "missing critical file: .clang-format"

# 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/RPCS3/rpcs3"
  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).

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