Come aggiornare le versioni di Godot in sicurezza

Introduzione

Aggiornare il motore di gioco a metà progetto è una delle decisioni di routine più spaventose nello sviluppo di videogiochi. Una nuova versione di Godot potrebbe correggere il bug che ti sta bloccando — oppure potrebbe rompere silenziosamente una scena in cui hai investito sei mesi di lavoro. Ecco perché gli sviluppatori esperti della community di Godot trattano un aggiornamento di versione come una decisione di rischio, non come una faccenda di routine.

Questa guida non è un'apologia dell'"aggiornare sempre". È una checklist di gestione del rischio per la migrazione tra versioni 4.x di Godot: come decidere se aggiornare davvero, come prepararsi in modo da poter tornare indietro in sicurezza, cosa è noto rompersi tra le versioni e — soprattutto — come verificare concretamente che nulla si sia rotto.

Dovresti davvero aggiornare?

Prima di toccare qualsiasi cosa, rispondi onestamente a questa domanda. Aggiornare ha un costo reale (lavoro di migrazione + nuovi test), quindi il beneficio deve essere altrettanto reale.

Aggiorna se…

• Un bug già corretto upstream ti sta bloccando. Se il tuo problema è già risolto in una release più recente, aggiornare di solito costa meno che continuare ad aggirarlo per sempre.
• Una nuova funzionalità porta un beneficio concreto al tuo gioco. Non un "sembra carina" — qualcosa che ti fa risparmiare tempo di sviluppo reale o sblocca un design di cui hai bisogno.
• Il tuo piano di sviluppo è lungo. Se il progetto richiederà anni, tanti piccoli salti frequenti (una versione minor alla volta) sono molto più sicuri di un unico salto gigante alla fine. Il divario non fa che crescere.

Non aggiornare se…

• Sei vicino al rilascio. Le settimane prima della pubblicazione sono il momento peggiore in assoluto per introdurre cambiamenti a livello di motore. Prima pubblica, poi aggiorna.
• Ti serve C# + export Web. L'export Web per i progetti C# non è ancora disponibile in Godot 4.x (tracciato in godot#70796). Se in 3.x ci fai affidamento, passare a 4.x te lo toglie.
• Il tuo target è hardware datato. Godot 3.x gira su GPU di classe OpenGL 2; il renderer Compatibility di Godot 4 richiede OpenGL 3.3 / WebGL 2. Se il tuo pubblico usa macchine vecchie, 3.x può davvero essere il motore giusto.
• Gli addon critici non sono ancora aggiornati. Se un plugin da cui il progetto dipende non supporta la nuova versione, erediti il suo problema di migrazione in aggiunta al tuo.

Prima di aggiornare — Checklist di preparazione

Ogni passo di questa lista esiste perché, se l'aggiornamento va storto, tu perda un pomeriggio, non un progetto.

1. Committa tutto e crea un branch dedicato all'aggiornamento. Non aggiornare mai l'unica copia del tuo progetto. Un branch dedicato (o una copia completa della cartella se non usi git) significa che il ripristino è un solo comando, non una missione di recupero.
2. Annota la versione esatta attuale (es. quale build 4.x.y, standard o .NET). Ti servirà se devi tornare indietro o segnalare un bug.
3. Conserva il binario del vecchio editor. Le versioni di Godot si installano fianco a fianco — l'editor è un singolo eseguibile, quindi tenerli entrambi non costa nulla e ti permette di aprire il vecchio branch con il vecchio editor in qualsiasi momento.
4. Elenca i tuoi addon e verifica le versioni supportate di ciascuno. Scorri addons/, annota da dove proviene ogni addon e conferma sul suo repository o sulla pagina dell'Asset Library che supporti la versione di destinazione.
5. Leggi le note ufficiali di aggiornamento di ogni versione che attraversi. Le guide ufficiali di migrazione sono scritte per singola versione — se passi da 4.2 a 4.4, leggi sia le note della 4.3 che quelle della 4.4.
6. Cattura prove dello "stato funzionante". Fai screenshot delle tue scene principali, registra una breve clip di gameplay oppure — la scelta migliore — scrivi scenari di test automatizzati (ne parliamo nella sezione sui test più avanti). Dopo l'aggiornamento, alla domanda "l'aspetto e il comportamento sono gli stessi?" si può rispondere solo se hai registrato prima cosa significa "gli stessi".

La procedura di aggiornamento

