Comment mettre à jour Godot en toute sécurité

Introduction

Mettre à jour son moteur de jeu en plein milieu d'un projet est l'une des décisions de routine les plus effrayantes du développement de jeux. Une nouvelle version de Godot corrige peut-être le bug qui te bloque — ou elle peut casser silencieusement une scène dans laquelle tu as investi six mois de travail. C'est pourquoi les développeurs expérimentés de la communauté Godot traitent une mise à jour de version comme une décision de risque, pas comme une corvée de routine.

Ce guide n'est pas un plaidoyer du type « mets toujours à jour ». C'est une check-list de gestion des risques pour la migration de 4.x vers 4.x : comment décider s'il faut mettre à jour tout court, comment se préparer pour pouvoir revenir en arrière sans danger, ce qui est connu pour casser entre les versions, et — le plus important — comment vérifier concrètement que rien n'a cassé.

Faut-il vraiment mettre à jour ?

Avant de toucher à quoi que ce soit, réponds honnêtement à cette question. Une mise à jour a un coût réel (travail de migration + re-tests), donc le bénéfice doit être tout aussi réel.

Mets à jour si…

• Un bug corrigé en amont te bloque. Si ton problème est déjà résolu dans une version plus récente, mettre à jour coûte généralement moins cher que de le contourner indéfiniment.
• Une nouvelle fonctionnalité apporte un bénéfice concret à ton jeu. Pas « ça a l'air sympa » — quelque chose qui te fait gagner du vrai temps de développement ou qui débloque un design dont tu as besoin.
• Ton calendrier de développement est long. Si ton projet va prendre des années, de petits sauts fréquents (une version mineure à la fois) sont bien plus sûrs qu'un saut géant à la fin. L'écart ne fait que grandir.

Ne mets pas à jour si…

• Tu es proche de la sortie. Les semaines qui précèdent la publication sont le pire moment possible pour introduire des changements au niveau du moteur. Publie d'abord, mets à jour ensuite.
• Tu as besoin de C# + export Web. L'export Web des projets C# n'est toujours pas disponible dans Godot 4.x (suivi dans godot#70796). Si tu en dépends en 3.x, passer en 4.x te le retire.
• Tu cibles du vieux matériel. Godot 3.x tourne sur des GPU de classe OpenGL 2 ; le moteur de rendu Compatibility de Godot 4 exige OpenGL 3.3 / WebGL 2. Si ton public utilise de vieilles machines, la 3.x peut sincèrement être le bon moteur.
• Des addons critiques ne sont pas encore à jour. Si un plugin dont dépend ton projet ne prend pas en charge la nouvelle version, tu hérites de son problème de migration en plus du tien.

Avant la mise à jour — check-list de préparation

Chaque étape de cette liste existe pour que, si la mise à jour tourne mal, tu perdes un après-midi, pas un projet.

