How to Upgrade Godot Versions Safely Godotのバージョンを安全に上げる方法

Introduction

はじめに

Upgrading your game engine mid-project is one of the scariest routine decisions in game development. A new Godot version might fix the bug that's blocking you — or it might silently break a scene you shipped six months of work into. That's why experienced developers in the Godot community treat a version upgrade as a risk decision, not a routine chore.

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

This guide is not "always upgrade" advocacy. It's a risk-management checklist for Godot 4.x-to-4.x migration: how to decide whether to upgrade at all, how to prepare so you can back out safely, what is known to break between versions, and — most importantly — how to actually verify that nothing broke.

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

Should You Upgrade at All?

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

Before touching anything, answer this question honestly. Upgrading has a real cost (migration work + re-testing), so the benefit needs to be equally real.

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

Upgrade if…

上げるべきケース

• A bug fixed upstream is blocking you. If your issue is already fixed in a newer release, upgrading is usually cheaper than working around it forever. 本家で修正済みのバグに悩まされている。 困っている問題が新しいリリースで既に直っているなら、永久に回避策を抱え続けるより上げてしまう方が安いことが多いです。
• A new feature materially benefits your game. Not "sounds nice" — something that saves you real development time or unlocks a design you need. 新機能がゲームに実質的なメリットをもたらす。 「良さそう」レベルではなく、実際の開発時間を節約できる、あるいは必要なデザインが実現できる機能であること。
• Your development timeline is long. If your project will take years, small frequent hops (one minor version at a time) are far safer than one giant hop at the end. The gap only grows. 開発期間が長い。 数年がかりのプロジェクトなら、マイナーバージョンを1つずつこまめに上げる方が、最後に一気に大ジャンプするよりはるかに安全です。差分は放っておくと広がる一方です。

Don't upgrade if…

上げるべきでないケース

• You're close to release. The weeks before shipping are the worst possible time to introduce engine-level changes. Ship first, upgrade after. リリースが近い。 出荷直前の数週間は、エンジンレベルの変更を入れる最悪のタイミングです。まずリリースし、上げるのはその後に。
• You need C# + Web export. Web export for C# projects is still unavailable in Godot 4.x (tracked in godot#70796). If you rely on it in 3.x, moving to 4.x removes it. C#＋Webエクスポートが必要。 C#プロジェクトのWebエクスポートはGodot 4.xでは依然として利用できません（godot#70796で追跡中）。3.xでこれに依存しているなら、4.xに移ると失われます。
• You target old hardware. Godot 3.x runs on OpenGL 2-class GPUs; Godot 4's Compatibility renderer requires OpenGL 3.3 / WebGL 2. If your audience is on old machines, 3.x may genuinely be the right engine. 古いハードウェアがターゲット。 Godot 3.xはOpenGL 2世代のGPUで動きますが、Godot 4のCompatibilityレンダラーはOpenGL 3.3 / WebGL 2が必須です。プレイヤー層が古いマシンを使うなら、3.xに留まるのが本当に正解ということもあります。
• Critical addons aren't updated yet. If a plugin your project depends on doesn't support the new version, you inherit its migration problem on top of yours. 重要なアドオンが未対応。 プロジェクトが依存するプラグインが新バージョン未対応なら、自分の移行作業に加えてそのアドオンの問題まで背負うことになります。

Before You Upgrade — Preparation Checklist

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

Every step here exists so that if the upgrade goes wrong, you lose an afternoon, not a project.

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

