Guia do Desenvolvedor

Primeiros Passos

Para contribuir com o TruchiEmu, você precisará de:

• macOS: 14.0 (Sonoma) ou posterior com Swift 5.9+
• Xcode: Versão estável mais recente
• XcodeGen: brew install xcodegen
• Padrão C++: gnu++17 / gnu17

Consulte o guia de Compilação a Partir do Código-Fonte para um passo a passo completo de configuração e o guia de Contribuição para convenções e fluxo de trabalho.

Pipeline de Compilação

O TruchiEmu usa XcodeGen para gerenciar a estrutura do projeto dinamicamente a partir do project.yml. Isso evita conflitos de merge no arquivo .xcodeproj.

# 1. Clonar o repositório
git clone https://github.com/JuanchoGithub/truchiemu.git
cd truchiemu

# 2. Gerar o projeto Xcode
xcodegen generate

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

Ou abra no Xcode: open TruchiEmu.xcodeproj e pressione ⌘+B.

Adicionando Arquivos de Código-Fonte

Novos arquivos de código-fonte em TruchiEmu/ e recursos em TruchiEmu/Resources/ são incluídos automaticamente via caminhos recursivos no project.yml. Basta adicionar seu arquivo e executar xcodegen generate para regenerar o projeto Xcode.

Se você precisar excluir um diretório da compilação, edite o project.yml e regenere.

Arquitetura do Projeto

O TruchiEmu segue uma arquitetura modular que separa o motor de emulação da interface nativa do macOS.

Para uma visualização interativa de como essas camadas se comunicam durante fluxos de trabalho comuns, consulte a página de Fluxos de Arquitetura do Aplicativo.

Sistema de Cores de Emulação

O TruchiEmu usa uma arquitetura baseada em cores alimentada pelo libretro, permitindo suporte para múltiplos backends de emulação. Cada core é um motor de emulação independente que funciona como um plugin.

Como os Cores Funcionam

• Especializados: Cada core é direcionado a um sistema ou família de sistemas
• Desenvolvidos Independentemente: Os cores vêm da comunidade libretro
• Atualizações Regulares: Os cores são atualizados independentemente do TruchiEmu
• Substituíveis: Múltiplos cores para o mesmo sistema são suportados

Atribuições Padrão de Cores

Gerenciamento de Cores

O Core Downloader integrado oferece instalação, atualização e reversão com um clique para todos os cores. As opções por core incluem configurações de vídeo e áudio, e perfis de configuração salváveis. A bridge Swift ↔ ObjC para comunicação de cores reside em LibretroBridge.mm / LibretroBridgeSwift.swift.

Bridge Swift ↔ ObjC

O motor de emulação é escrito em Objective-C++/C para acesso direto à API libretro. O código Swift se comunica com ele através de LibretroBridge.mm / LibretroBridgeSwift.swift, com símbolos expostos através do TruchiEmu-Bridging-Header.h.

Integração de Save States

O sistema de cores integra-se com o SaveStateManager para snapshots comprimidos com LZ4 com cabeçalhos TCS2, e SaveDirectoryManager para resolução de caminhos. Os salvamentos por bateria são tratados automaticamente pelo core de emulação.

Pipeline de Shaders

O sistema de shaders usa shaders Metal personalizados compilados em tempo de execução, rodando diretamente na GPU através do framework Metal da Apple.

Componentes Principais

• Compilador de Shaders: Compilação em tempo de execução de arquivos shader .metal com tratamento de erros
• Sistema de Parâmetros: Ajuste em tempo real de uniforms de shaders via controles SwiftUI

Arquivos de Shaders

Os shaders Metal ficam em TruchiEmu/Core/Shaders/. Os diretórios slang/, internal/ e all_shaders.metal são excluídos da compilação do Xcode estes são recursos carregados em tempo de execução de TruchiEmu_Resources/core_shaders/.

Características de Desempenho

Passthrough, Scale Smooth e Vignette têm impacto mínimo na GPU. Shaders CRT (Multipass, Lottes) e simulações LCD usam mais recursos de GPU. O sistema seleciona automaticamente fallbacks em hardware menos potente.

Sistema de Temas

O motor de temas fornece coloração de destaque em toda a interface do aplicativo, alimentado por um pipeline de três tipos principais.

Arquitetura

• AccentColorTheme Enum com 16 casos curados (mais .custom para cor personalizada). Cada um define cores de destaque, dimmed (84%), dark (70%) e secundárias para os modos claro e escuro. Inclui um sistema migratedRawValue() para temas renomeados.
• ThemeManager Singleton @MainActor ObservableObject que possui o tema atual, modo de aparência, cor de destaque personalizada, alternância de destaque na barra de ferramentas e alternância de superfícies coloridas. Persiste todo o estado via AppSettings (SwiftData).
• AppColors Tokens de cores semânticas estáticas em DesignSystem.swift que as views consomem. Auto-resolve via NSApp.effectiveAppearance. Variantes *ForScheme seguras para preview disponíveis.
• Reinicialização do Aplicativo Mudanças de tema chamam ThemeManager.relaunchApp(), gerando um novo processo e terminando o atual. A interface de configurações impõe isso com diálogos de confirmação e interceptação de mudanças não salvas.

Adicionando um Novo Tema

1. Adicione um caso ao enum AccentColorTheme
2. Defina accent, accentDimmed, accentDark, secondaryAccent (e variantes claro/escuro opcionais)
3. Adicione o ícone do recurso em Assets.xcassets/ThemeIcons/
4. Adicione chaves de localização: settings.theme.<name> em todos os arquivos JSON de idiomas
5. Se renomeando, adicione o mapeamento de migração em migratedRawValue()

Convenções de Temas

Todas as views devem usar tokens semânticos AppColors nunca use valores de cor fixos no código. Os tokens misturam automaticamente o destaque do tema atual em superfícies, textos e bordas. Verifique ThemeManager.shared.toolbarAccentEnabled e tintedSurfacesEnabled ao aplicar cores de destaque em ícones e superfícies de fundo.

Referência CLI

O TruchiEmu fornece uma interface de linha de comando para usuários avançados iniciarem jogos e gerenciarem o aplicativo externamente. Tratada por CLIManager e CLILauncher na camada de Serviços.

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

A CLI suporta integração com launchers de terceiros e fluxos de trabalho de automação.

Testes e QA

Não existe um alvo de testes atualmente no projeto. Quando testes forem adicionados:

• Crie um alvo de testes no project.yml e execute xcodegen generate
• Adicione arquivos de teste em TruchiEmuTests/
• Vincule o framework SwiftData no alvo de testes
• Alguns testes podem requerer acesso à rede para chamadas de API remotas

Leitura Complementar