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/dolphin-emu/dolphin 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 2d ago
• 16 active contributors
• Distributed ownership (top contributor 37% of recent commits)
• Other licensed
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ 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 dolphin-emu/dolphin repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dolphin-emu/dolphin.

What it runs against: a local clone of dolphin-emu/dolphin — 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 dolphin-emu/dolphin | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dolphin-emu/dolphin. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dolphin-emu/dolphin.git
#   cd dolphin
#
# 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 dolphin-emu/dolphin and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f ".gitmodules" \\
  && ok ".gitmodules" \\
  || miss "missing critical file: .gitmodules"
test -f "Contributing.md" \\
  && ok "Contributing.md" \\
  || miss "missing critical file: Contributing.md"
test -f "CMake/DolphinCompileDefinitions.cmake" \\
  && ok "CMake/DolphinCompileDefinitions.cmake" \\
  || miss "missing critical file: CMake/DolphinCompileDefinitions.cmake"
test -f ".editorconfig" \\
  && ok ".editorconfig" \\
  || miss "missing critical file: .editorconfig"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/dolphin-emu/dolphin"
  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).

Dolphin is a high-fidelity GameCube and Wii emulator written in C++ that allows users to play authentic console games on Windows, Linux, macOS, and Android with graphical enhancements. It translates PowerPC CPU instructions and GC/Wii hardware into native code via JIT compilation, and supports modern graphics APIs (Direct3D 11.1, OpenGL 3.3+) for upscaling and shader improvements beyond original hardware capabilities. Monolithic C++ codebase organized by functional subsystem: Source/Core/PowerPC/ contains CPU emulation and JIT compilation, Source/Core/HW/ has hardware interface emulation (GPU, audio, input), Source/VideoCommon/ abstracts graphics backends, Source/Android/ and Source/UWP/ contain platform-specific UI code, Data/Sys/ houses firmware and system data, with CMake build orchestration across all platforms via top-level CMakeLists.txt and platform-specific configuration in CMake/ directory.

Retro gaming enthusiasts and developers who want to play GameCube/Wii games on PC with visual improvements; contributors are emulation engineers, graphics programmers, and platform maintainers working across Windows/Linux/macOS/Android native code.

Highly mature and actively developed: 15.4M lines of C++ code, well-established since 2003, comprehensive CI via buildbot (dolphin.ci), regular commits, and production-ready stable releases. The project maintains strict coding standards (Contributing.md), has GPLv2+ licensing, and ships official builds across all major platforms.

Low integration risk for end-users, but moderate complexity for contributors due to architecture spanning CPU emulation (PowerPC JIT), GPU drivers (Direct3D/OpenGL/Vulkan), and platform-specific code (Objective-C++ for macOS, Kotlin for Android). Large codebase (15K+ C++ files) with heavy dependency management (CMake custom finders for FFmpeg, HIDAPI, LibUSB, Vulkan) means build configuration can be fragile; requires latest compiler (C++20) and SDK versions.

Active development on graphics rendering improvements, platform compatibility (recent Android/macOS support), input handling, and performance optimizations. The buildbot tracks continuous integration, Transifex handles localization across languages, and the bug tracker at bugs.dolphin-emu.org shows prioritized issues. Recent work likely spans driver compatibility, JIT optimization, and multi-platform testing.

Clone with submodules: git clone --recurse-submodules https://github.com/dolphin-emu/dolphin.git && cd dolphin. On Windows: open Source/dolphin-emu.sln in Visual Studio. On Linux/macOS: mkdir build && cd build && cmake .. && make -j$(nproc). Ensure submodules are initialized: git submodule update --init --recursive.

Daily commands: After build: Windows: run generated dolphin.exe from build folder. Linux: ./build/Dolphin/dolphin-emu. macOS: ./build/Dolphin/Dolphin.app/Contents/MacOS/Dolphin. Android: build APK via gradle in Source/Android/. Launch emulator GUI, configure controller input (Input settings), point to GameCube/Wii game ISO files via File > Open, and select graphics backend (Rendering tab).

