Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

21.3 KB
Raw Blame

Follows CONTRIBUTING.md as of v1.0.2

Contribuire al progetto

Segnalazioni (issue) e pull request sono sempre benvenute. NX2Apple costituisce il launcher (frontend/, frontend-qt/) e il livello di integrazione attorno al motore nxnative, che viene scaricato qui come progetto upstream a un commit fissato più una coda di patch (python3 tools/engine.py sync assembla il tutto nella cartella engine/) e viene aggiornato ogni giorno all'ultima versione disponibile upstream. AGENTS.md descrive questo repository, mentre engine/AGENTS.md descrive il motore. La compilazione manuale da terminale (strumenti, prod.keys e creazione dell'IPA) è descritta nella pagina dedicata: BUILDING.it.md.

Segnalare un problema

I problemi di gioco, i problemi di compilazione e i problemi del launcher dispongono ciascuno di un apposito modulo di segnalazione (.github/ISSUE_TEMPLATE/). Il modulo richiede tutte le informazioni necessarie per analizzare il caso — versioni, dispositivo, output di Copia diagnostica, righe del profilo di gioco nel log di compilazione, log del gioco ed eventuale crash report. Compilalo direttamente dalla pagina Issues. Una segnalazione priva di questi dati risulta solitamente impossibile da verificare.

Dove aprire una segnalazione

  • Qui: per l'app, per una compilazione o un'installazione non riuscita e per un gioco che non gira correttamente sul tuo Mac, iPhone o iPad.
  • Discussions: per domande (Q&A) e proposte o idee (Ideas). I bug restano nelle Issues.
  • seedds/nxnative: per il funzionamento interno del motore, il porting di un nuovo gioco (il cui profilo va inviato lì tramite pull request, vedi "Aiutare con i giochi") o un difetto di rendering che hai ricondotto direttamente al motore stesso.

Cosa serve in una segnalazione

Scegli il modulo appropriato: Game problem, Build problem oppure Launcher problem or idea. Ciascuno richiede gli elementi indispensabili per ricostruire il problema: il gioco, il suo Title ID e le versioni, la destinazione scelta, il dispositivo e il sistema operativo, la versione di NX2Apple, l'output di Impostazioni > Copia diagnostica e il file di log (il log del gioco o il log di compilazione nella pagina Compilazioni). A una segnalazione sprovvista di questi dati verrà innanzitutto richiesto di aggiungerli. Dove trovare il log di un gioco: su Mac, un gioco situato in una cartella della libreria scrive log/<title ID>.log accanto alla propria app, altrimenti in ~/Library/Logs/nxnative/<title ID>.log. Su iPhone o iPad è il file log.txt all'interno dell'app File.

Non allegare mai chiavi, file di gioco o qualsiasi elemento estratto da un gioco. File di log, screenshot, Title ID e Build ID vanno invece benissimo.

Aiutare con i giochi

Ogni nuovo gioco richiede un lavoro di adattamento (bring-up) specifico: un profilo (Build ID, layout di memoria, slot delle texture), un lettore di shader nel caso in cui li impacchetti in un formato non ancora supportato e i punti di patch. Il profilo di un gioco fa parte del codice del motore (dm/games/<id>/) e il motore risiede in seedds/nxnative. Ecco i modi in cui puoi dare una mano, tutti preziosi:

  • Segnala un gioco che funziona — se sei riuscito a far girare un titolo non ancora presente nell'elenco dei giochi verificati, apri una issue indicando il Title ID, la versione dell'aggiornamento e i passaggi che hai seguito. Diventerà una voce in GAMES.it.md (e GAMES.md) utile a tutti gli altri utenti.
  • Invia il profilo di un nuovo gioco, o una correzione al motore, prima a seedds/nxnative. Apri la pull request lì seguendo il loro file CONTRIBUTING.md (un nuovo gioco richiede il relativo profilo, la nota tecnica e la riga nella tabella dei giochi). Se il gioco è rilevante anche per i dispositivi Apple su questo fork, inserisci il link alla tua pull request in una issue di tipo Game problem qui, oppure in un commento a una issue già esistente. Ti chiediamo di non inviarlo direttamente qui sotto forma di patch. Se il progetto upstream impiega tempo a rispondere e il gioco è stato verificato qui, un manutentore potrà includerlo temporaneamente in patches/ come ponte (Upstream-Status: forwarded) riconoscendoti i crediti. Se non ti è possibile aprire la pull request upstream, se ne occuperà un manutentore.
  • Invia gli shader mancanti — se un gioco gira ma presenta brevi blocchi al primo utilizzo di un effetto grafico, significa che le relative varianti shader mancano dalla mappa. L'host può esportare gli shader che non trova (DM_NVN_SHDUMP=<cartella>). Allegali a una issue e li aggiungeremo a shader_map.tsv a beneficio di tutti.

