はじめに

開発途中のプロジェクトでゲームエンジンのバージョンを上げるのは、ゲーム開発における日常的な判断の中でも特に怖いものの一つです。新しいGodotでは今まさに困っているバグが直っているかもしれませんが、半年かけて作り込んだシーンが静かに壊れる可能性もあります。だからこそGodotコミュニティの経験豊富な開発者は、バージョンアップを「作業」ではなくリスク判断として扱っています。

このガイドは「常に最新版にすべき」という主張ではありません。Godot 4.x間の移行を対象とした、リスク管理のチェックリストです。そもそも上げるべきかの判断基準、安全に引き返せる準備の仕方、バージョン間で壊れることが知られているポイント、そして最も重要な「何も壊れていないことをどう確認するか」を扱います。

そもそもバージョンを上げるべきか？

何かを触る前に、まずこの問いに正直に答えてください。バージョンアップには実コスト（移行作業＋再テスト）がかかるので、それに見合う実利が必要です。

上げるべきケース

  • 本家で修正済みのバグに悩まされている。 困っている問題が新しいリリースで既に直っているなら、永久に回避策を抱え続けるより上げてしまう方が安いことが多いです。
  • 新機能がゲームに実質的なメリットをもたらす。 「良さそう」レベルではなく、実際の開発時間を節約できる、あるいは必要なデザインが実現できる機能であること。
  • 開発期間が長い。 数年がかりのプロジェクトなら、マイナーバージョンを1つずつこまめに上げる方が、最後に一気に大ジャンプするよりはるかに安全です。差分は放っておくと広がる一方です。

上げるべきでないケース

  • リリースが近い。 出荷直前の数週間は、エンジンレベルの変更を入れる最悪のタイミングです。まずリリースし、上げるのはその後に。
  • C#＋Webエクスポートが必要。 C#プロジェクトのWebエクスポートはGodot 4.xでは依然として利用できません（godot#70796で追跡中）。3.xでこれに依存しているなら、4.xに移ると失われます。
  • 古いハードウェアがターゲット。 Godot 3.xはOpenGL 2世代のGPUで動きますが、Godot 4のCompatibilityレンダラーはOpenGL 3.3 / WebGL 2が必須です。プレイヤー層が古いマシンを使うなら、3.xに留まるのが本当に正解ということもあります。
  • 重要なアドオンが未対応。 プロジェクトが依存するプラグインが新バージョン未対応なら、自分の移行作業に加えてそのアドオンの問題まで背負うことになります。

経験則： 「新しいバージョンが出たから」ではなく、見積もった具体的なコストを具体的なメリットが上回るときに上げる。これが基本です。

アップグレード前の準備チェックリスト

ここでの各ステップは、万一失敗しても失うのが「半日」であって「プロジェクト」ではないようにするためのものです。

  1. すべてコミットし、アップグレード用ブランチを作る。 プロジェクトの唯一のコピーを直接アップグレードしてはいけません。専用ブランチ（gitを使っていないならフォルダの完全コピー）があれば、巻き戻しはコマンド1つで済みます。
  2. 現在の正確なバージョンを記録する（4.x.yのどのビルドか、通常版か.NET版か）。戻すときやバグ報告のときに必要になります。
  3. 旧バージョンのエディタ実行ファイルを残しておく。 Godotは複数バージョンを並存できます。エディタは単一の実行ファイルなので、両方持っておくコストはゼロですし、いつでも旧ブランチを旧エディタで開けます。
  4. アドオンを列挙し、それぞれの対応バージョンを確認する。 addons/の中身を洗い出し、入手元を控え、リポジトリやAsset Libraryのページで移行先バージョンへの対応を確認します。
  5. 跨ぐバージョンすべての公式アップグレードノートを読む。 公式の移行ガイドはバージョンごとに書かれています。4.2から4.4に上げるなら、4.3と4.4の両方のノートを読んでください。
  6. 「正常な状態」の証拠を残す。 主要シーンのスクリーンショット、短いプレイ動画、あるいはベストなのは自動テストシナリオの作成です（後述のテストの章で詳しく扱います）。アップグレード後に「見た目も挙動も同じか？」に答えられるのは、事前に「同じ」の基準を記録しておいた場合だけです。