1. Apri la copia del branch con il nuovo editor. Il branch di aggiornamento, non main. Il nuovo editor proporrà di convertire/reimportare — accetta.
2. Lascia che reimporti. La cartella .godot viene rigenerata da zero. Il primo import può richiedere tempo sui progetti grandi, e gli avvisi stampati durante quel primo passaggio sono di solito innocui.
3. Controlla i pannelli Output e Debugger alla ricerca di errori nuovi. Confrontali con gli errori che avevi già prima (li avevi annotati, vero?). Gli errori nuovi sono la to-do list della migrazione.
4. Gioca i percorsi critici. Avvia una nuova partita, carica un salvataggio, esegui il gameplay loop principale, apri i menu principali. Gli errori in fase di editor sono quelli facili — è nel comportamento a runtime che si nascondono le regressioni.
5. Esegui i tuoi scenari di test (quelli preparati prima di aggiornare) e confrontali con la baseline.
6. Esamina il diff del working tree in git prima di committare. Durante la migrazione l'editor riscrive i file: project.godot riceve nuovi valori di configurazione, i file .tscn vengono risalvati e possono comparire nuovi file .uid. Rivedi il diff così sai esattamente cosa è cambiato — poi committa il tutto come un singolo commit di migrazione etichettato chiaramente.

Punti di rottura noti tra le versioni 4.x

Le versioni minor di Godot 4 sono in gran parte compatibili, ma quel "in gran parte" nasconde delle insidie. Ecco i cambiamenti che più probabilmente ti colpiranno, sulla base delle note ufficiali e delle segnalazioni della community.

4.2 → 4.3: TileMap deprecato in favore di TileMapLayer

Godot 4.3 ha deprecato il nodo TileMap in favore di TileMapLayer — un nodo per livello invece di livelli dentro un unico nodo. I TileMap esistenti continuano a funzionare, ma il nuovo codice e i nuovi progetti dovrebbero usare TileMapLayer. L'editor include uno strumento di estrazione: seleziona il tuo TileMap, apri il pannello inferiore TileMap, clicca sull'icona della cassetta degli attrezzi nell'angolo in alto a destra e scegli "Extract TileMap layers as individual TileMapLayer nodes".

4.3 → 4.4: file .uid e novità di GDScript

• Godot 4.4 ha introdotto i file companion .uid accanto a script e shader. Committali nel controllo di versione — eliminarli può rompere i riferimenti uid:// ovunque siano usati (le note ufficiali di aggiornamento della 4.4 coprono cambiamenti correlati, come i percorsi di @export_file che diventano uid://). Sembrano spazzatura; non lo sono.
• I Dictionary tipizzati e le altre aggiunte a GDScript sono retrocompatibili — il tuo vecchio codice continua a girare. Ma gli addon che adottano le nuove funzionalità smettono di funzionare sulle versioni più vecchie, quindi il comportamento degli addon può cambiare nel passaggio.

In generale: cambiamenti sottili tra qualunque coppia di versioni minor

Le modifiche al rendering tra versioni minor possono cambiare in modo sottile l'aspetto del tuo gioco — illuminazione, anti-aliasing, snapping 2D. Le discussioni della community includono anche regressioni specifiche di una scena che non si riproducono in progetti nuovi: una scena si comporta male dopo l'aggiornamento, ma ricostruendo la stessa scena in un progetto pulito tutto funziona. Se qualcosa si rompe in modo inspiegabile, prova questa sequenza di isolamento: chiudi l'editor, elimina la cartella .godot, riapri e lascia reimportare tutto; se il problema persiste, riproduci la scena in un progetto pulito per capire se il colpevole è lo stato accumulato del tuo progetto o un vero cambiamento del motore.

3.x → 4.x è tutta un'altra storia

Tutto quanto sopra riguarda i passaggi tra versioni 4.x. Migrare da Godot 3 a Godot 4 è una categoria completamente diversa: la sintassi di GDScript è cambiata, molti nodi sono stati rinominati, e TileMap, fisica e rendering sono stati rifatti da zero — e la maggior parte degli addon richiede versioni dedicate per 4.x. Per i grandi progetti in 3.x, il costo della migrazione può avvicinarsi a quello di una ricostruzione, e se ne valga la pena è una decisione davvero legata al singolo progetto. Quella migrazione merita (e ha) una documentazione dedicata; questo articolo non pretende di coprirla.

Testare dopo l'aggiornamento — il vero collo di bottiglia

Ecco la parte onesta: il motivo numero uno per cui gli sviluppatori evitano di aggiornare non è la migrazione in sé — è che verificare a mano che "nulla si sia rotto" costa caro. Un passaggio completo di regressione manuale su un gioco di medie dimensioni può divorare un weekend. E un bug a runtime che i tuoi giocatori trovano dopo il rilascio è molto peggio di qualsiasi errore in editor, perché a quel punto è un problema di reputazione, non una voce di una to-do list.

Smoke test manuale minimo

• Avvia una nuova partita dalla schermata del titolo
• Carica un file di salvataggio esistente
• Gioca il gameplay loop principale per qualche minuto
• Controlla la UI a ogni risoluzione e modalità finestra che supporti

