Guía del Desarrollador

Primeros Pasos

Para contribuir a TruchiEmu, necesitarás:

• macOS: 14.0 (Sonoma) o posterior con Swift 5.9+
• Xcode: Última versión estable
• XcodeGen: brew install xcodegen
• Estándar C++: gnu++17 / gnu17

Consulta la guía Compilar desde el Código Fuente para una configuración paso a paso completa y la guía de Contribuir para convenciones y flujo de trabajo.

Pipeline de Compilación

TruchiEmu usa XcodeGen para gestionar la estructura del proyecto dinámicamente desde project.yml. Esto previene conflictos de fusión en el archivo .xcodeproj.

# 1. Clonar el repositorio
git clone https://github.com/JuanchoGithub/truchiemu.git
cd truchiemu

# 2. Generar el proyecto Xcode
xcodegen generate

# 3. Compilar
xcodebuild -project TruchiEmu.xcodeproj -scheme TruchiEmu -configuration Debug build

O ábrelo en Xcode: open TruchiEmu.xcodeproj y presiona ⌘+B.

Agregar Archivos Fuente

Los nuevos archivos fuente bajo TruchiEmu/ y recursos bajo TruchiEmu/Resources/ se incluyen automáticamente mediante rutas recursivas en project.yml. Simplemente agrega tu archivo y ejecuta xcodegen generate para regenerar el proyecto Xcode.

Si necesitas excluir un directorio de la compilación, edita project.yml y regenera.

Arquitectura del Proyecto

TruchiEmu sigue una arquitectura modular que separa el motor de emulación de la interfaz nativa de macOS.

Para una visualización interactiva de cómo estas capas se comunican durante flujos de trabajo comunes, consulta la página de Flujos de Arquitectura de la App.

Sistema de Cores de Emulación

TruchiEmu usa una arquitectura basada en cores impulsada por libretro, permitiendo soporte para múltiples backends de emulación. Cada core es un motor de emulación independiente que funciona como un plug-in.

Cómo Funcionan los Cores

• Especializados: Cada core está orientado a un sistema o familia de sistemas
• Desarrollados Independientemente: Los cores provienen de la comunidad libretro
• Actualizaciones Regulares: Los cores se actualizan independientemente de TruchiEmu
• Intercambiables: Se soportan múltiples cores para el mismo sistema

Asignaciones de Core Predeterminadas

Gestión de Cores

El Descargador de Cores integrado proporciona instalación, actualización y retroceso con un clic para todos los cores. Las opciones por core incluyen ajustes de video y audio, y perfiles de configuración guardables. El bridge Swift ↔ ObjC para la comunicación de cores se encuentra en LibretroBridge.mm / LibretroBridgeSwift.swift.

Bridge Swift ↔ ObjC

El motor de emulación está escrito en Objective-C++/C para acceso directo a la API de libretro. El código Swift se comunica con él a través de LibretroBridge.mm / LibretroBridgeSwift.swift, con símbolos expuestos a través de TruchiEmu-Bridging-Header.h.

Integración de Estados de Guardado

El sistema de cores se integra con SaveStateManager para instantáneas comprimidas con LZ4 con cabeceras TCS2, y SaveDirectoryManager para resolución de rutas. Los guardados de batería son gestionados automáticamente por el core de emulación.

Pipeline de Shaders

El sistema de shaders usa shaders Metal personalizados compilados en tiempo de ejecución, ejecutándose directamente en la GPU a través del framework Metal de Apple.

Componentes Clave

• Compilador de Shaders: Compilación en tiempo de ejecución de archivos shader .metal con manejo de errores
• Sistema de Parámetros: Ajuste en tiempo real de uniforms de shader mediante controles SwiftUI

Archivos de Shaders

Los shaders Metal se encuentran en TruchiEmu/Core/Shaders/. Los directorios slang/, internal/ y all_shaders.metal están excluidos de la compilación de Xcode estos son recursos cargados en tiempo de ejecución desde TruchiEmu_Resources/core_shaders/.

Características de Rendimiento

Passthrough, Smooth Upscale y Vignette tienen un impacto mínimo en la GPU. Los shaders CRT (Multipass, Lottes) y simulaciones LCD usan más recursos de GPU.

Sistema de Temas

El motor de temas proporciona tematización de color acentuado en toda la interfaz de la app, impulsado por un pipeline de tres tipos principales.

Arquitectura

• AccentColorTheme Enum con 16 casos curados (más .custom). Cada uno define colores accent, dimmed (84%), dark (70%) y secondary para modos claro y oscuro. Incluye un sistema migratedRawValue() para temas renombrados.
• ThemeManager Singleton @MainActor ObservableObject que posee el tema actual, modo de apariencia, color acentuado personalizado, toggle de acento en barra de herramientas y toggle de superficies tintadas. Persiste todo el estado vía AppSettings (SwiftData).
• AppColors Tokens de color semántico estáticos en DesignSystem.swift que las vistas consumen. Auto-resuelve vía NSApp.effectiveAppearance. Variantes *ForScheme seguras para previews disponibles.
• Reinicio de App Los cambios de tema llaman ThemeManager.relaunchApp(), generando un nuevo proceso y terminando el actual. La UI de configuración aplica esto con diálogos de confirmación e intercepción de cambios no guardados.

Agregar un Nuevo Tema

1. Agrega un caso al enum AccentColorTheme
2. Define accent, accentDimmed, accentDark, secondaryAccent (y variantes light/dark opcionales)
3. Agrega el recurso de icono a Assets.xcassets/ThemeIcons/
4. Agrega claves de localización: settings.theme.<name> a todos los archivos JSON de idioma
5. Si renombras, agrega mapeo de migración en migratedRawValue()

Convenciones de Tematización

Todas las vistas deben usar los tokens semánticos AppColors nunca codificar valores de color en duro. Los tokens mezclan automáticamente el acento del tema actual en superficies, texto y bordes. Verifica ThemeManager.shared.toolbarAccentEnabled y tintedSurfacesEnabled al aplicar colores acentuados a iconos y superficies de fondo.

Referencia CLI

TruchiEmu proporciona una interfaz de línea de comandos para usuarios avanzados que les permite iniciar juegos y gestionar la aplicación externamente. Gestionada por CLIManager y CLILauncher en la capa de Servicios.

./TruchiEmu "/path/to/game.nes"

Testing y QA

Actualmente no existe un target de tests en el proyecto. Cuando se agreguen tests:

• Crea un target de tests en project.yml y ejecuta xcodegen generate
• Agrega archivos de test bajo TruchiEmuTests/
• Enlaza el framework SwiftData en el target de tests
• Algunos tests pueden requerir acceso a la red (LaunchBox, servicios de miniaturas)

Lectura Adicional