TruchiEmu Features

TV Mode

TV Mode is TruchiEmu's couch-friendly, full-screen library experience. Flip to TV Mode from the View → TV Mode menu (or a button on the game-toolbar) to browse your entire collection without a mouse.

What You Get

• Gamepad Navigation: D-pad / analog stick scrolls through games, A selects, B backs out, R3/L3 toggles the sidebar — full traversal without ever touching the keyboard or mouse
• Animated Backgrounds: Backdrops derived from each game's box art and system artwork, with auto-repeat navigation and dynamic delay scheduling
• Box-Art Focus: Focused entries scale up with cleaner visuals and pin the background fill to the image size to prevent halo clipping
• Short-List Mode: Compact title-only stack for very large libraries, with smooth item duplication
• Filter & Sort: TV Mode maintains your filter and ROM selections on state restoration; reset filters at any time
• Resolution-Adaptive Scaling: Auto-scales the UI relative to your screen resolution for a consistent feel on 1080p, 1440p, and 4K displays
• Core Download Overlay: Trigger core downloads directly from TV Mode — no need to drop back to the desktop
• Auto-Fullscreen: Optionally restore the previous fullscreen state when you exit TV Mode

Learn more about TV Mode →

Shader Collection

Transform your gaming experience with our curated collection of high-quality Metal shaders. Each shader is optimized for macOS and designed to enhance or authentically reproduce classic gaming visuals.

Built-in Metal Shaders

TruchiEmu ships with 14 built-in Metal shaders that work out of the box — no downloads, no setup:

Slang Shader Presets

Beyond the built-in Metal shaders, TruchiEmu also runs RetroArch .slangp presets via librashader. Hundreds of community-made presets from the libretro slang-shaders project are bundled and discovered automatically. Browse them in the All and Slang tabs of the shader picker. Drop new .slangp files into ~/Library/Application Support/TruchiEmu/SlangPresets/ and they appear automatically.

Shader Customization

Each shader includes adjustable parameters to fine-tune the effect:

• Intensity Sliders: Adjust the strength of each effect
• Parameter Presets: Quick settings for different display types
• Real-time Preview: See changes instantly as you adjust
• Per-Game Settings: Save shader preferences for individual games
• Global Defaults: Set system-wide shader preferences

Learn more about the Shader System →

Library Management

Organize your game collection with powerful library management features designed for serious collectors and casual gamers alike.

Automatic Organization

• Smart Detection: Automatically identifies games from ROM file hashes (CRC32 hardware-accelerated via zlib, with DAT databases and a rejection-tracking scorer for MAME)
• Metadata Fetching: LaunchBox Metadata Service downloads game descriptions, release dates, publisher, genre with platform overrides and match scoring
• Cover Art Sources: ScreenScraper and Libretro CDN with configurable priority; interactive Box Art Picker lets you swap alt artwork per game; PPSSPP asset downloads are auto-applied
• System Categorization: Groups games by original console/system
• Achievement Detection: Identifies games with RetroAchievements support and shows the RA hash in the Game Detail view
• iCloud Materialization: iCloud dataless-placeholders are materialized on access so ROMs stored in iCloud appear correctly when they would otherwise be displayed as zero-byte stubs
• Removal Notifications: When ROMs are removed from a watched folder, TruchiEmu posts a notification and updates the library automatically

Collections & Categories

Organize your games with custom categories and built-in filters:

• Custom Categories: Create named categories with SF Symbol icons, custom uploaded icons, and per-category colors
• Favorites: Quick access to your must-play titles via the favorites filter
• Recently Played: Automatically tracks and displays your most recent sessions

RetroAchievements Integration

Earn achievements while playing classic games! TruchiEmu integrates seamlessly with RetroAchievements.org to add modern achievement hunting to retro gaming.

Learn more about RetroAchievements →

Emulation Cores

TruchiEmu is powered by libretro, a universal emulation API. Each system runs on a dedicated core — think of them as plug-in engines. Cores are automatically downloaded, updated, and configured through the integrated Core Downloader.

For a complete reference on which cores power each system, performance tuning, and the technical architecture, see the Developer Guide.

Save State Features

Save states allow you to capture and restore your exact position in a game instantly, providing a modern safety net for retro gaming.

Save State Manager

The integrated save state browser provides a visual way to manage your progress:

• Thumbnail Grid: Browse your saved positions visually via 320x240 previews
• Slot Management: Easy access to slots 0 through 9
• Metadata: View exactly when each state was created
• Automated Paths: Consistent folder structure for easy backup and migration

Learn more about Save States →

Themes & Appearance

