Jak bezpiecznie aktualizować wersje Godota

Wprowadzenie

Aktualizacja silnika gry w trakcie projektu to jedna z najbardziej stresujących rutynowych decyzji w tworzeniu gier. Nowa wersja Godota może naprawić błąd, który Cię blokuje — albo po cichu zepsuć scenę, w którą włożyłeś sześć miesięcy pracy. Dlatego doświadczeni deweloperzy ze społeczności Godota traktują aktualizację wersji jako decyzję dotyczącą ryzyka, a nie rutynowy obowiązek.

Ten przewodnik nie namawia do zasady „zawsze aktualizuj". To checklista zarządzania ryzykiem dla migracji między wersjami Godot 4.x: jak zdecydować, czy w ogóle aktualizować, jak się przygotować, żeby móc bezpiecznie się wycofać, co według dostępnej wiedzy psuje się między wersjami, oraz — co najważniejsze — jak faktycznie zweryfikować, że nic się nie zepsuło.

Czy w ogóle warto aktualizować?

Zanim czegokolwiek dotkniesz, odpowiedz szczerze na to pytanie. Aktualizacja ma realny koszt (praca migracyjna + ponowne testowanie), więc korzyść musi być równie realna.

Aktualizuj, jeśli…

• Blokuje Cię błąd naprawiony w nowszej wersji silnika. Jeśli Twój problem został już rozwiązany w nowszym wydaniu, aktualizacja jest zwykle tańsza niż wieczne obchodzenie go dookoła.
• Nowa funkcja przynosi Twojej grze wymierną korzyść. Nie „brzmi fajnie" — coś, co realnie oszczędza czas developmentu albo odblokowuje potrzebny Ci element projektu gry.
• Masz długi harmonogram developmentu. Jeśli projekt potrwa lata, małe częste skoki (po jednej wersji pomocniczej naraz) są znacznie bezpieczniejsze niż jeden gigantyczny skok na końcu. Różnica tylko rośnie.

Nie aktualizuj, jeśli…

• Jesteś blisko premiery. Tygodnie przed wydaniem gry to najgorszy możliwy moment na wprowadzanie zmian na poziomie silnika. Najpierw wydaj, aktualizuj potem.
• Potrzebujesz C# + eksportu na Web. Eksport webowy dla projektów C# wciąż jest niedostępny w Godot 4.x (śledzone w godot#70796). Jeśli polegasz na nim w 3.x, przejście na 4.x go odbiera.
• Celujesz w stary sprzęt. Godot 3.x działa na GPU klasy OpenGL 2; renderer Compatibility w Godot 4 wymaga OpenGL 3.3 / WebGL 2. Jeśli Twoi odbiorcy siedzą na starych maszynach, 3.x może być naprawdę właściwym silnikiem.
• Kluczowe addony nie zostały jeszcze zaktualizowane. Jeśli wtyczka, od której zależy Twój projekt, nie obsługuje nowej wersji, dziedziczysz jej problem migracyjny na dokładkę do własnego.

Przed aktualizacją — checklista przygotowań

Każdy krok z tej listy istnieje po to, żeby w razie nieudanej aktualizacji stracić popołudnie, a nie projekt.

1. Zacommituj wszystko i utwórz gałąź aktualizacyjną. Nigdy nie aktualizuj jedynej kopii projektu. Dedykowana gałąź (albo pełna kopia folderu, jeśli nie używasz gita) sprawia, że powrót to jedna komenda, a nie misja ratunkowa.
2. Zanotuj swoją obecną dokładną wersję (np. który build 4.x.y, standardowy czy .NET). Przyda się, jeśli będziesz musiał wrócić albo zgłosić błąd.
3. Zachowaj stary plik wykonywalny edytora. Wersje Godota instalują się obok siebie — edytor to pojedynczy plik wykonywalny, więc trzymanie obu nic nie kosztuje i pozwala w każdej chwili otworzyć starą gałąź starym edytorem.
4. Spisz swoje addony i sprawdź obsługiwane wersje każdego z nich. Przejrzyj addons/, zanotuj, skąd pochodzi każdy z nich, i potwierdź w jego repozytorium albo na stronie Asset Library, że obsługuje wersję docelową.
5. Przeczytaj oficjalne noty aktualizacyjne każdej wersji, przez którą przeskakujesz. Oficjalne przewodniki migracyjne są pisane per wersja — jeśli przechodzisz z 4.2 na 4.4, przeczytaj noty zarówno 4.3, jak i 4.4.
6. Zbierz dowody „znanego dobrego stanu". Zrób zrzuty ekranu kluczowych scen, nagraj krótki klip z rozgrywki albo — najlepiej — napisz zautomatyzowane scenariusze testowe (więcej o tym w sekcji o testowaniu poniżej). Po aktualizacji na pytanie „czy wygląda i zachowuje się tak samo?" da się odpowiedzieć tylko wtedy, gdy wcześniej utrwaliłeś, co znaczy „tak samo".

Procedura aktualizacji

