Gerenciamento da Biblioteca

Visão Geral

A biblioteca é onde seus jogos vivem. Aponte o TruchiEmu para suas pastas de ROMs e ele faz o resto: descobre a qual sistema cada arquivo pertence, identifica o jogo, obtém um título e descrição, e baixa a capa. Navegue por sistema, favoritos, jogados recentemente ou as categorias que você criou.

O Que Ele Faz por Você

• Identificação CRC32: Hash CRC32 acelerado por hardware (via zlib) contra bancos DAT — não apenas extensões de arquivo — para identificar ROMs com precisão independentemente do nome
• Rastreamento de Rejeição MAME: A identificação MAME usa rastreamento de rejeição e um algoritmo de pontuação refinado; entradas MAME não-jogo são filtradas automaticamente
• Serviço de Metadados LaunchBox: O enriquecimento de metadados em segundo plano obtém descrições, datas de lançamento, editora, número de jogadores e gênero. Overrides de plataforma melhoram a pontuação entre sistemas
• Prioridade de Box Art: As capas são obtidas do ScreenScraper e Libretro CDN com prioridade configurável; um seletor interativo de Box Art permite trocar a capa alternativa por jogo
• Download de Assets PPSSPP: Assets específicos do PPSSPP são baixados e aplicados automaticamente ao detectar uma ROM de PSP
• Seleção de Região de Box Art: Escolha a região preferida para capas por jogo ou global; miniaturas são geradas, cacheadas e reamostradas eficientemente
• Materialização do iCloud: Placeholders do iCloud são materializados ao acessar, para que ROMs armazenadas no iCloud sejam exibidas corretamente — sem stubs de zero bytes na sua lista
• Notificações de Remoção de ROMs: Quando ROMs são removidas de pastas monitoradas, a biblioteca é atualizada automaticamente e publica uma notificação — sem necessidade de reescaneamento manual
• Organizado do Seu Jeito: Navegue por sistema, favoritos, recentes, últimos adicionados, categorias personalizadas ou compatibilidade com RetroAchievements
• Grade ou Lista: Alterne entre a grade de capas (com controle deslizante de zoom) e a visualização de lista compacta
• Busca e Filtros: Busca por digitação na janela principal (busca multi-termo); chips de filtro rápido para "sem capa", "nunca jogado", "não identificado", "multijogador", "gênero"
• Barra Lateral Inteligente: As linhas de coleções inteligentes no SystemSidebarView respeitam a consulta de busca ativa — sistemas ocultos permanecem ocultos ao filtrar
• Compatibilidade com RetroAchievements: Jogos com conquistas são marcados e podem ser filtrados para mostrar apenas esses

Automação Pós-Escaneamento

O TruchiEmu não apenas escaneia — após o escaneamento, o LibraryAutomationCoordinator executa um pipeline pós-escaneamento: identificar → enriquecer metadados → baixar capa. O pipeline respeita o RunningGamesTracker para que o trabalho pesado pós-escaneamento pause durante o jogo.

Pipeline de Identificação

1. Escaneamento

   ROMScanner (um actor do Swift) escaneia diretórios recursivamente, filtra por extensão e identifica arquivos MAME em uma única passada.

2. Hash e Correspondência

   ROMIdentifierService calcula CRC32 em paralelo (semáforo de 4 vias para limitação de E/S) e compara com bancos DAT. ROMIdentifier usa pontuação ponderada: cabeçalhos mágicos > extensões únicas > padrões de nome > contexto de caminho.

3. Enriquecimento de Metadados

   O Serviço de Metadados LaunchBox enriquece os jogos identificados com descrição, data de lançamento, editora, número de jogadores e gênero.

4. Download de Capas

   BoxArtService obtém capas do ScreenScraper e Libretro CDN conforme sua prioridade. Respeita preferências de região. BoxArtThumbnailService gera e cacheia miniaturas para renderização rápida em grade.

5. Categorização por Gênero

   Os gêneros são populados a partir dos metadados e expostos como chips de filtro na barra lateral da biblioteca.

Gerenciamento de Pastas da Biblioteca

Adicionar Pastas

• Assistente de Configuração: Adicione uma ou mais pastas durante a configuração inicial
• Barra de Ferramentas: 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: Ajustes → Biblioteca → Pastas da Biblioteca, clique em "Adicionar Pasta"

Reescaneamento e Reconstrução

• Reescaneamento Completo: Ajustes → Biblioteca → Manutenção → "Reescaneamento Completo da Biblioteca" (ou Shift+Cmd+R)
• Atualização por Pasta: Cada pasta tem um botão "Atualizar" (e uma opção "Reconstruir" com múltiplas estratégias)
• Atualização por Sistema: Clique com o botão direito em um sistema na barra lateral e escolha "Atualizar"
• Arquivos MAME Ocultos: Entradas MAME não-jogo filtradas ficam sob uma entrada "Arquivos MAME Ocultos" na barra lateral, não na grade principal

Gêneros e Categorias

Navegue por gênero usando o chip de filtro de gênero (baseado em metadados do LaunchBox), ou crie categorias personalizadas com nomes, ícones SF Symbol, ícones personalizados e cores por categoria.

• Categorias Personalizadas: Arraste e solte jogos em categorias personalizadas, ou use o menu de contexto
• Favoritos: Clique direito → "Adicionar aos Favoritos" para acesso rápido
• Jogados Recentemente: Rastreamento automático baseado no histórico de inicialização
• Jogos Ocultos: Clique direito → "Ocultar Jogo" para manter a grade principal organizada
• Gerenciamento de Gêneros: Ajustes → Gêneros fornece controles por gênero

Recursos Relacionados