Primeros Pasos con TruchiEmu

Elige Tu Camino

Inicio Rápido: Jugar

1. Descarga e Inicia TruchiEmu

   Descarga la última versión desde el enlace de arriba, muévela a tu carpeta de Aplicaciones y ejecútala. El asistente de configuración aparecerá en el primer inicio.

2. Agrega Tus Carpetas de ROMs

   Cuando aparezca el asistente, haz clic en el botón de carpeta para seleccionar el directorio que contiene tus ROMs. Puedes agregar múltiples carpetas — TruchiEmu las escanea recursivamente. También puedes agregar carpetas más tarde desde la barra de herramientas de la biblioteca (botón folder.badge.plus) o con Shift+Cmd+O.

3. Espera el Escaneo

   TruchiEmu identifica automáticamente tus juegos usando hashes CRC32 y bases de datos DAT, descarga carátulas y enriquece los metadatos. Un indicador de progreso muestra el estado del escaneo.

4. Doble Clic para Jugar

   Cualquier juego en tu biblioteca se puede iniciar con un doble clic. La primera vez que juegues un juego de un sistema determinado, TruchiEmu mostrará una hoja de selección de core donde podrás descargar el core de emulación necesario — después de eso, se inicia instantáneamente.

Asistente de Configuración

En el primer inicio, TruchiEmu te guía a través de un asistente de configuración de 4 pasos:

Agregar y Gestionar Juegos

Importar Juegos

TruchiEmu usa escaneo basado en carpetas — agrega un directorio y la app encuentra todas las ROMs compatibles dentro. Hay varias formas de agregar carpetas:

• Asistente de Configuración: Agrega carpetas durante la configuración inicial
• Barra de Herramientas de la Biblioteca: Haz clic en el botón folder.badge.plus en la parte superior de tu biblioteca
• Barra de Menú: Juegos → Agregar Carpeta de ROMs (Shift+Cmd+O)
• Configuración: Navega a Configuración → Biblioteca → Carpetas de Biblioteca y haz clic en “Agregar Carpeta”
• Biblioteca Vacía: Aparece un botón destacado “Agregar Carpeta de ROMs” cuando tu biblioteca está vacía

Cómo Funciona el Escaneo

Cuando agregas una carpeta, TruchiEmu la escanea recursivamente e identifica juegos usando hashes CRC32 contra bases de datos DAT — no solo extensiones de archivo. Esto significa que tus ROMs se identifican con precisión independientemente del nombre del archivo. Después de la identificación, la app automáticamente:

• Descarga carátulas desde el CDN de Libretro (con fuentes opcionales de LaunchBox y ScreenScraper)
• Enriquece los metadatos (género, cantidad de jugadores, distribuidor)
• Filtra archivos BIOS y recursos del sistema para que solo aparezcan juegos jugables

Reescaneo y Mantenimiento

Si agregas nuevas ROMs a una carpeta existente, reescanea para detectarlas:

• Reescaneo Completo: Configuración → Biblioteca → Mantenimiento → “Reescaneo Completo de Biblioteca”, o usa Shift+Cmd+R
• Actualización por Carpeta: En Configuración → Biblioteca, cada carpeta tiene un botón “Actualizar”
• Actualización por Sistema: Haz clic derecho en un sistema en la barra lateral y elige “Actualizar”
• Reconstruir: Para una limpieza más profunda, cada carpeta tiene una opción “Reconstruir” con múltiples estrategias

Gestión de Formatos de Archivo

Organización de la Biblioteca

TruchiEmu ofrece varias formas de navegar y organizar tu colección de juegos:

Navegación por la Barra Lateral

• Todos los Juegos: Tu biblioteca completa de un vistazo
• Favoritos: Juegos que has marcado como favoritos (clic derecho → “Agregar a Favoritos”)
• Recientes: Juegos que has jugado recientemente
• Retro Achievements: Juegos con logros coincidentes (visible cuando RA está habilitado)
• Por Sistema: Navega por consola (NES, SNES, GBA, Genesis, etc.)
• Categorías: Grupos personalizados que creas con nombres, iconos y colores personalizados
• Juegos Ocultos: Juegos que has ocultado de la vista principal (clic derecho → “Ocultar Juego”)
• Archivos MAME Ocultos: Entradas no-juego de MAME filtradas (visible cuando aplica)

Modos de Vista

Alterna entre vista de Cuadrícula y Lista usando el control segmentado en la barra de herramientas. En modo cuadrícula, un control deslizante ajusta el tamaño de las tarjetas y la cantidad de columnas.

Búsqueda y Filtros

• Búsqueda: Escribe en el campo de búsqueda (o presiona Cmd+F) — soporta búsqueda con múltiples términos (todos deben coincidir)
• Filtros Rápidos: “Sin Carátula”, “Nunca Jugado”, “No Identificado”, “Multijugador”, “Género”
• Chips de Orden: “Último Jugado” y “Último Agregado” (en la misma barra de chips que los filtros; orden predeterminado es alfabético)