1. Commit everything and create an upgrade branch. Never upgrade the only copy of your project. A dedicated branch (or a full copy of the folder if you don't use git) means reverting is one command, not a recovery mission. すべてコミットし、アップグレード用ブランチを作る。 プロジェクトの唯一のコピーを直接アップグレードしてはいけません。専用ブランチ（gitを使っていないならフォルダの完全コピー）があれば、巻き戻しはコマンド1つで済みます。
2. Record your current exact version (e.g. which 4.x.y build, standard or .NET). You'll need it if you have to go back or file a bug report. 現在の正確なバージョンを記録する（4.x.yのどのビルドか、通常版か.NET版か）。戻すときやバグ報告のときに必要になります。
3. Keep the old editor binary. Godot versions install side-by-side — the editor is a single executable, so keeping both costs nothing and lets you open the old branch with the old editor at any time. 旧バージョンのエディタ実行ファイルを残しておく。 Godotは複数バージョンを並存できます。エディタは単一の実行ファイルなので、両方持っておくコストはゼロですし、いつでも旧ブランチを旧エディタで開けます。
4. List your addons and check each one's supported versions. Go through addons/, note where each came from, and confirm on its repo or Asset Library page that it supports the target version. アドオンを列挙し、それぞれの対応バージョンを確認する。 addons/の中身を洗い出し、入手元を控え、リポジトリやAsset Libraryのページで移行先バージョンへの対応を確認します。
5. Read the official upgrade notes for every version you hop across. The official migration guides are written per-version — if you go from 4.2 to 4.4, read both the 4.3 and 4.4 notes. 跨ぐバージョンすべての公式アップグレードノートを読む。 公式の移行ガイドはバージョンごとに書かれています。4.2から4.4に上げるなら、4.3と4.4の両方のノートを読んでください。
6. Capture "known-good" evidence. Take screenshots of your key scenes, record a short gameplay clip, or — best of all — write automated test scenarios (more on this in the testing section below). After the upgrade, "does it look and behave the same?" is only answerable if you captured what "same" means beforehand. 「正常な状態」の証拠を残す。 主要シーンのスクリーンショット、短いプレイ動画、あるいはベストなのは自動テストシナリオの作成です（後述のテストの章で詳しく扱います）。アップグレード後に「見た目も挙動も同じか？」に答えられるのは、事前に「同じ」の基準を記録しておいた場合だけです。

The Upgrade Procedure

アップグレードの手順

1. Open the branch copy with the new editor. The upgrade branch, not main. The new editor will offer to convert/reimport — accept. 新しいエディタでブランチ側のコピーを開く。 mainではなくアップグレード用ブランチを開きます。新エディタが変換・再インポートを提案してくるので受け入れます。
2. Let it reimport. The .godot folder regenerates from scratch. The first import can take a while on large projects, and the warnings it prints during that first pass are usually harmless. 再インポートを待つ。 .godotフォルダはゼロから再生成されます。大きなプロジェクトでは初回インポートに時間がかかりますが、その最初のパスで出る警告はたいてい無害です。
3. Check the Output and Debugger panels for new errors. Compare against the errors you already had before (you did note them, right?). New errors are the migration's to-do list. OutputパネルとDebuggerで「新しい」エラーを確認する。 アップグレード前からあったエラーと比較します（事前に控えてありますよね？）。新規のエラーが移行作業のToDoリストになります。
4. Play through the critical paths. Start a new game, load a save, run the core gameplay loop, open the main menus. Editor-time errors are the easy ones — runtime behavior is where regressions hide. クリティカルパスを実際にプレイする。 ニューゲーム開始、セーブのロード、コアゲームループ、主要メニューの表示。エディタ上のエラーは簡単な方で、リグレッションが潜むのは実行時の挙動です。
5. Run your test scenarios (the ones you prepared before upgrading) and compare against the baseline. テストシナリオを実行する（アップグレード前に用意したもの）。ベースラインと結果を比較します。
6. Diff the working tree in git before committing. The editor rewrites files during migration: project.godot gets new config values, .tscn files get resaved, and new .uid files may appear. Review the diff so you know exactly what changed — then commit it as a single, clearly labeled migration commit. コミット前にgitで作業ツリーの差分を確認する。 移行中、エディタはファイルを書き換えます。project.godotに新しい設定値が入り、.tscnが再保存され、新しい.uidファイルが現れることもあります。何が変わったかを差分で正確に把握してから、移行コミットとして1つの分かりやすいコミットにまとめてください。

Known Breaking Points Between 4.x Versions

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

Minor versions of Godot 4 are mostly compatible, but "mostly" is doing some work in that sentence. Here are the changes most likely to bite, based on official notes and community reports.

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

4.2 → 4.3: TileMap deprecated in favor of TileMapLayer

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

Godot 4.3 deprecated the TileMap node in favor of TileMapLayer — one node per layer instead of layers inside one node. Existing TileMaps keep working, but new code and new projects should use TileMapLayer. The editor includes an extraction tool: select your TileMap, open the TileMap bottom panel, click the toolbox icon in the top-right corner, and choose "Extract TileMap layers as individual TileMapLayer nodes".

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

4.3 → 4.4: .uid files and GDScript additions

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

• Godot 4.4 added .uid companion files next to scripts and shaders. Commit them to version control — deleting them can break uid:// references wherever those are used (the official 4.4 upgrade notes cover related changes such as @export_file paths becoming uid://). They look like clutter; they are not. Godot 4.4から.uidコンパニオンファイルがスクリプトやシェーダーの隣に生成されます。必ずバージョン管理にコミットしてください。削除すると、uid://参照を使っている箇所で参照が壊れる可能性があります（@export_fileのパスがuid://になる等の関連変更は公式の4.4アップグレードノートに記載があります）。ゴミに見えますが、ゴミではありません。
• Typed Dictionaries and other GDScript additions are backward-compatible — your old code keeps running. But addons that adopt the new features stop working on older versions, so addon behavior may differ across the hop. 型付きDictionaryなどGDScriptの追加機能は後方互換で、既存コードはそのまま動きます。ただし新機能を採用したアドオンは旧バージョンでは動かなくなるため、バージョンを跨ぐとアドオンの挙動が変わる可能性があります。

General: subtle changes between any minor versions

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

Rendering tweaks between minor versions can subtly change how your game looks — lighting, anti-aliasing, 2D snapping. Community discussions also include scene-specific regressions that don't reproduce in fresh projects: a scene misbehaves after the upgrade, but rebuilding the same scene in a clean project works fine. If something breaks inexplicably, try this isolation sequence: close the editor, delete the .godot folder, reopen and let everything reimport; if the problem persists, reproduce the scene in a clean project to determine whether the culprit is your project's accumulated state or an actual engine change.

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

3.x → 4.x is a different beast

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

Everything above is about 4.x-to-4.x hops. Migrating from Godot 3 to Godot 4 is a different category entirely: GDScript syntax changed, many nodes were renamed, and TileMap, physics, and rendering were reworked from the ground up — and most addons need dedicated 4.x versions. For large 3.x projects, the migration cost can approach the cost of a rebuild, and whether it's worth it is a genuinely per-project decision. That migration deserves (and has) its own documentation; this article won't pretend to cover it.

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

Testing After the Upgrade — the Actual Bottleneck

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

Here's the honest part: the #1 reason developers avoid upgrading isn't the migration itself — it's that verifying "nothing broke" by hand is expensive. A full manual regression pass on a mid-sized game can eat a weekend. And a runtime bug your players find after release is far worse than any editor error, because now it's a reputation problem, not a to-do item.

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

Minimum manual smoke test

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

• Start a new game from the title screenタイトル画面からニューゲームを開始する
• Load an existing save file既存のセーブデータをロードする
• Play the core gameplay loop for a few minutesコアゲームループを数分プレイする
• Check the UI at each resolution and window mode you supportサポートする各解像度・ウィンドウモードでUIを確認する

Automate the before/after comparison

前後比較を自動化する

The manual pass doesn't scale, and it can't tell you a sprite shifted by two pixels. This is exactly what Godot QA was built for — a free, MIT-licensed, open-source test runner for Godot. The workflow fits version upgrades perfectly:

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

1. Before upgrading, write (or record) scenario JSON files covering your critical paths, and capture baseline screenshots on the old version.アップグレード前に、クリティカルパスをカバーするシナリオJSONを書き（または記録し）、旧バージョンでベースラインのスクリーンショットを取得します。
2. After upgrading, run the exact same scenarios plus a pixel-diff against the baselines on the new version.アップグレード後に、新バージョンでまったく同じシナリオを実行し、ベースラインとのピクセル差分を取ります。
3. Failures pinpoint regressions in minutes instead of a weekend of manual replay.失敗箇所がそのままリグレッションの位置を示すので、週末まるごとの手動プレイが数分で片付きます。

A scenario is just a JSON list of steps — inputs, waits, assertions, screenshots:

シナリオはステップ（入力・待機・アサーション・スクリーンショット）を並べた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"}
  ]
}

