Realskyrin/ns-game-apple-arm-port

Portage natif des jeux NS vers Apple ARM

L'objectif est d'obtenir un résultat visible, exploitable et sauvegardable du code du jeu original sur l'appareil cible. Le CPU étant également ARM64, cela réduit le travail de traduction des instructions, mais ne dispense pas de créer des couches de compatibilité pour l'ABI du système d'exploitation, la mémoire, les threads, le graphisme, l'audio et les entrées.

Langue et architecture requises

• Le cœur du nouveau portage doit être écrit en Rust (.rs), en utilisant un espace de travail Cargo pour séparer l'analyse des ressources, l'ABI partagée, la réécriture hors ligne, la conversion des shaders et le runtime hôte. Les projets Rust existants sont directement réutilisés ; les modules natifs en C/C++ sont intégrés via des interfaces FFI clairement définies, sans réécrire les modules déjà validés dans un langage unifié. Si l'utilisateur spécifie explicitement une autre pile technologique, elle est suivie et les différences sont documentées.
• Swift est utilisé pour le lanceur et les interfaces utilisateur de la plateforme Apple ; Objective-C/Objective-C++, C/C++ pour les ponts système nécessaires ou les bibliothèques natives existantes ; l'assembleur AArch64 est limité aux points d'entrée, à la sauvegarde des registres et aux trampolines d'appel ; Metal Shading Language (MSL) pour les programmes GPU. Python/Bash orchestrent uniquement la préparation des ressources, la construction, la signature et le diagnostic, et ne portent pas la lecture image par image ou les chemins chauds d'exécution du guest.
• La feuille de route est : analyse locale des ressources → réécriture hors ligne AArch64 → exécution native du code machine du jeu original → compatibilité Horizon/SDK → enregistrement des commandes NVN et leur lecture avec Metal. La logique originale du jeu est conservée ; on ne réécrit pas les mécanismes de jeu, on ne produit pas de démonstration hôte, on ne remplace pas le portage par des stubs d'API vides.
• Avant de commencer l'implémentation ou la réutilisation entre jeux, lisez architecture-and-workflow.md pour déterminer les limites des modules, la configuration de la version du jeu et le chemin de validation vertical le plus court. Cette référence est tirée de la structure réelle de portage en Rust/Cargo et ne dépend pas de la présence du projet original sur la machine locale.

Commencer le travail

1. Localisez le dépôt cible à partir du répertoire spécifié par l'utilisateur ou de l'espace de travail actuel ; les dépôts de référence ne sont lus que s'ils sont fournis par l'utilisateur ou trouvés dans l'espace de travail actuel, sans supposer aucun chemin local chez le développeur. Lisez la description du dépôt cible, le fichier AGENTS.md local, l'état Git, le point d'entrée de la construction et les derniers enregistrements de validation. Déterminez d'abord si l'utilisateur souhaite implémenter, diagnostiquer ou simplement évaluer ; les tâches d'évaluation restent en lecture seule.
2. Établissez une matrice d'entrée : jeu/Title ID, jeu de base/mise à jour/DLC, version affichée, architecture NPDM, ID de build du module NSO réel, système d'exploitation/puce cible, version du code source, mode d'exécution. Basez-vous sur les modules réellement extraits, ne déduisez pas AArch64 du nom de fichier ou du nom du jeu.
3. Respectez la feuille de route établie. Si une base de compatibilité native existe déjà, réutilisez l'architecture d'extraction, de réécriture, de l'hôte et de Metal, et comparez module par module ; ne copiez pas directement les correctifs d'adresse d'un autre jeu. Pour un nouveau projet, vérifiez d'abord s'il existe une couche de compatibilité réutilisable, puis décidez de la charge de travail. Les entrées AArch32 ne sont pas adaptées à cette voie d'exécution AArch64 directe ; recherchez une version appropriée existante chez l'utilisateur ou définissez clairement qu'une autre voie d'exécution est nécessaire.
4. Commencez par sélectionner un chemin de validation le plus court et reproductible : démarrage → titre/menu → scène → action → sortie normale → nouveau processus chargeant la sauvegarde. Avancez par étapes en résolvant un blocage réel à la fois, en utilisant les journaux, le code et l'image pour confirmer la cause.