アップグレードの手順

  1. 新しいエディタでブランチ側のコピーを開く。 mainではなくアップグレード用ブランチを開きます。新エディタが変換・再インポートを提案してくるので受け入れます。
  2. 再インポートを待つ。 .godotフォルダはゼロから再生成されます。大きなプロジェクトでは初回インポートに時間がかかりますが、その最初のパスで出る警告はたいてい無害です。
  3. OutputパネルとDebuggerで「新しい」エラーを確認する。 アップグレード前からあったエラーと比較します（事前に控えてありますよね？）。新規のエラーが移行作業のToDoリストになります。
  4. クリティカルパスを実際にプレイする。 ニューゲーム開始、セーブのロード、コアゲームループ、主要メニューの表示。エディタ上のエラーは簡単な方で、リグレッションが潜むのは実行時の挙動です。
  5. テストシナリオを実行する（アップグレード前に用意したもの）。ベースラインと結果を比較します。
  6. コミット前にgitで作業ツリーの差分を確認する。 移行中、エディタはファイルを書き換えます。project.godotに新しい設定値が入り、.tscnが再保存され、新しい.uidファイルが現れることもあります。何が変わったかを差分で正確に把握してから、移行コミットとして1つの分かりやすいコミットにまとめてください。

4.x間の既知の破壊的変更ポイント

Godot 4のマイナーバージョン間は「おおむね」互換ですが、この「おおむね」がくせ者です。公式ノートとコミュニティ報告に基づき、引っかかりやすい変更を挙げます。

4.2 → 4.3：TileMapが非推奨に、TileMapLayerへ

Godot 4.3でTileMapノードは非推奨となり、TileMapLayerに置き換えられました。1つのノード内にレイヤーを持つのではなく、レイヤーごとに1ノードという設計です。既存のTileMapは動き続けますが、新しいコードやプロジェクトではTileMapLayerを使うべきです。エディタには変換ツールがあります。TileMapを選択し、下部のTileMapパネルを開き、右上のツールボックスアイコンから「Extract TileMap layers as individual TileMapLayer nodes」を選んでください。

コミュニティ報告のある落とし穴： TileMapLayerへの移行後、TileSetの物理レイヤーのコリジョンビットがデフォルトにリセットされたという報告があります。全員に起きるわけではありませんが、「衝突しなくなるのに何もエラーが出ない」というたちの悪い壊れ方です。変換後はタイルのコリジョンを明示的に確認してください。

4.3 → 4.4：.uidファイルとGDScriptの拡張

  • Godot 4.4から.uidコンパニオンファイルがスクリプトやシェーダーの隣に生成されます。必ずバージョン管理にコミットしてください。削除すると、uid://参照を使っている箇所で参照が壊れる可能性があります（@export_fileのパスがuid://になる等の関連変更は公式の4.4アップグレードノートに記載があります）。ゴミに見えますが、ゴミではありません。
  • 型付きDictionaryなどGDScriptの追加機能は後方互換で、既存コードはそのまま動きます。ただし新機能を採用したアドオンは旧バージョンでは動かなくなるため、バージョンを跨ぐとアドオンの挙動が変わる可能性があります。

全般：あらゆるマイナーバージョン間の微妙な変化

マイナーバージョン間のレンダリング調整により、ライティング、アンチエイリアス、2Dスナッピングなど、ゲームの見た目が微妙に変わることがあります。また、コミュニティの議論には「新規プロジェクトでは再現しない、特定シーンだけのリグレッション」の報告もあります。アップグレード後にあるシーンだけがおかしくなるのに、同じシーンをまっさらなプロジェクトで組み直すと正常に動く、というものです。原因不明の不具合が出たら、エディタを閉じて.godotフォルダを削除し、再度開いて全再インポート。それでも直らなければ、クリーンなプロジェクトで同じシーンを再現して、原因がプロジェクトに蓄積した状態なのかエンジン側の変更なのかを切り分けてください。

3.x → 4.xは別次元の話

ここまでの内容はすべて4.x間の話です。Godot 3から4への移行はまったく別カテゴリの作業です。GDScriptの構文が変わり、多数のノードが改名され、TileMap・物理・レンダリングは根本から作り直されており、ほとんどのアドオンは4.x専用バージョンが必要になります。大規模な3.xプロジェクトでは、移行コストが作り直しのコストに迫ることもあり、やる価値があるかは本当にプロジェクト次第です。この移行には専用のドキュメントが存在します（そして必要です）。本記事でカバーするふりはしません。

アップグレード後のテスト — 本当のボトルネック

