๐ An Open-Source Nintendo Switch Emulator Written in C
Switch 2 support is a research target, not a shipping capability: this build has no console keys, no content decryption, and no Switch 2 execution layer.
High-fidelity system emulation. Highly experimental, but steadily growing.
Compound is an ambitious, production-focused Nintendo Switch emulator project written in clean C with a relentless focus on correctness, performance, and portability. Unlike many emulation projects, Compound emphasizes:
- ๐งฌ Defensive architecture with checked arithmetic and runtime validation
- ๐๏ธ Architecture-first design with clear separation of concerns
- ๐ High-performance JIT compilation via the Ballistic ARM64 recompiler
- ๐ Cross-platform excellence โ Linux, macOS, Windows, Android, and ARM64
- ๐ Professional-grade debugging with GUI, live reload, and comprehensive logging
- ๐ฏ Staged development approach โ foundations first, then execution, then compatibility
Perfect for:
- ๐ฎ Gaming enthusiasts and emulation developers
- ๐ฌ Systems programming researchers and students
- ๐ ๏ธ Hardware debugging and reverse engineering
| Feature | Status | Details |
|---|---|---|
| ๐งฑ Build & CI Infrastructure | โ Complete | Presets, CMake 3.25+, cross-platform CI |
| ๐ญ Runtime & Memory System | โ Complete | mimalloc allocator, checked arithmetic, pool/slab/arena allocators, host accounting |
| ๐ Debug Tooling | โ Working | GUI with live reload, comprehensive logging |
| โก Ballistic ARM64 JIT | โ Complete | Recompiler integration and code cache |
| ๐พ Filesystem & Crypto | โ Complete | HFS0 parser, 64-bit file reader, SHA-256, RSA-2048 PKCS#1 v1.5 verification |
| ๐ฅ๏ธ Guest CPU & OS | โ Complete | A64 interpreter subset; kernel objects, one-sided event handles and services |
| ๐จ Graphics & Audio | โ Complete | SM86โSPIR-V translation, Vulkan scaffolding, SDL audio output and gamepad input |
| ๐ฎ Title Support | โ Complete | Content-based NRO/NSO parsing and boot mapping; encrypted packages are recognised and refused |
| ๐ฎ Switch 2 | โ Not implemented | No keys, decryption, or execution layer; compatibility is always reported false |
Compound is in early-stage, active development. The emulator has:
โ
A solid foundation with working unit tests and presets
โ
Defensive systems for memory safety and correctness
โ
Professional debugging tools with GUI and instrumentation
๐ง Experimental work in JIT, guest CPU and OS, and graphics translation
๐ฎ Planned: Guest execution, compatibility, graphics, and full Switch support
โ Build system (CMake, Ninja, Clang)
โ CI/CD (Linux, macOS, Windows, Android, ARM64)
โ Unit testing and validation
โ Memory accounting and profiling
โ Pool, slab, and rewindable arena allocators
โ Debug GUI with real-time diagnostics
โ Logging framework
โ Guest CPU baseline (A64 interpreter subset, Horizon OS kernel objects, SVC dispatch, guest-created events, thread scheduler, memory layout)
โ Title detection and validation (NRO/NSO images; NCA/NSP/XCI recognised and explicitly refused)
โ RSA-2048 PKCS#1 v1.5 signature verification (caller-supplied keys only)
โ Boot mapping for NRO/NSO images (segments, permissions, stack, initial PC/SP)
โ Input, audio ring, SDL audio output, gamepad and keyboard mapping, platform services
โ Commercial title boot (needs user-supplied keys, decryption, and a filesystem stack)
โ Switch 2 execution (no keys, no decryption, no execution layer)
-
mimallochost allocator integration - Build and CI infrastructure
- Unit tests and debug instrumentation
- Advanced memory ownership and allocation strategies (pool, slab, rewindable arena)
- Hardened validation paths (checked arithmetic, ranges, alignment, overlap predicates)
- HFS0 filesystem parser
- Filesystem reader abstraction
- SHA256 and crypto primitives
- Verification and signature handling (RSA-2048 PKCS#1 v1.5, verification only)
- Ballistic ARM64 code cache allocator
- JIT metadata manager
- Error logging and diagnostics
- Execution loop integration
- ARM64 CPU instruction dispatch (interpreter subset)
- Horizon OS kernel abstraction (objects, handles and services)
- System call handling (SVC dispatch for handles, events, yields and the tick)
- Thread scheduling and blocking waits
- Synchronization cancellation (
svcCancelSynchronization) - Guest-created events with one-sided readable and writable handles (
svcCreateEvent) - Core OS services and memory layout
- SM86 โ SPIR-V translation
- Vulkan render backend (stub implementation, ready for integration)
- Input, audio, and platform services (SDL gamepad/keyboard, S16 audio ring and output, lifecycle/timing)
- Bootable guest state for validated NRO/NSO images (commercial packages and Switch 2 titles are refused)
compound/
โโโ ๐ src/
โ โโโ emulator core and runtime
โ โโโ GUI and debug tools
โ โโโ bootstrap and initialization
โโโ ๐ cmake/
โ โโโ build modules and toolchains
โ โโโ platform-specific configuration
โโโ ๐ tests/
โ โโโ unit test suite
โ โโโ validation harness
โโโ ๐ android/
โ โโโ Android packaging
โ โโโ JNI integration
โโโ ๐ extern/
โ โโโ vendored dependencies
โ โโโ third-party libraries
โโโ ๐ docs/
โ โโโ architecture and design
โ โโโ build and CI documentation
โ โโโ programming rules
โ โโโ graphics (SM86โSPIR-V) rules
โโโ ๐ LICENSE, README, etc.
- CMake 3.25 or later
- Ninja build system
- Clang compiler (GCC/MSVC with adjustments)
- C++17 or later support
# Configure and build
cmake --preset debug
cmake --build --preset debug --parallel
# Run tests
ctest --preset debug
# Verbose output (optional)
cmake --build --preset debug --verbose| Preset | Platform | Architecture | Features |
|---|---|---|---|
debug |
Linux / macOS | x86-64 | ASan + UBSan enabled |
release |
Linux / macOS | x86-64 | Optimized build |
debug-windows |
Windows | x86-64 | clang-cl compiler |
release-windows |
Windows | x86-64 | Optimized (clang-cl) |
linux-aarch64-debug |
Linux | ARM64 | Cross-compile, QEMU tested |
linux-aarch64-release |
Linux | ARM64 | Cross-compile, optimized |
android-arm64-debug |
Android | ARM64 | Produces libmain.so |
android-arm64-release |
Android | ARM64 | Optimized Android library |
For detailed setup, prerequisites, and Android packaging, see docs/BUILDING.md.
Comprehensive documentation is available in the /docs folder:
| Document | Purpose |
|---|---|
| ARCHITECTURE.md | System design, module breakdown, and design patterns |
| BUILDING.md | Build setup, platform-specific instructions, Android packaging |
| CI.md | CI/CD workflows, automation, and testing strategies |
| PROGRAMMING_RULES.md | Code style, safety, and best practices |
| SM86_TO_SPIRV_RULES.md | Graphics shader translation rules and patterns |
Before contributing, please read:
- CONTRIBUTING.md โ Contribution guidelines
- PROGRAMMING_RULES.md โ Code standards
- ARCHITECTURE.md โ System design overview
# 1. Fork the repository
# 2. Create a feature branch
git checkout -b feature/your-amazing-feature
# 3. Commit with clear messages
git commit -m "Add: [feature description]"
# 4. Push and open a PR
git push origin feature/your-amazing-featureGood contribution areas:
- ๐ Bug fixes in core systems
- ๐ Documentation and examples
- โ Unit tests and validation
- ๐ Performance optimizations
- ๐ Platform support and portability
| Branch | Purpose | Status |
|---|---|---|
main |
Stable baseline, release-ready | Production |
general-upgrade-dev-v1 |
Primary development track | Active |
general-upgrade-experimental-* |
Feature-specific experimental work | In Progress |
origin/enhancement/project-upgrade-core-cmake |
Build system improvements | Active |
The repository uses a staged experimental approach: features are tested in dedicated experimental branches, then selectively merged into the main development stream.
โจ Correctness First
Runtime validation, checked arithmetic, and defensive coding patterns ensure system stability.
โก Performance-Conscious
Ballistic ARM64 JIT provides high-speed guest code execution without sacrificing clarity.
๐งฑ Clean Architecture
Clear separation of concerns with well-defined module boundaries and interfaces.
๐ Cross-Platform
Native support for Linux, macOS, Windows, Android, and ARM64 architectures.
- Memory System:
mimallocallocator with host accounting; pool, slab, and rewindable arena strategies; shared checked-arithmetic validation - JIT Engine: Ballistic ARM64 recompiler for high-performance execution
- Guest OS: Horizon OS kernel objects, per-process handles with one-sided event rights, named services, SVC dispatch including
svcCreateEvent,svcMapMemory,svcUnmapMemory, a priority round-robin thread scheduler with blocking waits andsvcCancelSynchronization, and a partitioned address space whose region table gates guest access, answerssvcQueryMemory, and reprotects an existing region withsvcSetMemoryPermission/svcSetMemoryAttribute - Graphics: SM86โSPIR-V translation with Vulkan render backend scaffolding
- Title Loading: Content-based NRO/NSO detection, layout validation, and boot mapping; NCA/NSP/XCI are recognised and refused because this build has no keys or decryption
- Crypto: SHA-256 and RSA-2048 PKCS#1 v1.5 verification over caller-supplied public keys
- Platform: SDL audio output, gamepad/keyboard mapping, and host lifecycle/timing services, with an SDL-free core input/audio layer
- Debug Tools: GUI with live reload, comprehensive logging, and profiling
- Validation: Extensive unit tests and runtime checks
- Filesystem: Experimental HFS0 parser and file-backed reader abstraction
Compound is licensed under the GNU General Public License v3.0. See LICENSE for full details.
Copyright (C) 2024 - Emulator Contributors
Licensed under GPLv3 โ You are free to use, modify, and distribute
under the terms of the GPL v3.
- ๐งฑ Foundation strengthening: Shared validation helpers, an arena allocator with ownership tags and checkpoints, and a 64-bit file reader
- โก JIT experimentation: Ballistic ARM64 integration progress
- ๐ฅ๏ธ Guest CPU and OS: A64 interpreter subset, a Horizon OS handle/service kernel with one-sided readable and writable event handles, SVC dispatch including
svcCreateEvent,svcMapMemory,svcUnmapMemory, a thread scheduler with blocking waits, synchronization cancellation withsvcCancelSynchronization, and a memory-layout slice that partitions the guest address space, answerssvcSetHeapSize/svcQueryMemory, and reprotects regions withsvcSetMemoryPermission/svcSetMemoryAttribute - ๐ Filesystem work: HFS0 parser and a file-backed reader with 64-bit offsets
- ๐ Crypto: SHA-256 plus RSA-2048 PKCS#1 v1.5 signature verification over caller-supplied keys; no Nintendo keys are shipped
- ๐จ Graphics: SM86โSPIR-V translation with Vulkan render backend scaffolding
- ๐ฎ Title loading: Content-based NRO/NSO detection, validated segment layouts, and boot mapping; encrypted NCA/NSP/XCI packages are refused by name rather than approximated
- ๐ Platform services: Thread-safe S16 audio ring, SDL audio output, gamepad/keyboard input mapping, and lifecycle/timing capability reporting
- ๐ Testing: 32 registered CTest suites, including validation, arena, RSA, file reader, loader, input, audio, and platform services
- Integration of Vulkan render backend with main render loop
- Key handling, package decryption, and a filesystem stack for commercial titles
- IPC/CMIF shared memory and the remaining
svcMapMemory/svcUnmapMemoryalias path
Have questions or ideas?
๐ Open an issue or start a discussion
Want to help?
๐ Check the roadmap and pick a task!
Made with โค๏ธ by the Emulation Community
GitHub โข Issues โข Discussions