Le segnalazioni che includono il file Documents/log.txt completo vengono esaminate per prime — quel log indica quasi sempre l'elemento esatto che manca.

Aprire una pull request

  • Prima di iniziare qualsiasi lavoro in un clone o in un worktree, esegui git config core.hooksPath .githooks. Gli hook eseguono i controlli necessari su ciò che confermi con commit e invii con push (python3 tools/engine.py check per patches/ e i test per il codice modificato, vedi tools/githooks.py). I comandi tools/engine.py sync, check ed export installano automaticamente gli hook se non sono già attivi. Mantienili attivi e non usare mai --no-verify. Non eseguire mai un push diretto sul branch main. L'hook di pre-push lo rifiuta per qualsiasi strumento e il ruleset "Main rule" su GitHub lo blocca per chiunque, senza eccezioni.
  • Una sola modifica per PR, partendo da main. I messaggi di commit devono spiegare cosa è cambiato e perché, in inglese chiaro e semplice, seguendo lo stile visibile in git log.
  • Compila il template della PR indicando cosa è stato fatto e perché, cosa è stato verificato e includendo gli screenshot in caso di modifiche all'interfaccia.
  • Una PR che modifica qualsiasi elemento visibile nel launcher deve allegare gli screenshot "prima" e "dopo" nella sezione Screenshots della PR stessa. Mostra ogni schermata toccata dalla PR in ciascuna delle lingue coinvolte. Una PR priva di screenshot non viene sottoposta a revisione. Se una PR non comporta alcuna modifica visibile, scrivi "None, no visible change".
  • Ogni correzione di bug deve essere accompagnata da un test specifico. Il test deve fallire senza la correzione e passare con la correzione applicata. Quando un bug non può essere coperto da un test automatico (perché richiede un dispositivo fisico, iCloud, un gioco reale o hardware specifico), la PR deve spiegarne il motivo nella sezione Checked. Una patch al motore segue la stessa regola quando il motore dispone di una suite di test per quell'area (dm/host/tests), altrimenti va specificato.
  • frontend/ e frontend-qt/ appartengono direttamente a questo fork: puoi modificarli liberamente. Esegui cd frontend && swift test. Per una modifica all'interfaccia cattura anche le viste per la verifica visiva (NX_LAUNCHER_CAPTURE_DIR, vedi frontend/README.md).
  • Il motore non risiede direttamente in questo repository. Le cartelle dm/, scripts/, docs/ e ref/ corrispondono a seedds/nxnative al commit indicato in .upstream-ref con l'applicazione delle patch presenti in patches/, assemblate dentro engine/ tramite python3 tools/engine.py sync (un repository git ignorato dal repository principale, #214). Una PR che aggiunge file direttamente sotto quei percorsi non supera il controllo pr-scope, poiché la sincronizzazione successiva non li conserverebbe. Una correzione al motore o a un profilo di gioco entra prima qui sotto forma di patch e viene inviata in parallelo a seedds/nxnative come pull request, come illustrato in patches/README.md. Se non puoi aprire la pull request upstream, lo farà un manutentore. Per creare la patch, effettua il commit della modifica dentro engine/, esegui python3 tools/engine.py export, compila l'intestazione della nuova patch (Upstream-Status, Reason, Issue), verifica il tutto con python3 tools/engine.py check e infine includi patches/ nel tuo commit. Quella pagina illustra tutti i passaggi e definisce la politica sulle patch (cosa una patch può o non può modificare). Tutto il resto nella radice del repository e dentro .github/ (questo file, CLAUDE.md, AGENTS.md, i file README) appartiene a questo fork.

Correzioni, nuove funzionalità e idee