正直な話をすると、開発者がアップグレードを避ける最大の理由は移行作業そのものではありません。「何も壊れていない」ことを手作業で確認するコストの高さです。中規模のゲームで手動リグレッションを一通りやると、週末が丸ごと消えます。そしてリリース後にプレイヤーが見つける実行時バグは、どんなエディタエラーよりも深刻です。ToDoリストの1項目ではなく、評判の問題になるからです。

最低限の手動スモークテスト

  • タイトル画面からニューゲームを開始する
  • 既存のセーブデータをロードする
  • コアゲームループを数分プレイする
  • サポートする各解像度・ウィンドウモードでUIを確認する

前後比較を自動化する

手動テストはスケールしませんし、スプライトが2ピクセルずれたことも教えてくれません。まさにそのために作られたのがGodot QAです。無料・MITライセンスのオープンソースなGodot用テストランナーで、そのワークフローはバージョンアップと完璧に噛み合います。

  1. アップグレード前に、クリティカルパスをカバーするシナリオJSONを書き（または記録し）、旧バージョンでベースラインのスクリーンショットを取得します。
  2. アップグレード後に、新バージョンでまったく同じシナリオを実行し、ベースラインとのピクセル差分を取ります。
  3. 失敗箇所がそのままリグレッションの位置を示すので、週末まるごとの手動プレイが数分で片付きます。

シナリオはステップ（入力・待機・アサーション・スクリーンショット）を並べたJSONにすぎません：

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

このシナリオ形式はGodot MCP Proのrun_test_scenarioツールと同じものなので、エディタに接続したAIアシスタントにシナリオを書かせることもできます。

壊れてしまったら

  1. バージョンで二分探索する。 複数のマイナーバージョンを一気に跨いだ場合は、1バージョンずつ上げ直してどこで壊れたかを特定します。調査範囲が「全部」から1つのchangelogに絞れます。
  2. .godotフォルダを削除して再インポートさせます。アップグレード後の謎の不具合のうち、意外な割合が古いインポートキャッシュが原因です。
  3. エラーメッセージそのままでエンジンのGitHub issuesを検索する。 本物のリグレッションなら誰かが報告済みのことが多く、回避策が書かれていることもあります。
  4. アドオンが原因でないか確認する。 プロジェクト設定でアドオンを無効にして再テストします。問題が消えたら犯人はアドオンです。エンジンを疑う前に、アドオンの更新版が出ていないか確認しましょう。
  5. 旧バージョンに留まることも正当な結論だと認める。 修正コストがアップグレードのメリットを上回るなら、ブランチを破棄して現状維持し、次のリリースで再挑戦するようリマインダーを設定しましょう。それは失敗ではなく、リスク管理が機能した結果です。

現状維持が正解のとき

アップグレードすべきでないプロジェクトというのは確かに存在し、それははっきり言っておくべきです。リリース済み・リリース間近のゲーム、Webエクスポートが必要なC#プロジェクト、古いハードウェア向けのゲーム、大きく改造したカスタムエンジンビルドのプロジェクト。これらのケースでは、今使っているバージョンがきちんと仕事をしています。アップグレードは道具であって美徳ではありません。ゴールは完成したゲームであって、真新しいエンジンではないのです。

よくある質問

アップグレード後にダウングレードできますか？

確実な方法はありません。新しいエディタがシーンやリソースを再保存した時点で、それらは旧エディタとの後方互換性を失います。安全に戻る唯一の手段はバージョン管理からの復元です。アップグレード用ブランチを作るのはまさにこのためです。

複数バージョンを一気に飛ばしてもいいですか？

小刻みに上げる方が安全です。公式のアップグレードノートはバージョンごとに書かれているため、1ホップずつなら確認事項が明確です。複数バージョンを一気に飛ぶと、それらが全部同時に積み重なり、どの変更が何を壊したのか切り分けにくくなります。

マイナーバージョンでも本当に壊れるんですか？

まれですが、あります。ほとんどのプロジェクトは問題なくマイナーバージョンを上げられますが、コリジョンビットのリセットやシーン固有のレンダリング退行など、コミュニティ報告のあるエッジケースは存在します。だからこそアップグレード前のベースラインテストが重要なのです。「何か壊れたかも？」という感覚を、測定に変えてくれます。

このチェックリストは3.x → 4.xにも使えますか？

チェックリスト自体は使えます。ブランチを切る、旧バイナリを残す、ベースラインを取る、事後テストをする、という流れは同じです。ただし破壊的変更のリストは別物です。3から4への移行ははるかに大規模で（GDScript構文、ノード改名、システムの作り直し）、専用の公式ドキュメントが用意されています。