Godot-Versionen sicher upgraden

Einführung

Mitten im Projekt die Engine-Version zu wechseln ist eine der beängstigendsten Routineentscheidungen in der Spieleentwicklung. Eine neue Godot-Version behebt vielleicht genau den Bug, der dich blockiert — oder sie zerstört stillschweigend eine Szene, in der sechs Monate Arbeit stecken. Genau deshalb behandeln erfahrene Entwickler in der Godot-Community ein Versions-Upgrade als Risikoentscheidung, nicht als Routineaufgabe.

Dieser Leitfaden ist kein Plädoyer für „immer upgraden“. Er ist eine Risikomanagement-Checkliste für die Migration von Godot 4.x zu 4.x: wie du entscheidest, ob du überhaupt upgraden solltest, wie du dich so vorbereitest, dass du sicher zurück kannst, was zwischen Versionen bekanntermaßen kaputtgeht, und — am wichtigsten — wie du tatsächlich verifizierst, dass nichts kaputtgegangen ist.

Solltest du überhaupt upgraden?

Bevor du irgendetwas anfasst, beantworte diese Frage ehrlich. Ein Upgrade hat echte Kosten (Migrationsarbeit + erneutes Testen), also muss der Nutzen genauso real sein.

Upgrade, wenn…

• Ein upstream behobener Bug dich blockiert. Wenn dein Problem in einem neueren Release bereits behoben ist, ist das Upgrade meist günstiger, als ewig einen Workaround mitzuschleppen.
• Ein neues Feature deinem Spiel spürbar nützt. Nicht „klingt nett“ — sondern etwas, das dir echte Entwicklungszeit spart oder ein Design ermöglicht, das du brauchst.
• Dein Entwicklungszeitraum lang ist. Wenn dein Projekt Jahre dauern wird, sind kleine, häufige Sprünge (eine Minor-Version nach der anderen) deutlich sicherer als ein riesiger Sprung am Ende. Der Abstand wächst nur weiter.

Kein Upgrade, wenn…

• Du kurz vor dem Release stehst. Die Wochen vor der Veröffentlichung sind der denkbar schlechteste Zeitpunkt für Änderungen auf Engine-Ebene. Erst releasen, dann upgraden.
• Du C# + Web-Export brauchst. Web-Export für C#-Projekte ist in Godot 4.x weiterhin nicht verfügbar (verfolgt in godot#70796). Wenn du dich in 3.x darauf verlässt, verlierst du ihn mit dem Wechsel zu 4.x.
• Du alte Hardware anvisierst. Godot 3.x läuft auf GPUs der OpenGL-2-Klasse; der Compatibility-Renderer von Godot 4 erfordert OpenGL 3.3 / WebGL 2. Wenn dein Publikum alte Rechner nutzt, kann 3.x tatsächlich die richtige Engine sein.
• Kritische Addons noch nicht aktualisiert sind. Wenn ein Plugin, von dem dein Projekt abhängt, die neue Version nicht unterstützt, erbst du dessen Migrationsproblem zusätzlich zu deinem eigenen.

Vor dem Upgrade — Vorbereitungs-Checkliste

Jeder Schritt hier existiert, damit du bei einem schiefgelaufenen Upgrade einen Nachmittag verlierst, nicht ein Projekt.

