Getting Started with TruchiEmu

Everything you need to start playing retro games on macOS

Download TruchiEmu

Get the latest release for macOS — no building required.

Download Latest Release

Fetching latest version...

Choose Your Path

🎮

I Want to Play Games

Download, set up your library, and start playing in minutes — no coding required.

 🔧

I Want to Build or Contribute

Clone the repo, build from source, and start developing or contributing to TruchiEmu.

Quick Start: Play Games

  1. Download & Launch TruchiEmu

    Grab the latest release from the link above, move it to your Applications folder, and launch it. The setup wizard will appear on first launch.

  2. Add Your ROM Folders

    When the wizard appears, click the folder button to select the directory containing your ROMs. You can add multiple folders — TruchiEmu scans them recursively. You can also add folders later from the library toolbar (folder.badge.plus button) or with Shift+Cmd+O.

  3. Wait for the Scan

    TruchiEmu automatically identifies your games using CRC32 hashing and DAT databases, downloads box art, and enriches metadata. A progress indicator shows scanning status.

  4. Double-Click to Play

    Any game in your library can be launched with a double-click. The first time you play a game from a given system, TruchiEmu will present a core picker sheet where you can download the required emulator core — after that, it launches instantly.

Tip: TruchiEmu uses the libretro API, so it supports virtually any system that has a libretro core available — from 8-bit classics to 3D consoles and arcade machines. See the Supported Systems page for details.

Setup Wizard

On first launch, TruchiEmu walks you through a 4-step setup wizard:

Step 1 — Language & ROM Folders

Choose your UI language (English, Spanish, or Portuguese) and add one or more ROM folders. Folders are scanned recursively. You can skip this and add folders later.

Step 2 — Look & Feel

Optionally download bezels (decorative screen overlays) and pick a default shader preset. Shaders add CRT scanlines, LCD effects, composite blur, or clean scaling — you can change this anytime.

Step 3 — Optional Features

Toggle cheat file downloads (from the libretro database) and optionally enable RetroAchievements. Note: RetroAchievements login is configured in Settings after the wizard — the wizard only toggles the feature on.

Step 4 — You’re All Set

If you added ROM folders, you’ll see a scanning progress indicator. Once complete, click “Enter Library” to start playing. Background downloads for bezels and cheats will continue automatically.

Adding & Managing Games

Importing Games

TruchiEmu uses folder-based scanning — add a directory and the app finds all compatible ROMs inside it. There are several ways to add folders:

  • Setup Wizard: Add folders during first-launch setup
  • Library Toolbar: Click the folder.badge.plus button at the top of your library
  • Menu Bar: Games → Add ROM Folder (Shift+Cmd+O)
  • Settings: Navigate to Settings → Library → Library Folders and click “Add Folder”
  • Empty Library: A prominent “Add ROM Folder” button appears when your library is empty

How Scanning Works

When you add a folder, TruchiEmu scans it recursively and identifies games using CRC32 hashing against DAT databases — not just file extensions. This means your ROMs are accurately identified regardless of filename. After identification, the app automatically:

  • Downloads box art from the Libretro CDN (with optional LaunchBox and ScreenScraper sources)
  • Enriches metadata (genre, player count, publisher)
  • Filters out BIOS files and system assets so only playable games appear

Rescanning & Maintenance

If you add new ROMs to an existing folder, rescan to pick them up:

  • Full Rescan: Settings → Library → Maintenance → “Full Library Rescan”, or use Shift+Cmd+R
  • Per-Folder Refresh: In Settings → Library, each folder has a “Refresh” button
  • Per-System Refresh: Right-click a system in the sidebar and choose “Refresh”
  • Rebuild: For deeper cleanup, each folder has a “Rebuild” option with multiple rebuild strategies

File Format Handling

Compressed ROMs

For arcade systems like MAME, .zip is the primary expected format and is handled natively by the library.

Disc Images

When a .cue file is detected, TruchiEmu prioritizes it and automatically hides the associated .bin files from the library to prevent duplicate entries.

Library Filtering

The application automatically filters out system BIOS files and metadata assets, displaying only playable game entries in the library view.

Legal Notice: TruchiEmu does not provide ROMs. Please use legally obtained backups of games you own.

Library Organization

TruchiEmu offers several ways to browse and organize your game collection:

Sidebar Navigation

  • All Games: Your entire library at a glance
  • Favorites: Games you’ve favorited (right-click → “Add to Favorites”)
  • Recent: Games you’ve played recently
  • Retro Achievements: Games with matched achievements (shown when RA is enabled)
  • Per-System: Browse by console (NES, SNES, GBA, Genesis, etc.)
  • Categories: Custom groups you create with custom names, icons, and colors
  • Hidden Games: Games you’ve hidden from the main view (right-click → “Hide Game”)
  • Hidden MAME Files: Filtered MAME non-game entries (shown when applicable)

View Modes

Toggle between Grid and List view using the segmented control in the library toolbar. In grid mode, a zoom slider adjusts card size and column count.

Search & Filters

  • Search: Type in the search field (or press Cmd+F) — supports multi-term search (all terms must match)
  • Filter Chips: “No Box Art”, “Never Played”, “Unidentified”, “Multiplayer”, “Genre”
  • Sort Chips: “Last Played” and “Last Added” toggle chips (in the same chip bar as filters; default sort is alphabetical)

Categories

Create custom categories from the sidebar — give them a name, icon (from SF Symbols), and color. Add games to categories via drag-and-drop or the right-click context menu.

Controls & Input

Gameplay Keyboard Defaults

Default mappings vary by system. The table below shows the default/fallback layout:

Key Action Notes
Arrow Keys D-Pad / Directional Input Standard for all systems
Z, X, C, V Action Buttons (A, B, X, Y) Default layout; NES uses C/V for Turbo, Arcade uses A/S/D/F
Enter Start Menu navigation
Tab Select Secondary menu button

In-Game Hotkeys

Key Action Details
F5 Quick Save Saves to the current slot
F7 Quick Load Loads from the current slot
F6 Next Slot Cycles slot forward (wraps 9 → 0)
F4 Previous Slot Cycles slot backward (wraps 0 → 9)
Cmd+Z Undo Load State Restores the state from before the last load
F8 Training Mode Reset Instant reset (requires Training Mode enabled)
F9 Toggle Tape Recording Record input sequences for training (requires Training Mode enabled)
F10 Play Tape Back Playback recorded sequences (requires Training Mode enabled)
Cmd+F10 Toggle Input Capture Captures keyboard/mouse for DOS/ScummVM games

Controller Support

TruchiEmu automatically detects controllers when connected via USB or Bluetooth and assigns them to the next available player slot (up to 4 players). A notification pill appears on connect.

  • Xbox Controllers: Xbox One and Series X|S
  • PlayStation Controllers: DualShock 4 and DualSense (PS5)
  • MFi Controllers: Apple-certified gamepads
  • Generic HID: Most USB/Bluetooth gamepads work out of the box

Controller Tip: TruchiEmu uses per-system default mappings that match the original hardware layout. NES gets a 2-button layout, SNES gets 4-button, N64 maps C-buttons to the right stick, and Arcade maps coin/start buttons. All defaults can be customized in Settings → Controllers.

Customizing Controls

Open Settings → Controllers to remap any button. The controller settings include:

  • System Picker: Configure mappings per system or set a “Global Default”
  • Player Slots: Assign controllers to P1–P4
  • Gamepad Remapping: Click a button name, then press a physical button on your controller to assign it
  • Keyboard Remapping: Click a button name, then press a key to reassign
  • Gamepad Profiles: Save and load named mapping configurations (gamepad only)

DOS & ScummVM: For these systems, all keyboard input is passed directly to the core as raw key events — enabling full keyboard interaction (typing in DOS, ScummVM point-and-click). Press Cmd+F10 to capture the mouse for these games.

Save States

TruchiEmu provides flexible save state management with 11 slots, progressive versioning, and auto-save/load options.

Slots

There are 11 save slots: one Auto slot (slot -1) plus slots 0 through 9. Each slot can store up to 5 progressive versions (default: 3), giving you multiple snapshots per slot.

Saving & Loading

During Gameplay

  • Keyboard: F5 to save, F7 to load, F6/F4 to cycle slots, Cmd+Z to undo a load
  • Overlay Toolbar: Save and Load buttons at the bottom of the game window, plus a slot selector to pick from all 11 slots
  • Slot Picker Sheet: Full grid view with Save/Load/Delete per slot (Load only for the Auto slot), thumbnails, timestamps, and file sizes

Before Launching

  • Game Detail View: The “Saved States” section shows all slots as a visual grid. Double-click any slot thumbnail to launch the game directly into that save state.
  • CLI: Use --slot <number> to launch into a specific save state from the command line