1. Commit tout et crée une branche de mise à jour. Ne mets jamais à jour la seule copie de ton projet. Une branche dédiée (ou une copie complète du dossier si tu n'utilises pas git) signifie que revenir en arrière est une seule commande, pas une mission de sauvetage.
2. Note ta version exacte actuelle (par exemple quel build 4.x.y, standard ou .NET). Tu en auras besoin si tu dois revenir en arrière ou signaler un bug.
3. Garde l'ancien binaire de l'éditeur. Les versions de Godot s'installent côte à côte — l'éditeur est un simple exécutable, donc garder les deux ne coûte rien et te permet d'ouvrir à tout moment l'ancienne branche avec l'ancien éditeur.
4. Liste tes addons et vérifie les versions prises en charge par chacun. Parcours addons/, note la provenance de chacun, et confirme sur son dépôt ou sa page de l'Asset Library qu'il prend en charge la version cible.
5. Lis les notes de mise à jour officielles de chaque version que tu traverses. Les guides de migration officiels sont rédigés version par version — si tu passes de 4.2 à 4.4, lis les notes de la 4.3 et de la 4.4.
6. Capture des preuves de l'état « connu bon ». Prends des captures d'écran de tes scènes clés, enregistre un court clip de gameplay, ou — le mieux — écris des scénarios de test automatisés (on y revient dans la section sur les tests ci-dessous). Après la mise à jour, la question « est-ce que ça a le même aspect et le même comportement ? » n'a de réponse que si tu as capturé au préalable ce que « même » signifie.

La procédure de mise à jour

1. Ouvre la copie de la branche avec le nouvel éditeur. La branche de mise à jour, pas main. Le nouvel éditeur proposera de convertir/réimporter — accepte.
2. Laisse-le réimporter. Le dossier .godot se régénère de zéro. Le premier import peut prendre du temps sur les gros projets, et les avertissements affichés pendant cette première passe sont généralement inoffensifs.
3. Vérifie les nouvelles erreurs dans les panneaux Output et Debugger. Compare avec les erreurs que tu avais déjà avant (tu les avais notées, n'est-ce pas ?). Les nouvelles erreurs constituent la liste de tâches de la migration.
4. Joue les parcours critiques. Lance une nouvelle partie, charge une sauvegarde, exécute la boucle de gameplay principale, ouvre les menus principaux. Les erreurs au moment de l'édition sont les plus faciles — c'est dans le comportement à l'exécution que se cachent les régressions.
5. Exécute tes scénarios de test (ceux que tu as préparés avant la mise à jour) et compare avec la référence.
6. Examine le diff de l'arbre de travail dans git avant de commiter. L'éditeur réécrit des fichiers pendant la migration : project.godot reçoit de nouvelles valeurs de configuration, les fichiers .tscn sont réenregistrés, et de nouveaux fichiers .uid peuvent apparaître. Passe le diff en revue pour savoir exactement ce qui a changé — puis commit le tout en un seul commit de migration clairement étiqueté.

Points de rupture connus entre versions 4.x

Les versions mineures de Godot 4 sont pour l'essentiel compatibles, mais ce « pour l'essentiel » cache quelques pièges. Voici les changements les plus susceptibles de mordre, d'après les notes officielles et les rapports de la communauté.

4.2 → 4.3 : TileMap déprécié au profit de TileMapLayer

Godot 4.3 a déprécié le nœud TileMap au profit de TileMapLayer — un nœud par calque au lieu de calques à l'intérieur d'un seul nœud. Les TileMaps existantes continuent de fonctionner, mais le nouveau code et les nouveaux projets devraient utiliser TileMapLayer. L'éditeur inclut un outil d'extraction : sélectionne ta TileMap, ouvre le panneau TileMap du bas, clique sur l'icône boîte à outils en haut à droite et choisis « Extract TileMap layers as individual TileMapLayer nodes ».

4.3 → 4.4 : fichiers .uid et ajouts GDScript

• Godot 4.4 a ajouté des fichiers compagnons .uid à côté des scripts et des shaders. Commit-les dans le contrôle de version — les supprimer peut casser les références uid:// partout où elles sont utilisées (les notes de mise à jour officielles de la 4.4 couvrent les changements associés, comme les chemins @export_file qui deviennent uid://). Ils ressemblent à des fichiers parasites ; ils n'en sont pas.
• Les Dictionaries typés et les autres ajouts de GDScript sont rétrocompatibles — ton ancien code continue de tourner. Mais les addons qui adoptent les nouvelles fonctionnalités cessent de fonctionner sur les versions plus anciennes, donc le comportement des addons peut différer d'un côté à l'autre du saut.

En général : des changements subtils entre n'importe quelles versions mineures

Les ajustements de rendu entre versions mineures peuvent changer subtilement l'apparence de ton jeu — éclairage, anticrénelage, snapping 2D. Les discussions de la communauté mentionnent aussi des régressions propres à certaines scènes, qui ne se reproduisent pas dans des projets vierges : une scène se comporte mal après la mise à jour, mais reconstruire la même scène dans un projet propre fonctionne parfaitement. Si quelque chose casse de façon inexplicable, essaie cette séquence d'isolation : ferme l'éditeur, supprime le dossier .godot, rouvre et laisse tout se réimporter ; si le problème persiste, reproduis la scène dans un projet propre pour déterminer si le coupable est l'état accumulé de ton projet ou un véritable changement du moteur.

3.x → 4.x, c'est une tout autre histoire

Tout ce qui précède concerne les sauts de 4.x vers 4.x. Migrer de Godot 3 vers Godot 4 est une catégorie entièrement différente : la syntaxe GDScript a changé, de nombreux nœuds ont été renommés, et TileMap, la physique et le rendu ont été refaits de fond en comble — et la plupart des addons nécessitent des versions dédiées 4.x. Pour les gros projets 3.x, le coût de migration peut approcher celui d'une reconstruction, et savoir si ça en vaut la peine est une décision réellement propre à chaque projet. Cette migration mérite (et possède) sa propre documentation ; cet article ne prétendra pas la couvrir.

Tester après la mise à jour — le vrai goulot d'étranglement

Soyons honnêtes : la raison numéro un pour laquelle les développeurs évitent de mettre à jour n'est pas la migration elle-même — c'est que vérifier à la main que « rien n'a cassé » coûte cher. Une passe de régression manuelle complète sur un jeu de taille moyenne peut engloutir un week-end. Et un bug à l'exécution que tes joueurs découvrent après la sortie est bien pire que n'importe quelle erreur d'éditeur, parce que c'est désormais un problème de réputation, pas un élément de liste de tâches.

Test de fumée manuel minimal

• Lancer une nouvelle partie depuis l'écran titre
• Charger un fichier de sauvegarde existant
• Jouer la boucle de gameplay principale pendant quelques minutes
• Vérifier l'UI dans chaque résolution et mode de fenêtre que tu prends en charge

Automatiser la comparaison avant/après

La passe manuelle ne passe pas à l'échelle, et elle ne peut pas te dire qu'un sprite s'est décalé de deux pixels. C'est exactement pour cela que Godot QA a été créé — un lanceur de tests pour Godot gratuit, open source et sous licence MIT. Son flux de travail s'accorde parfaitement avec les mises à jour de version :

1. Avant la mise à jour, écris (ou enregistre) des fichiers JSON de scénario couvrant tes parcours critiques, et capture des captures d'écran de référence sur l'ancienne version.
2. Après la mise à jour, exécute exactement les mêmes scénarios plus un diff pixel par pixel avec les références, sur la nouvelle version.
3. Les échecs localisent les régressions en quelques minutes au lieu d'un week-end de rejeu manuel.

Un scénario n'est qu'une liste JSON d'étapes — entrées, attentes, assertions, captures d'écran :

{
  "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"}
  ]
}