• CMakeLists.txt — Root build configuration that orchestrates the entire Dolphin build system across all platforms and dependencies.
• .gitmodules — Defines external dependencies as git submodules; critical for understanding the project's third-party code integration.
• Contributing.md — Establishes coding standards, contribution workflow, and architectural expectations that all pull requests must follow.
• CMake/DolphinCompileDefinitions.cmake — Centralizes compiler flags and feature definitions that control emulation capabilities and platform-specific behavior across the codebase.
• .editorconfig — Enforces consistent code formatting rules (indentation, line endings) to prevent style conflicts in pull requests.
• CODE_OF_CONDUCT.md — Community guidelines that define expected professional behavior for all contributors and maintainers.
• Data/Sys/ApprovedInis.json — Game-specific configuration whitelist that controls which per-game settings overrides are permitted.

Add Support for a New Platform Dependency

1. Create a new find-module in CMake/ that detects the library on the target platform (e.g., CMake/FindNewLib.cmake). Follow the pattern of existing modules like FindCUBEB.cmake or FindHIDAPI.cmake. (CMake/FindNewLib.cmake)
2. Update the root CMakeLists.txt to invoke find_package(NewLib) and link it to the main executable or library targets. (CMakeLists.txt)
3. Add conditional compilation flags or platform checks in CMake/DolphinCompileDefinitions.cmake if the library is platform-specific. (CMake/DolphinCompileDefinitions.cmake)
4. Document the dependency in Contributing.md, including build flags and platform-specific installation instructions. (Contributing.md)

Add a Per-Game Configuration Override

1. Create or edit the game's .ini file in Data/Sys/GameSettings/ using the GameCube or Wii game ID as the filename (e.g., Data/Sys/GameSettings/GAM3XX.ini). (Data/Sys/GameSettings/GAM3XX.ini)
2. Add configuration keys under appropriate sections [Core], [Display], [Audio], etc. matching the schema defined in Data/Sys/ApprovedInis.json. (Data/Sys/ApprovedInis.json)
3. If adding a new configuration key type, update ApprovedInis.json to whitelist it and document the key in Contributing.md. (Contributing.md)

Set Up Build on a New Operating System or Compiler

1. Add platform detection logic to CMakeLists.txt using CMAKE_SYSTEM_NAME or CMAKE_CXX_COMPILER_ID conditionals. (CMakeLists.txt)
2. Create or update a platform-specific find-module in CMake/ (e.g., CMake/FindPlatformToolchain.cmake) if the new OS has unique dependency paths. (CMake/FindPlatformToolchain.cmake)
3. Add compiler-specific flags in CMake/DolphinCompileDefinitions.cmake or CMake/FlagsOverride.cmake to suppress warnings or enable optimizations. (CMake/FlagsOverride.cmake)
4. Update Contributing.md and AndroidSetup.md with build prerequisites and environment setup for the new platform. (Contributing.md)

• CMake (cross-platform build system) — Enables single source build configuration for Windows, macOS, Linux, and Android with platform-specific dependency detection via modular find-modules.
• C++ with SSE2+ requirements — Core emulation demands high performance for cycle-accurate GameCube/Wii CPU/GPU simulation; SSE2 provides SIMD capabilities across older and modern x86/x64 hardware.
• Modular find-modules (FindALSA, FindCUBEB, etc.) — Isolates platform-specific library detection logic; allows graceful fallback or substitution (e.g., PulseAudio vs. ALSA on Linux) without modifying core build files.
• Per-game .ini configuration files (GameSettings/) — Allows game-specific compatibility workarounds and performance tuning without recompiling; whitelist validation via ApprovedInis.json prevents injection attacks.
• Data/Sys embedded resources (DSP ROMs, fonts, firmware) — GameCube and Wii emulation require authentic firmware/coprocessor images and boot fonts; bundled in the executable eliminates runtime lookup complexity.

• CMake over handwritten Makefiles or native build systems

  • Why: Single configuration source reduces maintenance burden across four major platforms; standardized module ecosystem.
  • Consequence: Adds CMake as a build-time dependency; slightly longer initial configure step; developers must learn CMake syntax for custom targets.

• SSE2 minimum CPU requirement

  • Why: Substantially accelerates emulation throughput via vectorized operations; modern CPU baseline assumption.
  • Consequence: Excludes pre-2005 hardware; limits portable/embedded deployments without fallback scalar code paths.

• Whitelist-based game configuration (ApprovedInis.json) over free-form .ini parsing

  • Why: Prevents malicious or malformed settings from crashing the emulator; controls scope of supported tweaks.
  • Consequence: New game settings require explicit schema approval; slower iteration for undocumented workarounds.

