Primeiros Passos com o TruchiEmu

Assistente de Configuração

No primeiro lançamento, o TruchiEmu guia você por um assistente de configuração de 4 passos:

Adicionar e Gerenciar Jogos

Importando Jogos

O TruchiEmu usa escaneamento baseado em pastas — adicione um diretório e o aplicativo encontra todas as ROMs compatíveis dentro dele. Há várias formas de adicionar pastas:

• Assistente de Configuração: Adicione pastas durante a configuração inicial
• Barra de Ferramentas da Biblioteca: Clique no botão folder.badge.plus no topo da sua biblioteca
• Barra de Menu: Jogos → Adicionar Pasta de ROMs (Shift+Cmd+O)
• Configurações: Navegue até Configurações → Biblioteca → Pastas da Biblioteca e clique em “Adicionar Pasta”
• Biblioteca Vazia: Um botão destacado “Adicionar Pasta de ROMs” aparece quando sua biblioteca está vazia

Como o Escaneamento Funciona

Quando você adiciona uma pasta, o TruchiEmu a escaneia recursivamente e identifica jogos usando hashing CRC32 contra bancos de dados DAT — não apenas extensões de arquivo. Isso significa que suas ROMs são identificadas com precisão independentemente do nome do arquivo. Após a identificação, o aplicativo automaticamente:

• Baixa capas do CDN Libretro (com fontes opcionais LaunchBox e ScreenScraper)
• Enriquece os metadados (gênero, número de jogadores, editora)
• Filtra arquivos de BIOS e recursos do sistema para que apenas jogos jogáveis apareçam

Reescaneamento e Manutenção

Se você adicionar novas ROMs a uma pasta existente, reescaneie para detectá-las:

• Reescaneamento Completo: Configurações → Biblioteca → Manutenção → “Reescaneamento Completo da Biblioteca”, ou use Shift+Cmd+R
• Atualização por Pasta: Em Configurações → Biblioteca, cada pasta tem um botão “Atualizar”
• Atualização por Sistema: Clique com o botão direito em um sistema na barra lateral e escolha “Atualizar”
• Reconstruir: Para uma limpeza mais profunda, cada pasta tem uma opção “Reconstruir” com múltiplas estratégias

Manipulação de Formatos de Arquivo

Organização da Biblioteca

O TruchiEmu oferece várias formas de navegar e organizar sua coleção de jogos:

Navegação pela Barra Lateral

• Todos os Jogos: Toda sua biblioteca de um golpe
• Favoritos: Jogos que você marcou (clique direito → “Adicionar aos Favoritos”)
• Recentes: Jogos que você jogou recentemente
• Por Sistema: Navegue por console (NES, SNES, GBA, Genesis, etc.)
• Categorias: Grupos personalizados que você cria com nomes, ícones e cores personalizados
• Jogos Ocultos: Jogos que você ocultou da visualização principal (clique direito → “Ocultar Jogo”)

Modos de Visualização

Alterne entre visualização em Grade e Lista usando o controle segmentado na barra de ferramentas. No modo grade, um controle deslizante ajusta o tamanho dos cartões e a quantidade de colunas.

Pesquisa e Filtros

• Pesquisa: Digite no campo de pesquisa (ou pressione Cmd+F) — suporta pesquisa com múltiplos termos (todos devem corresponder)
• Filtros Rápidos: “Sem Capa”, “Nunca Jogado”, “Não Identificado”, “Multijogador”, “Gênero”
• Ordenar: “Último Jogado”, “Último Adicionado” e “Alfabética” (padrão) — chips de ordenação aparecem na barra de filtros

Seções Adicionais da Barra Lateral

• Retro Achievements: Acompanhe conquistas do RetroAchievements
• Arquivos MAME Ocultos: Acesse recursos de sistema MAME que estão ocultos da biblioteca principal

Categorias

Crie categorias personalizadas pela barra lateral — dê a elas um nome, ícone (dos SF Symbols) e cor. Adicione jogos a categorias arrastando e soltando ou pelo menu de contexto com clique direito.

Controles e Entrada