Make TruchiEmu yours with 16 curated accent color themes plus custom colors — inspired by gaming legends from Samus to Doom — plus light/dark appearance modes and tinted surfaces.

What You Can Customize

• 16 Curated + 1 Custom: Accent palettes organized into Standard (Samus, Chocobo, Protoss, Joker, Geralt, Mega Man, Custom) and Gaming (Mario, Luigi, Sonic, Half-Life, Kratos, Kirby, Zelda, Pikachu, Doom, Master Chief) categories
• Appearance Mode: Light, Dark, or Automatic — follow your system preference or override it per-app
• Custom Colors: Pick any color as your accent with the built-in Color Picker
• Tinted Surfaces: Subtle accent color tinting on window, sidebar, and toolbar backgrounds
• Toolbar Accent: Optionally color toolbar icons with the accent color instead of system defaults
• Per-Mode Adaptations: Many themes automatically adjust their accent for better contrast in light vs. dark mode

Learn more about Themes & Appearance →

Bezels & Screen Framing

Enhance your immersion with custom bezels that frame your game screen, perfect for filling the void on modern wide-aspect displays.

• Automatic Mapping: Bezels are automatically matched based on the game name, following a resolution cascade (user override → exact match → cleaned name → fuzzy match → no bezel).
• Bezel Browser: Integrated downloader to find and apply community-created borders.
• Custom Import: Import your own bezel images for any game.

Learn more about bezels →

Controller Support

Plug in a gamepad and it just works. TruchiEmu supports both Apple's GCController framework and SDL2 for broad controller compatibility.

What You Get

• Plug and Play: USB and Bluetooth controllers are recognized the moment you connect them
• Dual Driver Support: Works with GCController-compatible gamepads (Xbox, PlayStation, MFi, Switch Pro) and SDL2-compatible controllers for broader hardware support
• Smart Defaults: TruchiEmu picks a sensible button layout based on the controller type and the system you're playing
• Per-Controller Profiles: Each controller you connect gets its own mapping, remembered for next time
• Per-System Overrides: A PlayStation pad can be SNES-style on one system and Genesis-style on another
• Multi-Player Keyboard Mapping: Refactored keyboard input supports multiple players from a single physical keyboard — combine a gamepad for P1 and keyboard for P2 (or vice-versa)
• Gap-Slot Prioritization: When a new controller connects, TruchiEmu prioritizes the first empty slot before substituting a keyboard player — your P2 stays P2
• SDL Disable & Reset: Disable a stuck SDL controller or reset the SDL controller list without quitting the app; keyboard controllers can also be disabled/reset independently
• Replace Keyboard with Controller: Toggle whether a freshly-connected controller should automatically take over a keyboard-assigned slot
• Deadzone & Sensitivity: Tune stick response so drift doesn't wander the character
• Remap Anything: Swap any button to any other button, including face, shoulder, and stick clicks
• Analog Mouse Mode: Use a stick to control the mouse in DOS and ScummVM games — see the Analog Mouse section for full details
• Keyboard Shortcuts: System hotkeys for save states, screenshots, and other common actions

Learn more about Controller Support →

Analog Mouse Support

TruchiEmu lets you use your gamepad's analog sticks to control the mouse cursor in DOS and ScummVM games, with configurable buttons for mouse clicks and D-pad for keyboard inputs.

Key Features

• Analog Stick to Mouse: The primary analog stick (left or right) controls the cursor at 60fps with configurable sensitivity
• Secondary Stick for Fine Control: The secondary analog stick moves the mouse at 1/5 speed for precise cursor placement
• D-Pad as Keyboard: D-pad sends arrow keys, Start sends Enter, Select sends Space
• Configurable Button Mapping: Assign left, right, and middle click to any gamepad button
• Per-System & Per-Game: Independent settings for DOS and ScummVM, with per-game overrides

Learn more about Analog Mouse Support →

Point & Click Guide

Stuck on a puzzle? The built-in Game Guide sidebar brings progressive hints and full walkthroughs directly into your game window. It automatically appears for adventure and point-and-click games, pulling content from the Universal Hint System (UHS) and GameFAQs.

Key Features

• Progressive Hints (UHS): Spoiler-free hints that reveal one at a time — get just enough help without ruining the puzzle
• Full Walkthroughs (GameFAQs): Complete text walkthroughs as a fallback when UHS hints aren't available
• Gamepad Navigation: Browse the guide with your controller — analog sticks scroll, A/B buttons navigate, R3/L3 toggles the sidebar
• 387+ Game Mappings: Pre-matched UHS guides for classic adventures including Monkey Island, Broken Sword, Grim Fandango, and more
• Automatic Detection: Adventure and point-and-click games are identified by genre or system (ScummVM games always qualify)

