Skip to main content
oboromi is an experimental Nintendo Switch 2 emulator foundation. It currently cannot run commercial games or firmware and focuses on CPU instruction emulation and testing.

​
Prerequisites

Before you begin, ensure you have the following installed:

Rust Toolchain

Latest stable version required

CMake

Version 3.16 or higher

Ninja

Build system for compilation

C++ Compiler

MSVC (Windows) or Clang (macOS/Linux)

​
Installation

1

Clone the repository

git clone https://github.com/0xNikilite/oboromi
cd oboromi
2

Build and run

The emulator uses a Cargo workspace with two main components: core (emulator library) and gui (frontend).
cargo run
This will:
  • Download and compile all Rust dependencies
  • Build the oboromi-core library (CPU, GPU, filesystem, and system services)
  • Build the oboromi-gui frontend using eframe/egui
  • Launch the GUI application
3

Verify the build

When the GUI launches, you should see:
  • A splash screen with the oboromi logo
  • An experimental warning message
  • The main window (1200×800) with a “Run CPU Tests” button

​
What’s Included

oboromi is structured as a Cargo workspace with the following components:
The core emulation library located in core/:
  • CPU: 8-core ARMv8 CPU emulation using Unicorn Engine
  • GPU: SM86 (NVIDIA Ampere) stub GPU with Vulkan backend
  • Memory: 12GB shared memory emulation
  • Filesystem: VFS implementation for 32GB UFS/eMMC
  • System Services: HLE (High-Level Emulation) of 150+ Nintendo Switch 2 firmware services
The GUI frontend located in gui/:
  • Built with eframe/egui for cross-platform support
  • CPU test runner interface
  • Real-time test result display
  • Logging system with file output to oboromi.log
Additional tools in scripts/:
  • decoder_generator.rs: Generates GPU instruction parser code
  • sm_86_instructions.txt: SM86 instruction dump from DocumentSASS
  • sm_86_latencies.txt: Instruction timing information
  • docs/sm86.pdf: Auto-generated instruction set documentation

​
First Steps

Once the GUI is running:
  1. Run CPU Tests: Click the “Run CPU Tests” button to verify the ARM64 emulation is working correctly
  2. View Logs: Test results appear in the scrollable results panel with color-coded output:
    • Green for passing tests
    • Red for failing tests
  3. Check Log File: Detailed logs are written to oboromi.log in the project directory

​
Enable Tracing

For detailed execution tracing, build with the trace feature: 
cargo run --features trace
This enables verbose logging of CPU instructions and system calls through both oboromi-core and oboromi-gui.

​
Troubleshooting

Install CMake 3.16 or higher:Ubuntu/Debian:
sudo apt install cmake ninja-build
macOS:
brew install cmake ninja
Windows: Download from cmake.org or use choco install cmake ninja
oboromi requires a modern C++ compiler for the Unicorn Engine dependency.Linux:
sudo apt install clang
Windows: Install Visual Studio 2019 or later with C++ development tools
Ensure you have the required graphics drivers:
  • Linux: Install Vulkan drivers and libvulkan1
  • Windows: Update your GPU drivers
  • macOS: MoltenVK should be installed automatically

​
Next Steps

Detailed Building

Learn about the build system and dependencies

Running the Emulator

Explore all runtime options and features

Contributing

Help improve oboromi development

Architecture

Understand the emulator’s design

​
Community

Join the oboromi community:

Build docs developers (and LLMs) love

Get started for freeTalk to us