1. Alles committen und einen Upgrade-Branch erstellen. Upgrade niemals die einzige Kopie deines Projekts. Ein dedizierter Branch (oder eine vollständige Kopie des Ordners, falls du kein Git verwendest) macht das Zurückrollen zu einem einzigen Befehl statt zu einer Rettungsaktion.
2. Notiere deine aktuelle, exakte Version (z. B. welcher 4.x.y-Build, Standard oder .NET). Du brauchst sie, falls du zurück musst oder einen Bug-Report einreichst.
3. Behalte die alte Editor-Binary. Godot-Versionen lassen sich parallel installieren — der Editor ist eine einzelne ausführbare Datei, beide zu behalten kostet also nichts, und du kannst den alten Branch jederzeit mit dem alten Editor öffnen.
4. Liste deine Addons auf und prüfe die unterstützten Versionen jedes einzelnen. Geh addons/ durch, notiere die Herkunft jedes Addons und bestätige auf dessen Repo- oder Asset-Library-Seite, dass es die Zielversion unterstützt.
5. Lies die offiziellen Upgrade-Hinweise für jede Version, die du überspringst. Die offiziellen Migrationsleitfäden sind pro Version geschrieben — wenn du von 4.2 auf 4.4 gehst, lies sowohl die 4.3- als auch die 4.4-Hinweise.
6. Sichere Belege für den „bekannt guten“ Zustand. Mach Screenshots deiner wichtigsten Szenen, nimm einen kurzen Gameplay-Clip auf oder — am besten — schreib automatisierte Testszenarien (mehr dazu im Test-Abschnitt weiter unten). Nach dem Upgrade ist „sieht es gleich aus und verhält es sich gleich?“ nur beantwortbar, wenn du vorher festgehalten hast, was „gleich“ bedeutet.

Der Upgrade-Ablauf

1. Öffne die Branch-Kopie mit dem neuen Editor. Den Upgrade-Branch, nicht main. Der neue Editor bietet Konvertierung/Reimport an — akzeptiere.
2. Lass ihn reimportieren. Der .godot-Ordner wird von Grund auf neu erzeugt. Der erste Import kann bei großen Projekten eine Weile dauern, und die Warnungen, die er in diesem ersten Durchlauf ausgibt, sind meist harmlos.
3. Prüfe die Output- und Debugger-Panels auf neue Fehler. Vergleiche mit den Fehlern, die du vorher schon hattest (du hast sie doch notiert, oder?). Neue Fehler sind die To-do-Liste der Migration.
4. Spiele die kritischen Pfade durch. Starte ein neues Spiel, lade einen Spielstand, durchlaufe den Kern-Gameplay-Loop, öffne die Hauptmenüs. Fehler zur Editor-Zeit sind die einfachen — Regressionen verstecken sich im Laufzeitverhalten.
5. Führe deine Testszenarien aus (die du vor dem Upgrade vorbereitet hast) und vergleiche mit der Baseline.
6. Prüfe vor dem Commit den Working Tree mit git diff. Der Editor schreibt Dateien während der Migration um: project.godot erhält neue Konfigurationswerte, .tscn-Dateien werden neu gespeichert, und neue .uid-Dateien können auftauchen. Sieh dir den Diff an, damit du genau weißt, was sich geändert hat — und committe es dann als einen einzelnen, klar benannten Migrations-Commit.

Bekannte Bruchstellen zwischen 4.x-Versionen

Die Minor-Versionen von Godot 4 sind größtenteils kompatibel, aber „größtenteils“ trägt in diesem Satz eine gewisse Last. Hier sind die Änderungen, die am ehesten zubeißen, basierend auf offiziellen Hinweisen und Community-Berichten.

4.2 → 4.3: TileMap zugunsten von TileMapLayer als veraltet markiert

Godot 4.3 hat den TileMap-Node zugunsten von TileMapLayer als veraltet markiert — ein Node pro Ebene statt Ebenen innerhalb eines Nodes. Bestehende TileMaps funktionieren weiter, aber neuer Code und neue Projekte sollten TileMapLayer verwenden. Der Editor enthält ein Extraktionswerkzeug: Wähle deine TileMap aus, öffne das TileMap-Panel unten, klicke auf das Werkzeugkasten-Symbol in der oberen rechten Ecke und wähle „Extract TileMap layers as individual TileMapLayer nodes“.

4.3 → 4.4: .uid-Dateien und GDScript-Erweiterungen