The same scenario format is what Godot MCP Pro's run_test_scenario tool uses, so an AI assistant connected to your editor can write these scenarios for you.

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

If Something Breaks

壊れてしまったら

1. Bisect by version. If you hopped multiple minor versions, retry the upgrade one minor version at a time to find exactly where it broke. That narrows the search from "everything" to one changelog. バージョンで二分探索する。 複数のマイナーバージョンを一気に跨いだ場合は、1バージョンずつ上げ直してどこで壊れたかを特定します。調査範囲が「全部」から1つのchangelogに絞れます。
2. Clear the .godot folder and let the project reimport. Stale import caches cause a surprising share of post-upgrade weirdness. .godotフォルダを削除して再インポートさせます。アップグレード後の謎の不具合のうち、意外な割合が古いインポートキャッシュが原因です。
3. Search the engine's GitHub issues for your exact error message. If it's a real regression, someone has often already reported it — sometimes with a workaround. エラーメッセージそのままでエンジンのGitHub issuesを検索する。 本物のリグレッションなら誰かが報告済みのことが多く、回避策が書かれていることもあります。
4. Check whether an addon is the culprit. Disable your addons in Project Settings and retest. If the problem vanishes, it's the addon — check for an updated release before blaming the engine. アドオンが原因でないか確認する。 プロジェクト設定でアドオンを無効にして再テストします。問題が消えたら犯人はアドオンです。エンジンを疑う前に、アドオンの更新版が出ていないか確認しましょう。
5. Accept that staying on the old version is a valid outcome. If the fix cost exceeds the upgrade's benefit, revert the branch, stay put, and set a reminder to retry when the next release lands. That's not failure — that's the risk management working. 旧バージョンに留まることも正当な結論だと認める。 修正コストがアップグレードのメリットを上回るなら、ブランチを破棄して現状維持し、次のリリースで再挑戦するようリマインダーを設定しましょう。それは失敗ではなく、リスク管理が機能した結果です。