• Embedded Data/Sys/ (firmware, fonts) in binary vs. runtime file lookup

  • Why: Guarantees emulation functionality even if files are deleted or corrupted post-install; simplifies Windows portable builds.
  • Consequence: Increases binary size; harder to patch firmware without rebuild; users cannot easily swap custom ROMs.

• Does not support non-SSE2 CPUs or pre-2005 hardware.
• Does not provide a browser-based or cloud emulation interface.
• Does not include game ROM distribution or licensing infrastructure.
• Does not support real-time online multiplayer synchronization

Build requires explicit submodule initialization (git submodule update --init --recursive) or CMake will fail silently. C++20 compiler mandatory (MSVC 2022+, GCC 11+, Clang 13+); older toolchains will be rejected at CMake stage. Graphics driver choice (Direct3D/OpenGL/Vulkan) selected at compile time via CMake flags, not runtime—must rebuild to switch. macOS builds require SDKs in Xcode and may conflict with homebrew-installed libraries. Android builds require specific NDK/SDK versions configured in gradle.properties. Controller input requires SDL2 or native platform drivers (XInput on Windows, /dev/input on Linux) to detect—missing drivers silently disable controllers. Some tests assume Data/Sys/ firmware files present; unit tests may skip if not found.

• JIT (Just-In-Time) Compilation — Dolphin's core performance technique: PowerPC instructions are dynamically translated to native x64 code at runtime (Jit64.cpp), not interpreted; understanding cache invalidation and register allocation is critical for CPU emulation work
• Ring Buffer (Audio/DSP) — Dolphin uses ring buffers in CUBEB/OpenAL audio subsystem to synchronize emulated DSP output with host audio hardware without blocking; essential for understanding audio sync code
• Memory-Mapped I/O — GameCube/Wii hardware (GPU, audio, controllers) accessed via memory-mapped registers; Memmap.cpp and ProcessorInterface.cpp orchestrate MMIO read/write trapping to emulated devices
• Graphics API Abstraction / Backend Pattern — VideoCommon defines abstract Renderer interface with Direct3D11, OpenGL, Vulkan implementations; critical for porting Dolphin to new graphics targets and understanding shader compilation pipelines
• Instruction Cache Invalidation — When emulated code modifies itself (self-modifying code), JIT cache must be flushed and re-translated; Jit64.cpp manages this via address range tracking to maintain correctness
• Audio Ring Buffer Synchronization — DSP audio output fed into ring buffers to decouple emulation speed from host audio clock; prevents audio crackle and frame drops by buffering when emulation lags
• Multi-threading with Memory Barriers — Dolphin's CPU and GPU emulation run on separate threads with carefully placed memory barriers (Source/Core/Core.cpp); incorrect synchronization causes race conditions in graphics or controller state

• PCSX2/pcsx2 — PlayStation 2 emulator using similar architecture (JIT compilation, modular graphics backends, cross-platform builds); direct peer in console emulation space
• citra-emu/citra — Nintendo 3DS emulator sharing Dolphin's C++ architecture, Qt UI patterns, and graphics abstraction layer approach for multi-backend support
• yuzu-emu/yuzu — Nintendo Switch emulator derived from Citra codebase; uses similar Vulkan/OpenGL graphics patterns and multi-platform CMake build system as Dolphin
• dolphin-emu/dolphin-wiki — Official wiki documenting Dolphin's internals, game compatibility matrix, and development setup; essential reference for contributors understanding emulation details

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 validation and linting GitHub Action workflow