Questa sezione riguarda i contributi esterni. I manutentori (v0lumehi e LNPANDY) seguono le regole descritte più avanti in "Quando una PR viene unita".

Vogliamo aiutarti a realizzare contributi che si integrino al meglio ed evitarti lavoro che non potrebbe essere accettato. Il codice del launcher è in fase di riorganizzazione, perciò molte PR aperte richiederanno un rebase, ed è molto più semplice integrare una modifica quando ci si accorda sul design prima ancora di scrivere il codice. Per questo motivo le nuove funzionalità e le proposte vanno sempre discusse in anticipo. Le correzioni di bug restano invece sempre benvenute senza bisogno di chiedere prima.

  • Una correzione (fix) è sempre benvenuta direttamente come PR senza chiedere prima. I test che coprono una correzione, i refusi e i miglioramenti o le traduzioni nella documentazione contano come correzioni. La segnalazione di un gioco funzionante resta invece una segnalazione (una issue o una voce in GAMES.it.md / GAMES.md), non una nuova funzionalità.
  • Tutto ciò che non è una correzione è una funzionalità o una proposta, e va discusso prima. Questo include nuove funzionalità, modifiche al funzionamento o all'aspetto del launcher, nuove impostazioni, nuove dipendenze, nuovi metodi di compilazione o installazione, refactoring o nuove pagine di documentazione. Apri una issue usando il modulo "Launcher problem or idea" (This is: An idea) oppure proponi un'idea in Discussions (Ideas). La discussione si conclude quando un manutentore approva l'idea e inserisce la issue in una milestone. Una issue inserita in una milestone rappresenta il via libera. A quel punto puoi svilupparla e collegare la issue nella tua PR. Una PR per una nuova funzionalità priva di una issue collegata in una milestone non viene revisionata: viene chiusa con una nota cordiale dopo 14 giorni e potrà essere riaperta non appena ci sarà il via libera. Una PR in bozza (draft) come schizzo iniziale va bene, ma attende comunque il via libera come qualsiasi altra. Per una modifica che tocca più front-end o l'architettura generale, la issue deve contenere anche una breve nota progettuale: cosa intendi cambiare, perché e quali alternative hai valutato.

Se hai dubbi sul fatto che una modifica sia considerata una semplice correzione, chiedi pure aprendo una issue. Decideranno i manutentori.

Il profilo di un nuovo gioco o una correzione al motore vanno inviati prima a seedds/nxnative, come spiegato in "Aiutare con i giochi".

Le PR aperte prima dell'introduzione di questa regola seguono il vecchio percorso: apertura di una issue entro 48 ore dalla prima risposta di un manutentore e approvazione dell'idea da parte di almeno un manutentore prima dell'unione (merge) della PR.

Dove ci farebbe piacere ricevere aiuto

Le milestone rappresentano il piano di lavoro e chiunque può prendere in carico qualsiasi issue aperta al loro interno che non sia già stata assegnata. Una issue presente in una milestone ha già il via libera.

  • Per prenderne in carico una, lascia un commento indicando che intendi lavorarci. Un manutentore te la assegnerà in modo che due persone non lavorino contemporaneamente alla stessa cosa. Collega poi la issue nella tua PR.
  • Parti sempre dal problema e non dalla soluzione. Spiega cosa vorresti ottenere e quale ostacolo incontri, proprio come richiesto dal modulo. I manutentori potrebbero indicarti un approccio già pianificato per risolverlo.
  • Se un manutentore ritiene che un'idea non possa essere accolta, lo comunicherà tempestivamente spiegandone il motivo, come descritto in Cosa succede alla tua PR.

Cosa succede alla tua PR

Una pull request proveniente dall'esterno non viene mai unita automaticamente. Un manutentore prova l'app compilata dalla CI per quella PR, ovvero l'artefatto NX2Apple-macOS-arm64 generato dal workflow Build Mac app. Lo stesso manutentore esamina il codice. Chi la prende in esame per primo decide.

Se i manutentori ritengono di non voler integrare una modifica, lo comunicano subito spiegando il perché e chiudono la PR. Possono eventualmente conservarne alcune parti inserendoti come co-autore.

Una PR che resta in attesa di risposta da parte del suo autore per 30 giorni viene chiusa con una nota che ricorda la possibilità di riaprirla.

Quando una PR viene unita