When Staying Put Is the Right Call

現状維持が正解のとき

Some projects should simply not upgrade, and that deserves saying plainly: shipped or nearly-shipped games, C# projects that need web export, games targeting old hardware, and projects on heavily modified custom engine builds. In all of these, the version you're on is doing its job. Upgrading is a tool, not a virtue — the goal is a finished game, not a fresh engine.

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

FAQ

よくある質問

Can I downgrade after upgrading?

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

No, not reliably. Once the new editor resaves your scenes and resources, they aren't backward-compatible with older editors. The only safe way back is restoring from version control — which is exactly why the upgrade branch exists.

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

Should I skip several versions at once?

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

Small hops are safer. The official upgrade notes are written per-version, so each hop has a known checklist — a multi-version jump stacks all of them at once and makes it harder to tell which change broke what.

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

Do minor versions really break things?

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

Rarely, but yes. Most projects hop minor versions without trouble, but community-reported edge cases exist — collision bits resetting, scene-specific rendering regressions. That's precisely why baseline tests before the upgrade matter: they turn "did anything break?" from a feeling into a measurement.

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

Does this checklist apply to 3.x → 4.x?

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

The checklist itself, yes — branch, keep the old binary, capture baselines, test after. The breaking-points list, no: the 3-to-4 migration is far larger (GDScript syntax, renamed nodes, reworked systems) and has its own dedicated official documentation.

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