Learn more about the Game Guide →

Training Mode

TruchiEmu's training mode overlay provides P2 automation tools for fighting games, letting you control the dummy player to practice combos, defense, and setups.

Key Features

• Dummy Control: Configure P2 stance, guard behavior, wake-up tech, and reversal actions for realistic practice
• Sequence Programming: Build frame data sequences of moves for P2 to execute on configurable triggers
• Input Recording: Record P1 inputs via tape deck and play them back as P2 with multiple slots
• Input Display: Real-time visualization of P1 and P2 inputs with move notation tokens
• Move Integration: Browse character moves and link them to training sequences directly from the overlay

Learn more about Training Mode →

Move List & Fight Data

Never forget a special move again. The move list overlay displays fighting game move notations directly on screen, powered by an extensive library of curated fight data for over 200 fighting games.

Key Features

• On-Screen Display: Move notations are shown as an overlay during gameplay, categorized by type
• Visual Tokens: Move notations use visual tokens for directional inputs, button combinations, and special conditions
• Extensive Fight Data Library: Over 200 curated fight data sets covering classic and modern fighting games across NES, SNES, Genesis, Arcade, PlayStation, and more. Games include Street Fighter II, Mortal Kombat, King of Fighters, Tekken, Samurai Shodown, and dozens more.
• Per-Game Move Sets: Moves are automatically loaded based on the game being played
• Search & Filter: Quickly find specific moves by name, input type, or character

Learn more about Move List Overlay →

Time Machine

TruchiEmu's Time Machine brings rewind, fast-forward, and slow-motion controls directly to the game toolbar. The Setup Wizard offers an optional Time Machine step on first launch, and the controls stay available during gameplay for the ultimate sandbox.

Key Features

• Rewind: Step backward through recent frames to retry a missed jump, a botched combo, or a fatal hit without reaching for a save state
• Fast Forward: Skip slow dialogue, grinding, or long cutscenes while keeping audio pitched to playback speed
• Slow Motion: Study frame-perfect sequences at reduced speed — ideal for fighting game combo practice or tricky platformer setups
• Hardcore-Aware: When RetroAchievements Hardcore Mode is active, Time Machine controls are disabled alongside save states and cheats
• Per-Core Compatibility: The Time Machine uses save-state deltas; some cores (e.g. Dolphin) with known crash issues are gracefully excluded, and Play! (PS2) save-state warnings surface clearly

Learn more about Time Machine →

Stream Recording

Record your gameplay sessions or stream live to Twitch, YouTube, or a custom RTMP server — all without leaving the game. The entire encode/RTMP pipeline runs in-process via HaishinKit, so there are no external processes, FIFOs, or silent frame drops under backpressure.

Key Features

• Local Recording: Capture gameplay to local files in H.264, HEVC, or lossless ProRes 422/4444
• Live Streaming: Stream directly to Twitch or YouTube, or point to any custom RTMP endpoint with stream-key verification (Twitch/YouTube give immediate success/failure feedback)
• Resolutions: Native / 720p / 1080p / 1440p / 4K via the StreamResolution picker; ProRes encoders are demoted to H.264 for streaming
• VideoToolbox Encoding: Hardware-accelerated H.264/HEVC encode and AAC audio encode via macOS VideoToolbox for minimal performance impact
• Rolling Video Buffer: Tap a "save last moments" hotkey to write the past few seconds to disk — perfect for clip-worthy plays you didn't see coming
• Share Button: Single-press and long-press share actions, configurable per game
• Record With or Without Shaders: Choose whether the recording captures the post-shader drawable or the raw core frame
• In-Game Controls: Start/stop recording from the game toolbar without breaking your flow; visibility of the record button adapts to your current recording state and settings

Learn more about Stream Recording →

Netplay — Roadmap

Netplay (multiplayer over the network) is documented as an implementation plan and is not yet shipped. The complete design — infrastructure, matchmaking, and rollback netcode integration — lives in Netplay_Implementation_Plan.md in the repository root.

Roadmap High-Level

• Core integration: Wrap libretro's netplay API in a Swift-friendly SwiftPM module reusing existing LibretroBridge
• Transport: Initial peer-to-peer via STUN, with optional relay for restrictive NATs
• Matchmaking: Optional centralized matchmaking with room codes — no requirements on local discovery
• Lobby UI: SwiftUI lobby shown as a tab/window; Brawl-style host/join/codes
• Savestate sync: Pull the existing save-state & Time Machine pipeline to seed initial state for retro games that support it