• Godot 4.4 hat .uid-Begleitdateien eingeführt, die neben Skripten und Shadern liegen. Committe sie in die Versionsverwaltung — sie zu löschen kann uid://-Referenzen überall dort brechen, wo sie verwendet werden (die offiziellen 4.4-Upgrade-Hinweise decken verwandte Änderungen ab, etwa dass @export_file-Pfade zu uid:// werden). Sie sehen aus wie Müll; sie sind es nicht.
• Typisierte Dictionaries und andere GDScript-Erweiterungen sind abwärtskompatibel — dein alter Code läuft weiter. Aber Addons, die die neuen Features übernehmen, funktionieren auf älteren Versionen nicht mehr, sodass sich das Addon-Verhalten über den Sprung hinweg unterscheiden kann.

Allgemein: subtile Änderungen zwischen beliebigen Minor-Versionen

Rendering-Anpassungen zwischen Minor-Versionen können das Aussehen deines Spiels subtil verändern — Beleuchtung, Anti-Aliasing, 2D-Snapping. In Community-Diskussionen finden sich auch szenenspezifische Regressionen, die sich in frischen Projekten nicht reproduzieren lassen: Eine Szene verhält sich nach dem Upgrade falsch, aber dieselbe Szene in einem sauberen Projekt neu aufgebaut funktioniert einwandfrei. Wenn etwas unerklärlich kaputtgeht, probiere diese Isolationssequenz: Editor schließen, den .godot-Ordner löschen, wieder öffnen und alles reimportieren lassen; wenn das Problem bleibt, reproduziere die Szene in einem sauberen Projekt, um festzustellen, ob der Übeltäter der angesammelte Zustand deines Projekts oder eine tatsächliche Engine-Änderung ist.

3.x → 4.x ist ein anderes Kaliber

Alles oben Gesagte betrifft Sprünge von 4.x zu 4.x. Die Migration von Godot 3 zu Godot 4 ist eine völlig andere Kategorie: Die GDScript-Syntax hat sich geändert, viele Nodes wurden umbenannt, und TileMap, Physik und Rendering wurden von Grund auf überarbeitet — und die meisten Addons brauchen eigene 4.x-Versionen. Bei großen 3.x-Projekten können die Migrationskosten an die Kosten eines Neuaufbaus heranreichen, und ob es sich lohnt, ist eine echte Einzelfallentscheidung pro Projekt. Diese Migration verdient (und hat) ihre eigene Dokumentation; dieser Artikel gibt nicht vor, sie abzudecken.

Testen nach dem Upgrade — der eigentliche Engpass

Hier kommt der ehrliche Teil: Der Hauptgrund, warum Entwickler Upgrades meiden, ist nicht die Migration selbst — sondern dass es teuer ist, von Hand zu verifizieren, dass „nichts kaputtgegangen“ ist. Ein vollständiger manueller Regressionsdurchlauf bei einem mittelgroßen Spiel kann ein ganzes Wochenende fressen. Und ein Laufzeit-Bug, den deine Spieler nach dem Release finden, ist weit schlimmer als jeder Editor-Fehler, denn jetzt ist es ein Reputationsproblem, kein To-do-Punkt.

Minimaler manueller Smoke-Test

• Ein neues Spiel vom Titelbildschirm aus starten
• Einen bestehenden Spielstand laden
• Den Kern-Gameplay-Loop einige Minuten spielen
• Die UI in jeder unterstützten Auflösung und jedem Fenstermodus prüfen

Den Vorher/Nachher-Vergleich automatisieren

Der manuelle Durchlauf skaliert nicht, und er kann dir nicht sagen, dass ein Sprite um zwei Pixel verrutscht ist. Genau dafür wurde Godot QA gebaut — ein kostenloser, MIT-lizenzierter Open-Source-Test-Runner für Godot. Der Workflow passt perfekt zu Versions-Upgrades:

1. Vor dem Upgrade schreibst (oder zeichnest) du Szenario-JSON-Dateien auf, die deine kritischen Pfade abdecken, und erfasst Baseline-Screenshots auf der alten Version.
2. Nach dem Upgrade führst du exakt dieselben Szenarien plus einen Pixel-Diff gegen die Baselines auf der neuen Version aus.
3. Fehlschläge zeigen Regressionen punktgenau in Minuten statt einem Wochenende manuellen Nachspielens.

