Cara Menaikkan Versi Godot dengan Aman

Pengantar

Menaikkan versi game engine di tengah proyek adalah salah satu keputusan rutin paling menakutkan dalam pengembangan game. Versi Godot baru mungkin memperbaiki bug yang selama ini menghambatmu — atau diam-diam merusak scene yang sudah kamu garap selama enam bulan. Itulah mengapa para developer berpengalaman di komunitas Godot memperlakukan upgrade versi sebagai keputusan risiko, bukan pekerjaan rutin biasa.

Panduan ini bukan kampanye "selalu upgrade". Ini adalah checklist manajemen risiko untuk migrasi Godot 4.x ke 4.x: cara memutuskan apakah upgrade memang perlu, cara mempersiapkan diri supaya bisa mundur dengan aman, apa saja yang diketahui rusak antar versi, dan — yang terpenting — cara benar-benar memverifikasi bahwa tidak ada yang rusak.

Perlukah Kamu Upgrade Sama Sekali?

Sebelum menyentuh apa pun, jawab pertanyaan ini dengan jujur. Upgrade punya biaya nyata (pekerjaan migrasi + pengujian ulang), jadi manfaatnya juga harus sama nyatanya.

Upgrade jika…

• Bug yang sudah diperbaiki di upstream sedang menghambatmu. Jika masalahmu sudah diperbaiki di rilis yang lebih baru, upgrade biasanya lebih murah daripada terus-menerus memakai solusi darurat.
• Fitur baru memberi manfaat nyata bagi game-mu. Bukan sekadar "kedengarannya bagus" — melainkan sesuatu yang benar-benar menghemat waktu pengembangan atau membuka desain yang kamu butuhkan.
• Timeline pengembanganmu panjang. Jika proyekmu akan memakan waktu bertahun-tahun, lompatan kecil yang sering (satu versi minor sekaligus) jauh lebih aman daripada satu lompatan raksasa di akhir. Kesenjangannya hanya akan makin lebar.

Jangan upgrade jika…

• Kamu sudah dekat rilis. Minggu-minggu menjelang perilisan adalah waktu terburuk untuk memasukkan perubahan di level engine. Rilis dulu, upgrade belakangan.
• Kamu butuh C# + ekspor Web. Ekspor Web untuk proyek C# masih belum tersedia di Godot 4.x (dilacak di godot#70796). Jika kamu mengandalkannya di 3.x, pindah ke 4.x berarti kehilangannya.
• Targetmu perangkat keras lama. Godot 3.x berjalan di GPU kelas OpenGL 2; renderer Compatibility di Godot 4 mewajibkan OpenGL 3.3 / WebGL 2. Jika audiensmu memakai mesin lama, 3.x bisa jadi memang engine yang tepat.
• Addon penting belum diperbarui. Jika plugin yang menjadi tumpuan proyekmu belum mendukung versi baru, kamu mewarisi masalah migrasinya di atas masalahmu sendiri.

Sebelum Upgrade — Checklist Persiapan

Setiap langkah di sini ada agar kalau upgrade gagal, yang hilang cuma satu sore, bukan seluruh proyek.

1. Commit semuanya dan buat branch khusus upgrade. Jangan pernah meng-upgrade satu-satunya salinan proyekmu. Branch khusus (atau salinan penuh folder jika kamu tidak memakai git) berarti mengembalikan keadaan cukup satu perintah, bukan misi penyelamatan.
2. Catat versi persismu saat ini (mis. build 4.x.y yang mana, standar atau .NET). Kamu akan membutuhkannya jika harus kembali atau melaporkan bug.
3. Simpan binary editor lama. Berbagai versi Godot bisa terpasang berdampingan — editornya berupa satu file executable, jadi menyimpan keduanya tidak memakan biaya apa pun dan kamu bisa membuka branch lama dengan editor lama kapan saja.
4. Daftar addon-mu dan periksa versi yang didukung masing-masing. Telusuri addons/, catat asal setiap addon, dan pastikan di repo atau halaman Asset Library-nya bahwa addon itu mendukung versi tujuan.
5. Baca catatan upgrade resmi untuk setiap versi yang kamu lewati. Panduan migrasi resmi ditulis per versi — jika kamu naik dari 4.2 ke 4.4, baca catatan 4.3 dan 4.4 dua-duanya.
6. Abadikan bukti "kondisi baik". Ambil screenshot scene-scene kunci, rekam klip gameplay singkat, atau — yang paling bagus — tulis skenario pengujian otomatis (dibahas lebih lanjut di bagian pengujian di bawah). Setelah upgrade, pertanyaan "apakah tampilan dan perilakunya masih sama?" hanya bisa dijawab kalau kamu sudah merekam arti "sama" itu sebelumnya.

Prosedur Upgrade