Auto-Save & Auto-Load

Setting Default Behavior
Auto-Save on Exit Off Saves to the Auto slot when you close the game window
Auto-Load on Start Configurable Loads the most recent save state across all slots when launching a game

Both settings can be toggled in Settings → Saves.

Save States vs. Battery Saves

Save States

  • Instant snapshot of emulator memory
  • 11 visual slots with thumbnail previews
  • Progressive versioning (up to 5 per slot)
  • Undo load with Cmd+Z
  • Optional LZ4 compression

Battery Saves

  • Works like original hardware
  • Compatible with real cartridge save data
  • Handled automatically by the game core
  • Stored in ~/Library/Application Support/TruchiEmu/saves/savefiles/
  • No user intervention needed

Restrictions: Save states are disabled for Dolphin cores (known crash issue). When RetroAchievements Hardcore Mode is active, save states, rewind, slow motion, and cheats are all blocked.

Personalizing TruchiEmu

Themes & Appearance

TruchiEmu ships with 17 accent color themes — including gaming-inspired themes — plus the ability to pick any custom color. Configure these in Settings → General:

  • Appearance Mode: Light, Dark, or Automatic (follows system)
  • Theme Grid: 7 standard themes (Samus, Chocobo, Protoss, Joker, Geralt, Mega Man, Custom) and 10 gaming themes (Mario, Luigi, Sonic, Half-Life, Kratos, Kirby, Zelda, Pikachu, Doom, Master Chief)
  • Custom Color: Pick any color with the system color picker when “Custom” is selected
  • Toolbar Accent: Toggle accent-colored toolbar icons
  • Tinted Surfaces: Toggle accent tint on window/sidebar/toolbar backgrounds

Note: Theme and appearance changes require an app restart to fully take effect. A preview card shows you what the theme will look like before you apply. When you press “Apply Theme”, a confirmation dialog offers “Restart Now” or “Later”.

Shaders

TruchiEmu includes 14 built-in Metal shaders across 5 categories, plus custom preset support:

  • CRT Simulation: CRT Lottes, CRT Classic, Lite CRT, CRT Multipass — authentic scanlines, phosphor glow, and curvature
  • Handheld LCD: 8b Game Boy, 8b Game Boy Color, GBA Advanced LCD, PSP Advanced LCD, NDS Advanced LCD, 3DS Advanced LCD, Dot Matrix LCD
  • Smoothing: Sharp Bilinear, Smooth Upscale (ScaleFX) — edge-directed upscaling
  • Composite: Composite/VHS blur for authentic analog signal effects
  • Custom Presets: Create and save your own .truchishader presets; also includes a “No Shader” passthrough option

Shaders can be changed in real-time during gameplay — no restart needed. See the Shader Guide for full details.

Bezels

Bezels are decorative overlays that frame the game screen with system-specific artwork. TruchiEmu can automatically download and match bezels for your games. Configure bezels in the shader/bezel settings, or opt in during the setup wizard. See the Bezel Guide for details.

Building from Source

If you want to contribute to TruchiEmu or build it yourself, follow these steps.

Prerequisites

macOS 14.0+ (Sonoma) with Swift 5.9+ and a Metal-compatible GPU

1. Install Build Tools

brew install xcodegen

Also ensure Xcode and Command Line Tools are installed: xcode-select --install

2. Clone and Generate Project

git clone https://github.com/JuanchoGithub/truchiemu.git
cd truchiemu
xcodegen generate

3. Build the Application

# CLI Method:
xcodebuild -project TruchiEmu.xcodeproj -scheme TruchiEmu -configuration Debug build

Alternatively: Run open TruchiEmu.xcodeproj and press Cmd+B.

Note: If you modify project.yml, you must run xcodegen generate again to update the Xcode project. However, new source files under TruchiEmu/ are auto-included via recursive paths — no project.yml edit needed for those.

For more details on the build pipeline, project architecture, and contribution guidelines, see the Developer Guide and Building Guide.

Next Steps

Shaders

Configure CRT, LCD, and scaling filters for authentic visuals.

Shader Guide

Achievements

Link your RetroAchievements account and earn trophies.

Achievements

Controllers

Customize per-system mappings and controller profiles.

Controller Guide

Themes

Pick a gaming-inspired accent color or create your own.

Themes

Cheats

Download and apply cheat codes from the libretro database.

Cheats

Contribute

Help improve TruchiEmu by contributing to the source.

Contributing