Getting Started with TruchiEmu

A technical guide to building, configuring, and running TruchiEmu on macOS

System Requirements

🖥️ macOS Compatibility

Minimum: macOS 14.0 (Sonoma) or later with Swift 5.9+

Recommended: macOS 15.0 (Sequoia) or later for optimal performance

Build Dependencies

  • Xcode: Latest stable version (Required for building)
  • Xcode Command Line Tools: xcode-select --install
  • xcodegen: Used to generate the Xcode project from project.yml
  • Metal-compatible GPU: For shader rendering and hardware acceleration

⚠️ Important: TruchiEmu uses modern SwiftUI features and Metal shaders that are not compatible with macOS versions older than 14.0.

Building from Source

TruchiEmu is built using XcodeGen to maintain a clean project structure. Follow these steps to build the application locally.

1. Install Build Tools

brew install xcodegen

2. Clone and Generate Project

git clone https://github.com/JuanchoGithub/truchiemu.git
cd truchiemu
xcodegen generate  # This creates the TruchiEmu.xcodeproj file

3. Build the Application

You can build via the command line or by opening the project in Xcode.

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

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

💡 Note: If you modify project.yml, you must run xcodegen generate again to update the Xcode project.

First Launch & Configuration

When you launch TruchiEmu for the first time, you will be guided through an initial setup process to configure your environment.

Environment Setup

Library & Data Location

TruchiEmu separates your game library from its internal application data. While you can choose any folder for your ROMs, the application stores its configuration, save states, and system files in the standard macOS Application Support directory: ~/Library/Application Support/TruchiEmu/.

Within the Application Support folder, TruchiEmu automatically organizes technical data into:

  • Saves/ - Your save states and battery save files
  • Cores/ - The libretro cores used for emulation
  • Thumbnails/ - Game artwork and cached screenshots
  • System/ - Required BIOS and system files

Controller Configuration

Map your inputs to the emulator. TruchiEmu supports Keyboard, Xbox, PlayStation, and Nintendo Switch controllers natively on macOS.

Adding Your First Game

TruchiEmu supports simple import methods to get your library ready.

Importing Games

TruchiEmu supports simple import methods to get your library ready.

  1. Drag and Drop: Drag ROM files or folders from Finder directly into the TruchiEmu library window.
  2. Manual Import: Use the import button in the library toolbar to browse for files.

File Handling & Compatibility

TruchiEmu leverages the libretro API, meaning it supports virtually any file format accepted by the active emulator core. Rather than relying on simple file extensions, the app uses CRC32 hashing and DAT databases to identify games accurately.

📦 Compressed ROMs

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

💿 Disc Images

Intelligent handling of 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

To keep your collection clean, 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.

Basic Controls

Keyboard Defaults

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 for most systems
Enter Start / Pause Menu navigation
Tab Select / Back Secondary menu button
Escape System Menu Access app-level settings

Controller Support

TruchiEmu automatically detects most popular controllers when connected via USB or Bluetooth through the native macOS GameController framework:

  • Xbox Controllers: Native support for Xbox One and Series X|S
  • PlayStation Controllers: DualShock 4 and DualSense (PS5) supported
  • Nintendo Switch: Joy-Cons and Pro Controller supported
  • Generic USB: Most MFi and XInput controllers work out of the box

💡 Controller Tip: TruchiEmu uses a global mapping template based on the modern Xbox/PlayStation layout. This ensures a consistent feel across different systems, but can be customized per-system in the settings.

Per-System Customization

Each emulator core can have its own control mapping to better suit the original hardware:

  1. Open a game for the system you want to configure
  2. Navigate to the Controller settings in the main menu
  3. Adjust button mappings to match your preference
  4. Mappings are saved per system and applied automatically next time you launch a game from that system

Save States

TruchiEmu provides robust save state management alongside traditional battery saves.

Save States

  • Instant snapshot of emulator memory
  • Visual slot-based management (Slots 0-9 + Auto)
  • Managed via the Game Detail view with thumbnail previews

Battery Saves

  • Works like original hardware
  • Compatible with real cartridges
  • Handled automatically by the game core

Next Steps

🎨 Explore Shaders

Try CRT and smoothing filters in the Shader menu.

Shader Guide

🏆 Achievements

Link your RetroAchievements account in Settings.

Achievements

🔧 Contribute

Help improve the emulator by contributing to the source.

Developer Guide