1. Buka salinan branch dengan editor baru. Branch upgrade, bukan main. Editor baru akan menawarkan konversi/impor ulang — terima.
2. Biarkan proses impor ulang berjalan. Folder .godot dibuat ulang dari nol. Impor pertama bisa memakan waktu di proyek besar, dan peringatan yang muncul selama proses pertama itu biasanya tidak berbahaya.
3. Periksa panel Output dan Debugger untuk error yang baru. Bandingkan dengan error yang memang sudah ada sebelumnya (sudah kamu catat, kan?). Error baru itulah daftar tugas migrasimu.
4. Mainkan jalur-jalur kritis. Mulai game baru, muat save, jalankan loop gameplay inti, buka menu-menu utama. Error di editor adalah bagian mudahnya — regresi bersembunyi di perilaku runtime.
5. Jalankan skenario pengujianmu (yang kamu siapkan sebelum upgrade) dan bandingkan hasilnya dengan baseline.
6. Diff working tree di git sebelum commit. Editor menulis ulang file selama migrasi: project.godot mendapat nilai konfigurasi baru, file .tscn disimpan ulang, dan file .uid baru bisa bermunculan. Tinjau diff-nya agar kamu tahu persis apa yang berubah — lalu commit sebagai satu commit migrasi yang berlabel jelas.

Titik Rusak yang Sudah Diketahui Antar Versi 4.x

Versi minor Godot 4 sebagian besar kompatibel, tetapi kata "sebagian besar" itu bukan tanpa makna. Berikut perubahan yang paling sering menggigit, berdasarkan catatan resmi dan laporan komunitas.

4.2 → 4.3: TileMap usang, digantikan TileMapLayer

Godot 4.3 menandai node TileMap sebagai usang dan menggantinya dengan TileMapLayer — satu node per layer, bukan layer-layer di dalam satu node. TileMap yang sudah ada tetap berfungsi, tetapi kode baru dan proyek baru sebaiknya memakai TileMapLayer. Editor menyediakan alat ekstraksi: pilih TileMap-mu, buka panel bawah TileMap, klik ikon toolbox di pojok kanan atas, lalu pilih "Extract TileMap layers as individual TileMapLayer nodes".

4.3 → 4.4: file .uid dan tambahan GDScript

• Godot 4.4 menambahkan file pendamping .uid di samping skrip dan shader. Commit file-file itu ke version control — menghapusnya bisa merusak referensi uid:// di mana pun referensi itu dipakai (catatan upgrade resmi 4.4 membahas perubahan terkait seperti path @export_file yang menjadi uid://). Mereka terlihat seperti sampah; padahal bukan.
• Typed Dictionary dan tambahan GDScript lainnya kompatibel ke belakang — kode lamamu tetap berjalan. Namun addon yang mengadopsi fitur baru berhenti berfungsi di versi lama, sehingga perilaku addon bisa berbeda setelah lompatan versi.

Umum: perubahan halus antar versi minor mana pun

Penyesuaian rendering antar versi minor bisa mengubah tampilan game-mu secara halus — pencahayaan, anti-aliasing, snapping 2D. Diskusi komunitas juga memuat regresi spesifik scene yang tidak bisa direproduksi di proyek baru: sebuah scene berulah setelah upgrade, tetapi membangun ulang scene yang sama di proyek bersih justru berjalan normal. Jika ada yang rusak tanpa penjelasan, coba urutan isolasi ini: tutup editor, hapus folder .godot, buka kembali dan biarkan semuanya diimpor ulang; jika masalahnya masih ada, reproduksi scene itu di proyek bersih untuk menentukan apakah biang keroknya kondisi yang menumpuk di proyekmu atau perubahan engine yang sesungguhnya.

3.x → 4.x adalah cerita yang berbeda

Semua di atas berlaku untuk lompatan 4.x ke 4.x. Migrasi dari Godot 3 ke Godot 4 adalah kategori yang sama sekali lain: sintaks GDScript berubah, banyak node diganti nama, dan TileMap, fisika, serta rendering dirombak dari dasar — dan kebanyakan addon membutuhkan versi khusus 4.x. Untuk proyek 3.x berukuran besar, biaya migrasinya bisa mendekati biaya membangun ulang, dan apakah itu sepadan benar-benar keputusan per proyek. Migrasi itu layak mendapat (dan memang punya) dokumentasi tersendiri; artikel ini tidak akan berpura-pura mencakupnya.

Pengujian Setelah Upgrade — Hambatan yang Sebenarnya

Inilah bagian jujurnya: alasan nomor satu developer menghindari upgrade bukanlah migrasinya itu sendiri — melainkan mahalnya memverifikasi "tidak ada yang rusak" secara manual. Satu putaran regresi manual penuh pada game berukuran menengah bisa melahap satu akhir pekan. Dan bug runtime yang ditemukan pemainmu setelah rilis jauh lebih buruk daripada error editor mana pun, karena kini itu masalah reputasi, bukan sekadar butir daftar tugas.