Categorías

Crea categorías personalizadas desde la barra lateral — dales un nombre, icono (desde SF Symbols) y color. Agrega juegos a categorías mediante arrastrar y soltar o el menú contextual con clic derecho.

Controles y Entrada

Valores Predeterminados del Teclado para Juego

Los mapeos predeterminados varían por sistema. La tabla muestra la configuración predeterminada/fallback:

Atajos de Teclado Durante el Juego

Soporte de Controladores

TruchiEmu detecta automáticamente los controladores cuando se conectan vía USB o Bluetooth y los asigna al siguiente slot de jugador disponible (hasta 4 jugadores). Aparece una notificación al conectar.

• Controladores Xbox: Xbox One y Series X|S
• Controladores PlayStation: DualShock 4 y DualSense (PS5)
• Controladores MFi: Gamepads certificados por Apple
• HID Genérico: La mayoría de los gamepads USB/Bluetooth funcionan directamente

Personalizar Controles

Abre Configuración → Controladores para reasignar cualquier botón. La configuración de controladores incluye:

• Selector de Sistema: Configura mapeos por sistema o establece un “Predeterminado Global”
• Slots de Jugador: Asigna controladores a P1–P4
• Reasignación de Gamepad: Haz clic en un nombre de botón, luego presiona un botón físico en tu controlador para asignarlo
• Reasignación de Teclado: Haz clic en un nombre de botón, luego presiona una tecla para reasignarla
• Perfiles de Gamepad: Guarda y carga configuraciones de mapeo con nombre (solo gamepad)

Estados de Guardado

TruchiEmu proporciona una gestión flexible de estados de guardado con 11 slots, versionado progresivo y opciones de auto-guardado/carga.

Slots

Hay 11 slots de guardado: un slot Auto (slot -1) más los slots 0 al 9. Cada slot puede almacenar hasta 5 versiones progresivas (predeterminado: 3), dándote múltiples instantáneas por slot.

Guardar y Cargar

Auto-Guardado y Auto-Carga

Ambas configuraciones se pueden cambiar en Configuración → Guardados.

Estados de Guardado vs. Guardados de Batería

Personalizar TruchiEmu

Temas y Apariencia

TruchiEmu incluye 17 temas de color de acento — incluyendo temas inspirados en videojuegos — más la capacidad de elegir cualquier color personalizado. Configúralos en Configuración → General:

• Modo de Apariencia: Claro, Oscuro o Automático (sigue el sistema)
• Cuadrícula de Temas: 7 temas estándar (Samus, Chocobo, Protoss, Joker, Geralt, Mega Man, Custom) y 10 temas de gaming (Mario, Luigi, Sonic, Half-Life, Kratos, Kirby, Zelda, Pikachu, Doom, Master Chief)
• Color Personalizado: Elige cualquier color con el selector de colores del sistema cuando “Custom” está seleccionado
• Acento de Barra de Herramientas: Activa/desactiva iconos de barra de herramientas con color de acento
• Superficies Teñidas: Activa/desactiva el tinte de acento en fondos de ventana/barra lateral/barra de herramientas

Shaders

TruchiEmu incluye 14 shaders Metal integrados en 5 categorías, más soporte para presets personalizados:

• Simulación CRT: CRT Lottes, CRT Classic, Lite CRT, CRT Multipass — líneas de escaneo auténticas, brillo de fósforo y curvatura
• LCD de Portátil: 8b Game Boy, 8b Game Boy Color, GBA Advanced LCD, PSP Advanced LCD, NDS Advanced LCD, 3DS Advanced LCD, Dot Matrix LCD
• Suavizado: Sharp Bilinear, Smooth Upscale (ScaleFX) — escalado dirigido por bordes
• Compuesto: Desenfoque compuesto/VHS para efectos de señal analógica auténticos
• Presets Personalizados: Crea y guarda tus propios presets .truchishader; también incluye una opción de passthrough “Sin Shader”

Los shaders se pueden cambiar en tiempo real durante el juego — sin necesidad de reiniciar. Consulta la Guía de Shaders para más detalles.

Bezels

Los bezels son marcos decorativos que enmarcan la pantalla del juego con ilustraciones específicas del sistema. TruchiEmu puede descargar y asociar automáticamente bezels para tus juegos. Configúralos en la configuración de shaders/bezels, u opta por ellos durante el asistente de configuración. Consulta la Guía de Bezels para más detalles.

Compilar desde el Código Fuente

Si quieres contribuir a TruchiEmu o compilarlo tú mismo, sigue estos pasos.

brew install xcodegen

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

# Método CLI:
xcodebuild -project TruchiEmu.xcodeproj -scheme TruchiEmu -configuration Debug build

Para más detalles sobre el proceso de compilación, arquitectura del proyecto y guías de contribución, consulta la Guía del Desarrollador y la Guía de Compilación.

Siguientes Pasos