1. Otwórz kopię z gałęzi nowym edytorem. Gałąź aktualizacyjną, nie main. Nowy edytor zaproponuje konwersję/reimport — zaakceptuj.
2. Pozwól na reimport. Folder .godot regeneruje się od zera. Pierwszy import może potrwać przy dużych projektach, a ostrzeżenia wypisywane podczas tego pierwszego przebiegu są zwykle nieszkodliwe.
3. Sprawdź panele Output i Debugger pod kątem nowych błędów. Porównaj z błędami, które miałeś już wcześniej (zanotowałeś je, prawda?). Nowe błędy to lista zadań migracji.
4. Przegraj krytyczne ścieżki. Rozpocznij nową grę, wczytaj zapis, uruchom rdzeń pętli rozgrywki, otwórz główne menu. Błędy w edytorze to te łatwe — regresje kryją się w zachowaniu podczas działania gry.
5. Uruchom swoje scenariusze testowe (te przygotowane przed aktualizacją) i porównaj wyniki z linią bazową.
6. Przejrzyj diff drzewa roboczego w gicie przed commitem. Edytor przepisuje pliki podczas migracji: project.godot dostaje nowe wartości konfiguracyjne, pliki .tscn są zapisywane ponownie, mogą też pojawić się nowe pliki .uid. Przejrzyj diff, żeby dokładnie wiedzieć, co się zmieniło — a potem zacommituj to jako pojedynczy, jasno opisany commit migracyjny.

Znane punkty awarii między wersjami 4.x

Wersje pomocnicze Godota 4 są w większości kompatybilne, ale słowo „w większości" robi tu sporo roboty. Oto zmiany, które najczęściej dają się we znaki, według oficjalnych not i zgłoszeń społeczności.

4.2 → 4.3: TileMap wycofany na rzecz TileMapLayer

Godot 4.3 oznaczył węzeł TileMap jako przestarzały na rzecz TileMapLayer — jeden węzeł na warstwę zamiast warstw wewnątrz jednego węzła. Istniejące TileMapy nadal działają, ale nowy kod i nowe projekty powinny używać TileMapLayer. Edytor zawiera narzędzie do ekstrakcji: zaznacz swój TileMap, otwórz dolny panel TileMap, kliknij ikonę skrzynki narzędziowej w prawym górnym rogu i wybierz „Extract TileMap layers as individual TileMapLayer nodes".

4.3 → 4.4: pliki .uid i nowości w GDScript

• Godot 4.4 dodał towarzyszące pliki .uid obok skryptów i shaderów. Commituj je do systemu kontroli wersji — ich usunięcie może zepsuć odwołania uid:// wszędzie tam, gdzie są używane (oficjalne noty aktualizacyjne 4.4 opisują powiązane zmiany, np. ścieżki @export_file stające się uid://). Wyglądają jak śmieci — nie są nimi.
• Typowane słowniki (Typed Dictionaries) i inne nowości GDScript są wstecznie kompatybilne — Twój stary kod nadal działa. Ale addony, które przyjmą nowe funkcje, przestają działać na starszych wersjach, więc zachowanie addonów może się różnić po skoku.

Ogólnie: subtelne zmiany między dowolnymi wersjami pomocniczymi

Poprawki renderowania między wersjami pomocniczymi mogą subtelnie zmienić wygląd Twojej gry — oświetlenie, antyaliasing, przyciąganie 2D. W dyskusjach społeczności pojawiają się też regresje specyficzne dla konkretnej sceny, które nie reprodukują się w świeżych projektach: scena zachowuje się źle po aktualizacji, ale odbudowanie tej samej sceny w czystym projekcie działa poprawnie. Jeśli coś psuje się w niewytłumaczalny sposób, wypróbuj tę sekwencję izolacji: zamknij edytor, usuń folder .godot, otwórz ponownie i pozwól na pełny reimport; jeśli problem nie znika, odtwórz scenę w czystym projekcie, żeby ustalić, czy winowajcą jest nagromadzony stan Twojego projektu, czy faktyczna zmiana w silniku.

3.x → 4.x to zupełnie inna bestia

Wszystko powyżej dotyczy skoków 4.x-na-4.x. Migracja z Godota 3 na Godota 4 to całkowicie inna kategoria: zmieniła się składnia GDScript, wiele węzłów przemianowano, a TileMap, fizyka i renderowanie zostały przebudowane od podstaw — a większość addonów potrzebuje dedykowanych wersji 4.x. Dla dużych projektów 3.x koszt migracji może zbliżyć się do kosztu przepisania od zera, a czy to się opłaca, to naprawdę decyzja indywidualna dla każdego projektu. Ta migracja zasługuje na własną dokumentację (i ją ma); ten artykuł nie będzie udawał, że ją obejmuje.

Testowanie po aktualizacji — prawdziwe wąskie gardło

Teraz szczerze: głównym powodem, dla którego deweloperzy unikają aktualizacji, nie jest sama migracja — tylko to, że ręczna weryfikacja, iż „nic się nie zepsuło", jest kosztowna. Pełen ręczny przebieg regresji w średniej wielkości grze potrafi pochłonąć cały weekend. A błąd runtime, który gracze znajdą po premierze, jest znacznie gorszy niż jakikolwiek błąd w edytorze, bo staje się problemem reputacyjnym, a nie pozycją na liście zadań.