Smoke test manual minimum

• Mulai game baru dari layar judul
• Muat file save yang sudah ada
• Mainkan loop gameplay inti selama beberapa menit
• Periksa UI di setiap resolusi dan mode jendela yang kamu dukung

Otomatiskan perbandingan sebelum/sesudah

Pemeriksaan manual tidak bisa diskalakan, dan ia tak akan memberitahumu bahwa sebuah sprite bergeser dua piksel. Justru untuk itulah Godot QA dibuat — test runner untuk Godot yang gratis, berlisensi MIT, dan open source. Alur kerjanya cocok sempurna untuk upgrade versi:

1. Sebelum upgrade, tulis (atau rekam) file JSON skenario yang mencakup jalur-jalur kritismu, dan ambil screenshot baseline di versi lama.
2. Setelah upgrade, jalankan skenario yang persis sama plus pixel-diff terhadap baseline di versi baru.
3. Kegagalan langsung menunjuk lokasi regresi dalam hitungan menit, bukan akhir pekan penuh replay manual.

Sebuah skenario hanyalah daftar langkah dalam JSON — input, jeda, asersi, 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"}
  ]
}

Format skenario yang sama juga dipakai oleh alat run_test_scenario milik Godot MCP Pro, jadi asisten AI yang terhubung ke editormu bisa menuliskan skenario-skenario ini untukmu.

Jika Ada yang Rusak

1. Lakukan bisect per versi. Jika kamu melompati beberapa versi minor sekaligus, ulangi upgrade satu versi minor demi satu untuk menemukan persis di mana kerusakannya. Itu mempersempit pencarian dari "semuanya" menjadi satu changelog.
2. Bersihkan folder .godot dan biarkan proyek diimpor ulang. Cache impor yang basi menyebabkan porsi keanehan pasca-upgrade yang mengejutkan besarnya.
3. Cari pesan errormu yang persis di GitHub issues engine. Jika itu regresi sungguhan, sering kali sudah ada yang melaporkannya — kadang lengkap dengan solusi sementara.
4. Periksa apakah addon-nya yang jadi biang kerok. Nonaktifkan addon-mu di Project Settings dan uji ulang. Jika masalahnya hilang, pelakunya addon — cek apakah ada rilis terbaru sebelum menyalahkan engine.
5. Terima bahwa bertahan di versi lama juga hasil yang sah. Jika biaya perbaikan melebihi manfaat upgrade, kembalikan branch-nya, bertahanlah, dan pasang pengingat untuk mencoba lagi saat rilis berikutnya tiba. Itu bukan kegagalan — itu manajemen risiko yang bekerja.

Ketika Bertahan Adalah Pilihan yang Benar

Beberapa proyek memang sebaiknya tidak upgrade, dan itu layak dikatakan terang-terangan: game yang sudah rilis atau hampir rilis, proyek C# yang butuh ekspor web, game yang menargetkan perangkat keras lama, dan proyek di atas build engine kustom yang banyak dimodifikasi. Dalam semua kasus itu, versi yang sedang kamu pakai sedang menjalankan tugasnya. Upgrade adalah alat, bukan kebajikan — tujuannya adalah game yang selesai, bukan engine yang paling anyar.

FAQ

Bisakah aku downgrade setelah upgrade?

Tidak, tidak dengan andal. Begitu editor baru menyimpan ulang scene dan resource-mu, semuanya tidak lagi kompatibel ke belakang dengan editor yang lebih lama. Satu-satunya jalan kembali yang aman adalah memulihkan dari version control — persis itulah alasan branch upgrade dibuat.

Bolehkah aku melompati beberapa versi sekaligus?

Lompatan kecil lebih aman. Catatan upgrade resmi ditulis per versi, jadi setiap lompatan punya checklist yang jelas — lompatan multi-versi menumpuk semuanya sekaligus dan menyulitkan menentukan perubahan mana yang merusak apa.

Apakah versi minor benar-benar bisa merusak sesuatu?

Jarang, tetapi ya. Sebagian besar proyek melompati versi minor tanpa masalah, tetapi kasus tepi yang dilaporkan komunitas memang ada — bit kolisi yang ter-reset, regresi rendering spesifik scene. Justru karena itulah tes baseline sebelum upgrade penting: ia mengubah "apa ada yang rusak?" dari sekadar perasaan menjadi pengukuran.

Apakah checklist ini berlaku untuk 3.x → 4.x?

Checklist-nya sendiri, ya — buat branch, simpan binary lama, ambil baseline, uji sesudahnya. Daftar titik rusaknya, tidak: migrasi 3 ke 4 jauh lebih besar (sintaks GDScript, node yang diganti nama, sistem yang dirombak) dan punya dokumentasi resmi tersendiri.