Ce format de scénario est le même que celui utilisé par l'outil run_test_scenario de Godot MCP Pro, donc un assistant IA connecté à ton éditeur peut écrire ces scénarios pour toi.

Si quelque chose casse

1. Bissecte par version. Si tu as sauté plusieurs versions mineures d'un coup, retente la mise à jour une version mineure à la fois pour trouver exactement où ça a cassé. Cela réduit la recherche de « tout » à un seul changelog.
2. Vide le dossier .godot et laisse le projet se réimporter. Les caches d'import périmés causent une part étonnante des bizarreries post-mise à jour.
3. Cherche ton message d'erreur exact dans les issues GitHub du moteur. S'il s'agit d'une vraie régression, quelqu'un l'a souvent déjà signalée — parfois avec une solution de contournement.
4. Vérifie si un addon est le coupable. Désactive tes addons dans les paramètres du projet et reteste. Si le problème disparaît, c'est l'addon — vérifie qu'une version mise à jour n'existe pas avant d'accuser le moteur.
5. Accepte que rester sur l'ancienne version est un résultat valable. Si le coût de la correction dépasse le bénéfice de la mise à jour, annule la branche, reste où tu es, et programme un rappel pour réessayer à la sortie de la prochaine version. Ce n'est pas un échec — c'est la gestion des risques qui fonctionne.

Quand ne rien changer est la bonne décision

Certains projets ne devraient tout simplement pas être mis à jour, et cela mérite d'être dit clairement : les jeux publiés ou presque publiés, les projets C# qui ont besoin de l'export Web, les jeux ciblant du vieux matériel, et les projets basés sur des builds de moteur fortement modifiés. Dans tous ces cas, la version sur laquelle tu es fait son travail. La mise à jour est un outil, pas une vertu — l'objectif est un jeu terminé, pas un moteur tout neuf.

FAQ

Puis-je rétrograder après une mise à jour ?

Non, pas de façon fiable. Une fois que le nouvel éditeur a réenregistré tes scènes et ressources, elles ne sont plus rétrocompatibles avec les éditeurs plus anciens. Le seul retour en arrière sûr est la restauration depuis le contrôle de version — c'est exactement pour cela que la branche de mise à jour existe.

Devrais-je sauter plusieurs versions d'un coup ?

Les petits sauts sont plus sûrs. Les notes de mise à jour officielles sont rédigées version par version, donc chaque saut a une check-list connue — un saut multi-versions les empile toutes d'un coup et rend plus difficile de déterminer quel changement a cassé quoi.

Les versions mineures cassent-elles vraiment des choses ?

Rarement, mais oui. La plupart des projets passent les versions mineures sans problème, mais des cas limites signalés par la communauté existent — bits de collision réinitialisés, régressions de rendu propres à certaines scènes. C'est précisément pour cela que les tests de référence avant la mise à jour comptent : ils transforment « est-ce que quelque chose a cassé ? » d'un ressenti en une mesure.

Cette check-list s'applique-t-elle à 3.x → 4.x ?

La check-list elle-même, oui — créer une branche, garder l'ancien binaire, capturer des références, tester après. La liste des points de rupture, non : la migration de 3 vers 4 est bien plus vaste (syntaxe GDScript, nœuds renommés, systèmes refaits) et possède sa propre documentation officielle dédiée.