The repo has 30+ custom CMake files (CMake/*.cmake) but no automated validation. CMake syntax errors or inconsistencies could slip through. A GitHub Action using cmake-lint or similar tool would catch issues early and ensure consistency across FindXXX.cmake modules (FindFFmpeg.cmake, FindHIDAPI.cmake, etc.) which follow similar patterns but may have divergent styles.

• [ ] Create .github/workflows/cmake-lint.yml to run cmake-lint on CMake/ directory
• [ ] Configure cmake-lint to check for common issues in the 30+ custom CMake modules
• [ ] Test on existing CMake files to ensure no false positives
• [ ] Document the new workflow in Contributing.md with CMake contribution guidelines

Add platform-specific integration tests for CMake FindXXX modules

The CMake/FindXXX.cmake files (FindFFmpeg.cmake, FindCUBEB.cmake, FindMBEDTLS.cmake, etc.) are critical for cross-platform builds but lack automated validation. Contributors could break Linux/macOS/Windows builds without knowing. Add a test suite that validates these modules can locate dependencies on each platform.

• [ ] Create CMake/Tests/ directory with CMakeLists.txt for testing individual Find modules
• [ ] Add test project that tries to find key dependencies (FFmpeg, HIDAPI, LibUSB) on each platform
• [ ] Create GitHub Actions workflow (.github/workflows/cmake-find-modules.yml) to run tests on Linux, macOS, Windows
• [ ] Document in Contributing.md how to test CMake changes locally

Create Data/Sys/GameSettings validation and schema documentation

The repo contains 100+ game-specific .ini files (Data/Sys/GameSettings/*.ini) but there's no documented schema, validation tool, or tests. New contributors adding game settings can't easily validate correctness. Creating a schema file and validator would prevent malformed contributions and help maintainers review PRs faster.

• [ ] Document the GameSettings .ini format by analyzing existing files like D43.ini, DSR.ini, etc.
• [ ] Create Data/Sys/GameSettings/schema.json defining valid keys, sections, and value types
• [ ] Add a Python validation script (scripts/validate_game_settings.py) to check .ini files against schema
• [ ] Create GitHub Action (.github/workflows/validate-game-settings.yml) to run validation on PRs modifying Data/Sys/GameSettings/

• Add missing unit tests for Source/Core/HW/Memmap.cpp memory mapping functions; currently untested edge cases around address translation and page faulting could hide bugs
• Improve CMake Find modules (CMake/Find*.cmake) to auto-detect library versions and warn on outdated dependencies (e.g., FFmpeg <5.0 unsupported) instead of failing silently at link time
• Document platform-specific input configuration gaps: Source/Core/InputCommon/ControllerInterface/ lacks per-platform examples for custom button mapping beyond standard SDL2 gamepad profiles

Dolphin Emulator maintains a reasonable security posture for an open-source emulation project. The main concerns are around binary file integrity verification, proper validation of configuration files, and ensuring that USB device access rules are properly restricted. The codebase structure indicates good organization and the GPL licensing ensures transparency. No hardcoded credentials or obvious SQL injection vectors are apparent from the file structure. The project should prioritize implementing integrity verification for binary assets and comprehensive validation of game configuration files to mitigate potential supply chain and configuration-based attacks.

• Medium · USB Device Rules File Permissions — Data/51-usb-device.rules. The file 'Data/51-usb-device.rules' appears to be a udev rules file for USB device access. If this file grants overly permissive access to USB devices without proper restrictions, it could allow unauthorized access to hardware devices. Fix: Review the udev rules file to ensure it follows the principle of least privilege. Verify that USB device access is properly restricted to intended user groups and that device permissions are appropriately configured.
• Medium · Binary Game Configuration Files — Data/Sys/GC/dsp_rom.bin, Data/Sys/GC/dsp_coef.bin, Data/Sys/GC/font_*.bin. The repository contains multiple binary DSP ROM/coefficient files (dsp_rom.bin, dsp_coef.bin, font files) that are included in the codebase. These binary files cannot be easily audited for malicious content and may pose a supply chain risk. Fix: Implement binary file integrity verification using checksums or signatures. Document the origin and provenance of all binary files. Consider storing these files separately from source code or behind a verification mechanism.
• Low · Extensive Game Settings Configuration Files — Data/Sys/GameSettings/. The Data/Sys/GameSettings directory contains numerous .ini configuration files for individual games. While this is typical for an emulator, there's a potential risk if these files are user-modifiable and not properly validated before use. Fix: Ensure that game settings files are properly validated before being parsed and applied. Implement input validation for all configuration options to prevent injection attacks or unexpected behavior from malicious game settings files.
• Low · Missing HTTPS Enforcement Documentation — README snippet and external links. The README references multiple external links (forums, wiki, etc.) but there's no visible enforcement of HTTPS-only connections in the provided configuration. Fix: Ensure all external links in documentation use HTTPS. Configure any web components to enforce HTTPS-only connections. Use HSTS headers if applicable.
• Low · Android Support Without Explicit Security Guidance — AndroidSetup.md. The project supports Android builds (reference to AndroidSetup.md), but no explicit Android security considerations or guidelines are visible in the provided file structure. Fix: Document security considerations for Android builds, including proper handling of permissions, secure storage of configuration data, and protection against runtime modification attacks. Consider implementing runtime integrity checks.

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.