Padrões de Teclado para Jogabilidade

Atalhos de Teclado Durante o Jogo

Suporte a Controles

O TruchiEmu detecta automaticamente os controles quando conectados via USB ou Bluetooth e os atribui ao próximo slot de jogador disponível (até 4 jogadores). Uma notificação aparece ao conectar.

• Controles Xbox: Xbox One e Series X|S
• Controles PlayStation: DualShock 4 e DualSense (PS5)
• USB Genérico: Controles MFi e HID funcionam imediatamente

Personalizar Controles

Abra Configurações → Controles para remapear qualquer botão. As configurações de controle incluem:

• Seletor de Sistema: Configure mapeamentos por sistema ou defina um “Padrão Global”
• Slots de Jogador: Atribua controles a P1–P4
• Remapeamento de Gamepad: Clique em um nome de botão, depois pressione um botão físico no seu controle para atribuí-lo
• Remapeamento de Teclado: Clique em um nome de botão, depois pressione uma tecla para reatribuir
• Perfis: Salve e carregue configurações de mapeamento nomeadas (gamepads apenas)

Save States

O TruchiEmu oferece gerenciamento flexível de save states com 11 slots, versionamento progressivo e opções de auto-salvamento/carregamento.

Slots

Existem 11 slots de salvamento: um slot Auto (slot -1) mais os slots 0 a 9. Cada slot pode armazenar até 5 versões progressivas (padrão: 3), dando a você múltiplos instantâneos por slot.

Salvar e Carregar

Auto-Salvamento e Auto-Carregamento

Ambas as configurações podem ser alteradas em Configurações → Salvamentos.

Save States vs. Salvamentos por Bateria

Personalizar o TruchiEmu

Temas e Aparência

O TruchiEmu vem com 17 temas de cor de destaque — de Samus a Doom — além da capacidade de escolher qualquer cor personalizada. Configure-os em Configurações → Geral:

• Modo de Aparência: Claro, Escuro ou Automático (segue o sistema)
• Grade de Temas: 7 temas padrão (Samus, Chocobo, Protoss, Joker, Geralt, Mega Man, Custom) e 10 temas de gaming (Mario, Luigi, Sonic, Half-Life, Kratos, Kirby, Zelda, Pikachu, Doom, Master Chief)
• Cor Personalizada: Escolha qualquer cor com o seletor de cores do sistema quando “Custom” está selecionado
• Destaque da Barra de Ferramentas: Ative/desative ícones da barra de ferramentas com cor de destaque
• Superfícies Tintadas: Ative/desative o tinte de destaque nos fundos de janela/barra lateral/barra de ferramentas

Shaders

O TruchiEmu inclui 14 shaders Metal integrados em 5 categorias, mais suporte para presets personalizados:

• Simulação CRT: CRT Lottes, CRT Classic, Lite CRT, CRT Multipass — linhas de varredura autênticas, brilho de fósforo e 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
• Suavização: Sharp Bilinear, Smooth Upscale (ScaleFX) — escalonamento dirigido por bordas
• Composto: Desfoque composto/VHS para efeitos autênticos de sinal analógico
• Presets Personalizados: Crie e salve seus próprios presets .truchishader; também inclui uma opção de passthrough “Sem Shader”

Shaders podem ser alterados em tempo real durante o jogo — sem necessidade de reiniciar. Consulte o Guia de Shaders para detalhes completos.

Bezels

Bezels são molduras decorativas que emolduram a tela do jogo com ilustrações específicas do sistema. O TruchiEmu pode baixar e corresponder automaticamente bezels para seus jogos. Configure bezels nas configurações de shaders/bezels, ou opte por eles durante o assistente de configuração. Consulte o Guia de Bezels para detalhes.

Compilando a Partir do Código-Fonte

Se você quer contribuir com o TruchiEmu ou compilá-lo você mesmo, siga estes passos.

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 mais detalhes sobre o processo de compilação, arquitetura do projeto e diretrizes de contribuição, consulte o Guia do Desenvolvedor e o Guia de Compilação.

Próximos Passos