Automatizza il confronto prima/dopo

Il passaggio manuale non scala, e non può dirti che uno sprite si è spostato di due pixel. È esattamente per questo che è nato Godot QA — un test runner per Godot gratuito, open source e con licenza MIT. Il suo flusso di lavoro si sposa perfettamente con gli aggiornamenti di versione:

1. Prima di aggiornare, scrivi (o registra) file JSON di scenario che coprano i tuoi percorsi critici e cattura gli screenshot di baseline sulla vecchia versione.
2. Dopo l'aggiornamento, esegui esattamente gli stessi scenari più un pixel-diff rispetto alle baseline sulla nuova versione.
3. I fallimenti individuano le regressioni in pochi minuti invece che in un weekend di riprove manuali.

Uno scenario è semplicemente una lista JSON di passi — input, attese, asserzioni, screenshot:

{
  "name": "core_loop_smoke",
  "steps": [
    {"type": "wait", "seconds": 1.0},
    {"type": "input", "action": "ui_accept", "pressed": true},
    {"type": "wait", "seconds": 0.5},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "health", "expected": 100, "operator": "eq"},
    {"type": "input", "action": "move_right", "pressed": true},
    {"type": "wait", "seconds": 2.0},
    {"type": "input", "action": "move_right", "pressed": false},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "position:x", "expected": 100.0, "operator": "gt"},
    {"type": "screenshot", "name": "after_move"}
  ]
}

Lo stesso formato di scenario è quello usato dallo strumento run_test_scenario di Godot MCP Pro, quindi un assistente IA collegato al tuo editor può scrivere questi scenari al posto tuo.

Se qualcosa si rompe

1. Fai una bisezione per versione. Se hai saltato più versioni minor in un colpo solo, riprova l'aggiornamento una versione minor alla volta per trovare esattamente dove si è rotto. Questo restringe la ricerca da "tutto" a un solo changelog.
2. Svuota la cartella .godot e lascia che il progetto reimporti. Le cache di import obsolete causano una quota sorprendente delle stranezze post-aggiornamento.
3. Cerca il tuo esatto messaggio di errore nelle issue GitHub del motore. Se è una vera regressione, spesso qualcuno l'ha già segnalata — a volte con un workaround.
4. Verifica se il colpevole è un addon. Disattiva i tuoi addon nelle Impostazioni progetto e riprova. Se il problema scompare, è l'addon — controlla se esiste una release aggiornata prima di incolpare il motore.
5. Accetta che restare sulla vecchia versione è un esito valido. Se il costo della correzione supera il beneficio dell'aggiornamento, ripristina il branch, resta dove sei e imposta un promemoria per riprovare alla prossima release. Non è un fallimento — è la gestione del rischio che funziona.

Quando restare fermi è la scelta giusta

Alcuni progetti semplicemente non dovrebbero aggiornare, e vale la pena dirlo chiaramente: giochi pubblicati o quasi pronti alla pubblicazione, progetti C# che necessitano dell'export web, giochi destinati a hardware datato e progetti su build custom del motore pesantemente modificate. In tutti questi casi, la versione su cui sei sta facendo il suo lavoro. Aggiornare è uno strumento, non una virtù — l'obiettivo è un gioco finito, non un motore nuovo di zecca.

FAQ

Posso fare il downgrade dopo aver aggiornato?

No, non in modo affidabile. Una volta che il nuovo editor risalva le tue scene e risorse, queste non sono più retrocompatibili con gli editor più vecchi. L'unico modo sicuro per tornare indietro è il ripristino dal controllo di versione — ed è esattamente per questo che esiste il branch di aggiornamento.

Posso saltare più versioni in un colpo solo?

I piccoli salti sono più sicuri. Le note ufficiali di aggiornamento sono scritte per singola versione, quindi ogni salto ha una checklist nota — un salto multi-versione le accumula tutte insieme e rende più difficile capire quale cambiamento ha rotto cosa.

Le versioni minor rompono davvero qualcosa?

Raramente, ma sì. La maggior parte dei progetti passa le versioni minor senza problemi, ma esistono casi limite segnalati dalla community — bit di collisione che si resettano, regressioni di rendering specifiche di una scena. È proprio per questo che i test di baseline prima dell'aggiornamento sono importanti: trasformano "si è rotto qualcosa?" da una sensazione a una misurazione.

Questa checklist vale anche per 3.x → 4.x?

La checklist in sé, sì — branch, conserva il vecchio binario, cattura le baseline, testa dopo. La lista dei punti di rottura, no: la migrazione da 3 a 4 è molto più grande (sintassi GDScript, nodi rinominati, sistemi rifatti) e ha una documentazione ufficiale dedicata.