Minimalny ręczny smoke test

• Rozpocznij nową grę z ekranu tytułowego
• Wczytaj istniejący plik zapisu
• Zagraj kilka minut w rdzeń pętli rozgrywki
• Sprawdź UI w każdej obsługiwanej rozdzielczości i trybie okna

Zautomatyzuj porównanie przed/po

Ręczny przebieg się nie skaluje i nie powie Ci, że sprite przesunął się o dwa piksele. Dokładnie do tego stworzono Godot QA — darmowy, open-source'owy runner testów dla Godota na licencji MIT. Jego przepływ pracy idealnie pasuje do aktualizacji wersji:

1. Przed aktualizacją napisz (lub nagraj) pliki JSON ze scenariuszami pokrywającymi krytyczne ścieżki i zbierz bazowe zrzuty ekranu na starej wersji.
2. Po aktualizacji uruchom dokładnie te same scenariusze plus porównanie pikselowe z liniami bazowymi na nowej wersji.
3. Niepowodzenia wskazują regresje w kilka minut zamiast weekendu ręcznego odtwarzania.

Scenariusz to po prostu lista kroków w JSON-ie — wejścia, oczekiwania, asercje, zrzuty ekranu:

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

Ten sam format scenariusza wykorzystuje narzędzie run_test_scenario w Godot MCP Pro, więc asystent AI podłączony do Twojego edytora może pisać te scenariusze za Ciebie.

Jeśli coś się zepsuje

1. Bisekcja po wersjach. Jeśli przeskoczyłeś kilka wersji pomocniczych naraz, powtórz aktualizację po jednej wersji pomocniczej, żeby dokładnie znaleźć, gdzie się zepsuło. To zawęża poszukiwania ze „wszystkiego" do jednego changeloga.
2. Wyczyść folder .godot i pozwól projektowi na reimport. Nieaktualne cache importu odpowiadają za zaskakująco dużą część poaktualizacyjnych dziwactw.
3. Wyszukaj swój dokładny komunikat błędu w issues silnika na GitHubie. Jeśli to prawdziwa regresja, często ktoś już ją zgłosił — czasem razem z obejściem.
4. Sprawdź, czy winowajcą nie jest addon. Wyłącz addony w ustawieniach projektu i przetestuj ponownie. Jeśli problem znika, to wina addonu — zanim obwinisz silnik, sprawdź, czy nie wyszła jego aktualizacja.
5. Zaakceptuj, że pozostanie na starej wersji to prawomocny wynik. Jeśli koszt naprawy przekracza korzyść z aktualizacji, cofnij gałąź, zostań na miejscu i ustaw przypomnienie, żeby spróbować ponownie przy następnym wydaniu. To nie porażka — to zarządzanie ryzykiem, które zadziałało.

Kiedy pozostanie na miejscu jest właściwą decyzją

Niektóre projekty po prostu nie powinny się aktualizować i warto powiedzieć to wprost: gry wydane lub bliskie wydania, projekty C# potrzebujące eksportu webowego, gry celujące w stary sprzęt oraz projekty na mocno zmodyfikowanych własnych buildach silnika. We wszystkich tych przypadkach wersja, na której jesteś, robi swoje. Aktualizacja to narzędzie, nie cnota — celem jest ukończona gra, a nie świeży silnik.

FAQ

Czy mogę zrobić downgrade po aktualizacji?

Nie w sposób niezawodny. Gdy tylko nowy edytor ponownie zapisze Twoje sceny i zasoby, przestają one być wstecznie kompatybilne ze starszymi edytorami. Jedyną bezpieczną drogą powrotu jest przywrócenie z systemu kontroli wersji — i dokładnie po to istnieje gałąź aktualizacyjna.

Czy powinienem przeskakiwać kilka wersji naraz?

Małe skoki są bezpieczniejsze. Oficjalne noty aktualizacyjne są pisane per wersja, więc każdy skok ma znaną checklistę — skok przez wiele wersji nakłada je wszystkie naraz i utrudnia ustalenie, która zmiana co zepsuła.

Czy wersje pomocnicze naprawdę coś psują?

Rzadko, ale tak. Większość projektów przeskakuje wersje pomocnicze bez kłopotów, ale istnieją zgłaszane przez społeczność przypadki brzegowe — resetujące się bity kolizji, regresje renderowania specyficzne dla sceny. Właśnie dlatego testy bazowe przed aktualizacją mają znaczenie: zamieniają pytanie „czy coś się zepsuło?" z przeczucia w pomiar.

Czy ta checklista działa dla 3.x → 4.x?

Sama checklista — tak: gałąź, zachowanie starego binarium, zebranie linii bazowych, testy po. Lista punktów awarii — nie: migracja z 3 na 4 jest znacznie większa (składnia GDScript, przemianowane węzły, przebudowane systemy) i ma własną dedykowaną oficjalną dokumentację.