Références par problème

• Chargement du code, correctifs, ABI Horizon, threads et déploiement sur plateforme : lisez runtime-and-platforms.md.
• Écran noir, écran blanc, anomalies de couleur de terrain/eau, problèmes de shader ou de performances : lisez graphics-and-debugging.md.
• Validation, évaluation de l'avancement, rétrospective et passation : lisez validation-and-cases.md. Contient des cas reproductibles et des limites de preuves.

Boucle d'implémentation

• Enregistrez d'abord la couche du défaut : extraction/identification → réécriture des instructions → chargement/relogement → SDK/services → enregistrement des commandes → lecture Metal/soumission → fenêtre réelle → comportement du jeu.
• Pour chaque itération, utilisez une hypothèse falsifiable, collectez les preuves minimales nécessaires, puis effectuez une réparation locale. Les commutateurs de diagnostic sont désactivés par défaut, avec des limites de quantité/taille ; les exceptions doivent inclure la position relative du module, l'identifiant de la demande ou de la ressource, sans divulguer les clés.
• Choisissez une validation appropriée pour les corrections sémantiques de bas niveau : équivalence des instructions, disposition de l'ABI, concurrence, lecture réelle du GPU. Après une vérification statique et la construction, exécutez le jeu réel dans les limites d'autorisation de l'utilisateur ; si l'utilisateur interdit les tests, enregistrez simplement que la validation n'a pas été effectuée, n'exécutez pas sans autorisation.
• Les sources, builds, paquets d'installation, identifiants d'exécution, journaux et captures d'écran correspondants à une version donnée doivent pouvoir être mis en relation. Un nouveau build ne peut pas prouver le succès en utilisant des journaux d'un ancien appareil.
• Conservez les contre-exemples de diagnostic et mettez à jour les conclusions actuelles. La capture d'image/le pas à pas peut modifier le timing ; après une correction, re-testez avec un nouveau processus dont le diagnostic est désactivé. Ne modifiez pas la hauteur du personnage, la couleur de l'eau, les collisions ou l'avancement du jeu pour éliminer des anomalies superficielles.
• Pour les services, instructions ou formats inconnus, conservez un message d'échec explicite ; n'implémentez une dégradation sémantique que si la preuve est faite que l'appelant autorise cette dégradation. Ne renvoyez pas un succès général pour masquer des fonctionnalités non implémentées.

Ressources et livraison

• Gardez les paquets sources, les clés et le firmware en local ; n'écrivez pas les valeurs des clés dans les paramètres de commande, les journaux ou le dépôt. Ne copiez pas ces contenus dans la compétence. Conservez les licences et mentions de copyright originales.
• Les paquets sources de l'utilisateur sont en lecture seule ; le contenu extrait, les modules réécrits, le cache, les archives et les journaux utilisent un répertoire de données indépendant et ignoré. Isolez-les par jeu et par version, ne remplacez pas l'état d'autres émulateurs ; le retour d'un commit de source ne supprime pas les sauvegardes de l'utilisateur.
• Le cache doit être capable de reconnaître les changements d'ID de build d'entrée, de version du réécrivain/convertisseur, de plateforme et d'options de compilation. Les versions inconnues ou mixtes doivent être rejetées avant l'entrée dans le code guest.
• Construisez, signez et validez séparément pour macOS et iOS/iPadOS. Le succès du script d'installation ne prouve que l'étape correspondante ; les résultats pour iPhone, iPad, simulateur et Mac sont rapportés séparément.
• Les builds iOS locaux peuvent contenir du code réécrit du jeu original ; avant de livrer ou de publier, vérifiez le contenu du paquet d'application et les licences, et ne distribuez que le contenu que vous avez le droit de distribuer. Ne téléchargez pas automatiquement les dérivés locaux.

Le rapport de fin doit indiquer : ce qui a été modifié, jusqu'où l'exécution est allée, à quel build et appareil les preuves correspondent, les limites restantes, et quel blocage doit être validé ensuite. Évitez les pourcentages d'achèvement non vérifiables ou les mentions de "compatibilité totale".