Ein Szenario ist einfach eine JSON-Liste von Schritten — Eingaben, Wartezeiten, Assertions, Screenshots:

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

Dasselbe Szenario-Format verwendet das run_test_scenario-Tool von Godot MCP Pro, sodass ein mit deinem Editor verbundener KI-Assistent diese Szenarien für dich schreiben kann.

Wenn etwas kaputtgeht

1. Nach Version halbieren. Wenn du mehrere Minor-Versionen auf einmal übersprungen hast, wiederhole das Upgrade eine Minor-Version nach der anderen, um genau herauszufinden, wo es gebrochen ist. Das grenzt die Suche von „alles“ auf einen einzigen Changelog ein.
2. Den .godot-Ordner löschen und das Projekt reimportieren lassen. Veraltete Import-Caches verursachen einen überraschend großen Anteil der Merkwürdigkeiten nach einem Upgrade.
3. Durchsuche die GitHub-Issues der Engine nach deiner exakten Fehlermeldung. Wenn es eine echte Regression ist, hat sie oft schon jemand gemeldet — manchmal mit einem Workaround.
4. Prüfe, ob ein Addon der Übeltäter ist. Deaktiviere deine Addons in den Projekteinstellungen und teste erneut. Verschwindet das Problem, ist es das Addon — schau nach einer aktualisierten Version, bevor du der Engine die Schuld gibst.
5. Akzeptiere, dass auf der alten Version zu bleiben ein legitimes Ergebnis ist. Wenn die Reparaturkosten den Nutzen des Upgrades übersteigen, verwirf den Branch, bleib wo du bist, und setz dir eine Erinnerung, es beim nächsten Release erneut zu versuchen. Das ist kein Scheitern — das ist Risikomanagement, das funktioniert.

Wann Bleiben die richtige Entscheidung ist

Manche Projekte sollten schlicht nicht upgraden, und das verdient es, klar gesagt zu werden: veröffentlichte oder fast veröffentlichte Spiele, C#-Projekte, die Web-Export brauchen, Spiele für alte Hardware und Projekte auf stark modifizierten Custom-Engine-Builds. In all diesen Fällen erfüllt die Version, auf der du bist, ihren Zweck. Upgraden ist ein Werkzeug, keine Tugend — das Ziel ist ein fertiges Spiel, nicht eine frische Engine.

FAQ

Kann ich nach dem Upgrade downgraden?

Nein, nicht zuverlässig. Sobald der neue Editor deine Szenen und Ressourcen neu gespeichert hat, sind sie nicht mehr abwärtskompatibel mit älteren Editoren. Der einzige sichere Weg zurück ist die Wiederherstellung aus der Versionsverwaltung — genau dafür existiert der Upgrade-Branch.

Sollte ich mehrere Versionen auf einmal überspringen?

Kleine Sprünge sind sicherer. Die offiziellen Upgrade-Hinweise sind pro Version geschrieben, jeder Sprung hat also eine bekannte Checkliste — ein Sprung über mehrere Versionen stapelt sie alle auf einmal und macht es schwerer zu erkennen, welche Änderung was kaputtgemacht hat.

Machen Minor-Versionen wirklich Dinge kaputt?

Selten, aber ja. Die meisten Projekte überstehen Minor-Versionssprünge problemlos, aber es gibt von der Community gemeldete Grenzfälle — zurückgesetzte Kollisions-Bits, szenenspezifische Rendering-Regressionen. Genau deshalb sind Baseline-Tests vor dem Upgrade wichtig: Sie machen aus „ist irgendwas kaputtgegangen?“ eine Messung statt eines Gefühls.

Gilt diese Checkliste auch für 3.x → 4.x?

Die Checkliste selbst, ja — Branch anlegen, alte Binary behalten, Baselines erfassen, danach testen. Die Liste der Bruchstellen, nein: Die Migration von 3 zu 4 ist weit größer (GDScript-Syntax, umbenannte Nodes, überarbeitete Systeme) und hat ihre eigene, dedizierte offizielle Dokumentation.