Queste regole valgono per ogni PR. Una PR proveniente dall'esterno richiede inoltre la verifica del manutentore descritta sopra e non viene mai unita prima di tale controllo.

Ogni correzione passa attraverso una PR. Una correzione viene unita quando la CI è verde, senza necessità di ulteriori approvazioni formali.

Una revisione aperta con richiesta di modifiche ("changes requested") da parte di un manutentore blocca l'unione. Un semplice commento di revisione non la blocca. Il manutentore che ha richiesto le modifiche esamina nuovamente la PR una volta inviate le correzioni e approva o ritira la richiesta. Ciascun manutentore risolve le proprie obiezioni. Se i due manutentori sono in disaccordo su un'obiezione, la decisione finale spetta ad Andy (@LNPANDY).

Una nuova funzionalità sviluppata dai manutentori (v0lumehi e LNPANDY) viene unita dopo 48 ore. Una funzionalità proveniente dall'esterno non viene mai unita per semplice scadenza dei tempi, ma solo dopo che un manutentore ha approvato l'idea, provato l'app ed esaminato il codice.

Una patch in patches/ riceve il primo numero libero disponibile in patches/series su main al momento dell'unione. Chi effettua il merge rinumera la patch e lo annota nella PR, quindi non hai bisogno di fare rebase continui per inseguire i numeri liberi.

CI su stack di PR

