realskyrin/ns-game-apple-arm-port

Portabilidade nativa de jogos NS para Apple ARM

O objetivo é produzir resultados visíveis, operáveis e salváveis a partir do código original do jogo no dispositivo alvo. A CPU ARM64 reduz o trabalho de tradução de instruções, mas não elimina a necessidade de camadas de compatibilidade para ABI do SO, memória, threads, gráficos, áudio e entrada.

Requisitos de linguagem e arquitetura

• Novos núcleos de portabilidade devem usar Rust (.rs), com um workspace Cargo separando análise de recursos, ABI compartilhada, reescrita offline, conversão de shaders e runtime host. Projetos Rust existentes devem ser reutilizados; módulos nativos existentes em C/C++ devem ser integrados por meio de limites FFI claros, sem reescrever módulos já validados para unificar a linguagem. Quando o usuário especificar explicitamente outra pilha tecnológica, siga-a e documente as diferenças.
• Swift é usado para launchers e UI da plataforma Apple; Objective-C/Objective-C++, C/C++ para pontes de sistema necessárias ou bibliotecas nativas existentes; assembly AArch64 é limitado a entrada, salvamento de registradores e trampolines de chamada; Metal Shading Language (MSL) é usada para programas GPU. Python/Bash são usados apenas para orquestrar preparação de recursos, construção, assinatura e diagnóstico, não para reprodução quadro a quadro ou caminho crítico de execução do guest.
• A rota é: análise local de recursos → reescrita offline AArch64 → execução nativa do código de máquina do jogo original → compatibilidade Horizon/SDK → gravação de comandos NVN e reprodução Metal. Preserve a lógica original do jogo; não substitua a portabilidade por reescrita de jogabilidade, demonstrações visuais do host ou apenas stubs de API.
• Antes de iniciar a implementação ou reutilização entre jogos, leia architecture-and-workflow.md para determinar os limites dos módulos, a configuração da versão do jogo e o caminho de validação vertical mais curto. Esta referência é extraída da estrutura real de portabilidade Rust/Cargo e não depende da existência do projeto original na máquina local.

Iniciando o trabalho

1. Localize o repositório alvo a partir do diretório especificado pelo usuário ou do workspace atual; leia repositórios de referência apenas se fornecidos pelo usuário ou descobertos no workspace atual, sem assumir nenhum caminho local do desenvolvedor. Leia a descrição do repositório alvo, AGENTS.md local, status Git, entry points de construção e registros de validação mais recentes. Primeiro confirme se o usuário deseja implementar, diagnosticar ou apenas avaliar; tarefas de avaliação devem ser somente leitura.
2. Estabeleça a matriz de entrada: jogo/Title ID, base/atualização/DLC, versão exibida, arquitetura NPDM, build ID real do módulo NSO, SO/chip alvo, versão do código-fonte, modo de execução. Baseie-se nos módulos extraídos reais, não presuma AArch64 pelo nome do arquivo ou nome do jogo.
3. Siga a rota estabelecida. Quando já existir uma base de camada de compatibilidade nativa, reutilize extração, reescrita, host e arquitetura Metal, comparando módulo por módulo; não copie patches de endereço de outros jogos diretamente. Para novos projetos, primeiro verifique se há uma camada de compatibilidade reutilizável antes de decidir o esforço. Entrada AArch32 não se aplica a esta rota de execução direta AArch64; procure uma versão adequada existente com o usuário ou indique claramente a necessidade de outra rota de execução.
4. Primeiro escolha um caminho de validação mínimo reproduzível: inicialização → título/menu → cena → operação → saída normal → carregamento de save em novo processo. Avance gradualmente resolvendo um bloqueio real de cada vez, usando logs, código e imagem para confirmar a causa.

Leitura de referências por problema

• Carregamento de código, patches, ABI Horizon, threads e implantação de plataforma: leia runtime-and-platforms.md.
• Tela preta, artefatos, anomalias de terreno/água, shaders ou problemas de desempenho: leia graphics-and-debugging.md.
• Validação, julgamento de progresso, revisão e transição: leia validation-and-cases.md. Inclui casos transferíveis e limites de evidência.

Ciclo de implementação

• Primeiro registre a camada onde ocorre a falha: extração/identificação → reescrita de instruções → carregamento/realocação → SDK/serviços → gravação de comandos → reprodução/submissão Metal → janela real → comportamento do jogo.
• Use uma hipótese falseável por rodada, colete a evidência mínima necessária e então faça a correção local. As chaves de diagnóstico são desligadas por padrão, com limites de quantidade/tamanho; exceções devem incluir a posição relativa do módulo, informações de requisição ou recurso, e não podem vazar chaves.
• Escolha a validação apropriada para correções semânticas de baixo nível: equivalência de instruções, layout ABI, concorrência, leitura de retorno real da GPU. Após verificação estática e construção, execute o jogo real conforme a autorização do usuário; quando o usuário proibir testes, apenas registre como não validado, não execute por conta própria.
• O código-fonte, construção, pacote de instalação, ID de execução, logs e capturas de tela da versão correspondente devem ser associáveis. Novas construções não podem usar logs de dispositivos antigos para provar sucesso.
• Mantenha contraexemplos de diagnóstico e atualize as conclusões atuais. A captura de quadros/passos pode alterar o tempo; após a correção, re-teste com um novo processo com diagnóstico desligado. Não modifique rigidamente altura do personagem, cor da água, colisões ou progresso do jogo apenas para eliminar anomalias superficiais.
• Para serviços, instruções ou formatos desconhecidos, mantenha uma mensagem de falha clara; implemente degradação com significado semântico apenas quando for comprovado que o chamador permite degradação. Não retorne sucesso genérico para encobrir funcionalidades não implementadas.

Recursos e entrega

• Pacote de origem, chaves e firmware devem permanecer locais; não escreva valores de chave em argumentos de comando, logs ou repositório. Não copie esses conteúdos para a skill. Mantenha a licença e os avisos de direitos autorais do autor original.
• O pacote de origem do usuário é somente leitura; extrações, módulos reescritos, cache, arquivos salvos e logs usam diretórios de dados independentes e ignorados. Isole por jogo e versão, sem sobrescrever estados de outros emuladores; reverter o código-fonte não exclui os arquivos salvos do usuário.
• O cache deve ser capaz de identificar mudanças no build ID de entrada, versão do reescritor/conversor, plataforma e opções de compilação. Versões desconhecidas ou mistas devem ser rejeitadas antes de entrar no código guest.
• Construa, assine e valide separadamente para macOS e iOS/iPadOS. O sucesso do script de instalação prova apenas o estágio correspondente; os resultados para iPhone, iPad, simulador e Mac devem ser relatados separadamente.
• Construções locais para iOS podem conter código reescrito do jogo original; antes de entregar ou publicar, verifique o conteúdo do pacote do aplicativo e a licença, e distribua apenas o conteúdo que você tem direito de distribuir. Não faça upload automático de derivados locais.

O relatório de conclusão deve descrever: o que foi modificado, até que ponto foi executado, a qual construção e dispositivo as evidências correspondem, quais limitações ainda existem e qual bloqueio deve ser verificado a seguir. Evite porcentagens de conclusão não verificáveis ou alegações de "compatibilidade total".