I manutentori lavorano spesso per stack: una PR per ogni passo, ciascuna basata sul branch di testa di quella sottostante, mantenendo una PR distinta per la tracciabilità. GitHub mette a disposizione 5 runner macOS per l'intero account, perciò i controlli più pesanti vengono eseguiti una sola volta sulla cima dello stack (la PR su cui non si basa nessun'altra PR aperta).

  • Cosa gira e dove. Ogni PR esegue i controlli rapidi (Patch queue, Qt front end, Triage script tests, Changed areas). I job che richiedono un runner macOS (Mac launcher con swift test, Tool tests e i job del motore) girano sulla cima dello stack. La compilazione dell'app (Build the NX2Apple app (macOS)) gira sulla cima solo quando la PR modifica un file che rientra nel pacchetto finale (elencati in .github/scripts/build_wanted.py) oppure ha l'etichetta full-build. Un push su main, un tag e un avvio manuale eseguono sempre tutti i controlli. I file modificati vengono calcolati rispetto a main, per cui la cima dello stack tiene conto anche di tutte le PR sottostanti.
  • Perché una PR inferiore mostra "skipped". Il suo job Stack ha rilevato una PR aperta sopra di essa e ha saltato i job pesanti. Il riepilogo del job riporta Not the tip of a stack: heavy checks run on #N. Un job saltato conta come superato per i controlli obbligatori, consentendo comunque l'unione della PR. I controlli vengono saltati a livello di singolo job e mai di intero workflow, poiché un workflow che non parte non invia alcun risultato e bloccherebbe il merge.
  • Quando una PR diventa la cima dello stack. Se la PR figlia viene chiusa, unita o spostata di base, il workflow Stack parent re-run riesegue il job Stack delle ultime esecuzioni della PR padre, avviando i job pesanti. Se una PR padre risulta ancora saltata (perché la sua esecuzione era ancora in corso quando la PR figlia è stata chiusa), apri l'esecuzione e premi "Re-run all jobs" oppure esegui gh run rerun <run id> --job <id del job Stack>. Una PR figlia che viene aperta o riaperta in seguito rivaluta la PR padre nello stesso modo, facendo saltare i job pesanti della PR padre. Nulla viene annullato in corsa: se l'esecuzione della PR padre è già avviata, i suoi job pesanti continuano fino al termine. Riesegui manualmente il suo job Stack una volta terminata l'esecuzione, oppure apri le PR figlie partendo dalla cima.
  • Forzare un'esecuzione. Aggiungi l'etichetta full-build, quindi riesegui Build the NX2Apple app (macOS) (l'etichetta viene letta quando parte il job, non quando parte la run). In alternativa avvia il workflow manualmente con gh workflow run build-mac-app.yml --ref <branch>. Un'esecuzione manuale viene sempre trattata come cima dello stack.
  • Unire uno stack tramite la PR in cima. Usa l'API asincrona sulla PR in cima, che unirà automaticamente anche le PR sottostanti: gh api -X PUT repos/LNPANDY/NX2Apple/pulls/<n>/merge-async -f merge_method=merge -f merge_action=direct_merge. I controlli obbligatori di ogni PR dello stack devono aver riportato l'esito, requisito soddisfatto anche dai job pesanti saltati.
  • Se la ricerca fallisce (ad esempio per un disservizio delle API di GitHub), la PR viene considerata come cima dello stack e la CI viene eseguita per intero. Un errore di ricerca non salta mai un controllo.

Per gli agenti IA e altri strumenti automatici

I moduli delle issue e il template delle PR funzionano automaticamente solo nel browser. gh issue create, le API e gli strumenti MCP saltano i moduli, perciò devono seguirne la struttura manualmente:

  • Segnalazioni di problemi. Scrivi il corpo del testo usando intestazioni ### con gli stessi nomi dei campi del modulo (ad esempio ### Game and title ID, ### Copy diagnostics, ### The game's log) e compila tutti i campi obbligatori definiti in .github/ISSUE_TEMPLATE. Chiedi all'utente i dati che non puoi leggere autonomamente: l'output di Copia diagnostica, il log e le versioni. Se manca un campo obbligatorio, non aprire la issue.
  • Idee e piani. Non hanno un modulo fisso. Scrivi sezioni chiare e adatte al contenuto, ad esempio ### Idea, ### Plan e ### Done when. Ometti i campi specifici dei bug (This is, NX2Apple version, Computer and OS, Copy diagnostics). Apri la issue con le etichette idea e no-triage.
  • Prima di scrivere codice. Se operi per conto di un collaboratore esterno, una nuova funzionalità o una proposta richiede una issue inserita in una milestone (vedi "Correzioni, nuove funzionalità e idee"). Verifica che esista o chiedi all'utente. Il profilo di un nuovo gioco o una correzione al motore vanno inviati prima a seedds/nxnative (vedi "Aiutare con i giochi").
  • Pull request. Usa le sezioni di .github/pull_request_template.md: esegui gh pr create --template .github/pull_request_template.md oppure riporta le medesime intestazioni in --body. Compila ogni sezione e rimuovi i suggerimenti racchiusi tra <!-- -->. Sotto Fix or feature, spunta una sola casella. Una funzionalità esterna deve collegare la issue che ha ricevuto il via libera. Una modifica al motore segue la regola descritta più sopra.
  • Test per una correzione. Aggiungi un test specifico per il bug insieme alla correzione. Consulta "Aprire una pull request" per i casi in cui non è possibile scrivere un test automatico.
  • Screenshot. Una PR che modifica il launcher necessita di immagini "prima" e "dopo" nel corpo della descrizione (vedi "Aprire una pull request"). Su Mac, cattura le viste modificate di frontend/ con NX_LAUNCHER_CAPTURE_DIR=<cartella> swift test e usa NX_CAPTURE_LANG per selezionare la lingua (de, sv o zh, mentre l'inglese è predefinito). frontend-qt/ non dispone di cattura automatica, quindi acquisisci gli screenshot manualmente. Allega le immagini con gh pr create --attach o gh pr edit --attach, una volta per file. Scrivi ![before](./before.png) nel corpo e passa --attach ./before.png. gh caricherà il file e riscriverà il percorso in un URL https://github.com/user-attachments/assets/.... Ciò richiede gh 2.99.0 o successivo, accesso di push al repository e un token OAuth o Personal Access Token (i token di GitHub App vengono rifiutati). Al termine, rileggi il corpo della PR per verificare che contenga gli URL degli asset e nessun percorso locale. Se la tua versione di gh o il tuo token non permettono di allegare file, indicalo nella sezione Screenshots fornendo i percorsi delle immagini catturate e chiedendo all'utente di allegarle. Un agente che non gira su Mac (ad esempio un runner Linux) deve dichiarare nella sezione Screenshots di non aver potuto catturare le viste e richiedere l'aggiunta degli screenshot nella PR.
  • Note di rilascio. Seguono il modello .github/release_notes_template.md, prima in inglese e poi in cinese, senza emoji.
  • Non allegare né includere mai nei commit chiavi, file di gioco o dati estratti da un gioco, e non incollare mai valori di chiavi all'interno di un log o di un report diagnostico.