ゲームエンジンのバージョンアップで壊れたプロジェクトの直し方

まず「何が壊れているか」を分類する

バージョンアップ直後にやるべき最初の作業は、エラーを闇雲に直すことではなく、壊れている箇所の種類を分類することです。多くの場合、問題は次の三層のどこかに属します。

ビルド・コンパイルエラーは、コードが構文として通らない、または参照しているクラス・関数が存在しなくなったケースです。エディタやコンパイラが行番号を示してくれるため、場所は特定しやすい反面、同じAPIを使っている箇所が数十か所にわたることもあります。

実行時エラーは、ビルドは通るが実行すると落ちるケースです。型の扱いが厳密になった、デフォルト値が変わった、初期化順序が変わったといった理由が多く、再現条件が限られるため見落としやすいです。

見た目・挙動の劣化は、エラーは出ないが画面がおかしい、物理演算の結果が変わった、UIのレイアウトが崩れたといった問題です。これはエラーログに出ないため、プレイしながら目で確認するしかなく、修正コストが最も読みにくいカテゴリです。

この三層に分けてリストを作ると、修正の順序と工数の見通しが立ちやすくなります。ビルドエラーを先に全部潰してから実行時エラーに進む、という流れが基本です。

移行ガイドとCHANGELOGを最初に読む

多くのエンジンは、メジャーバージョンやマイナーバージョンの区切りに「移行ガイド（Migration Guide）」や「アップグレードノート」を公式ドキュメントとして提供しています。これを読む前に個別のエラーを直し始めると、同じ修正を何度もすることになります。

移行ガイドで確認すべき主な項目は以下のとおりです。

• 廃止されたAPI（Deprecated → Removed）：古いバージョンで「非推奨」とマークされていたAPIが今回削除された場合、代替APIへの置き換えが必要です。
• シグネチャ変更：関数名は同じでも引数の型・順序・数が変わっていることがあります。
• デフォルト動作の変更：物理エンジンの重力係数、レンダリングの色空間（リニア・ガンマ）、入力イベントの処理順などはデフォルト値が変わると全体の挙動に影響します。
• 非推奨ノード・コンポーネントの削除：GodotのKinematicBody→CharacterBody3Dのように、ノードの種類ごと置き換えが必要になることがあります。

CHANGELOGはすべての変更を羅列したものなので、移行ガイドが別にある場合はそちらを優先し、CHANGELOGは細部の確認に使うと効率的です。

修正の手順：小さく直して都度確認する

移行ガイドを読んだら、いよいよ修正作業に入ります。ここで失敗しやすいのは、一度に大量の修正をまとめてコミットしてしまうことです。どこで新たなバグが混入したか追跡できなくなるため、一つの変更単位ごとにビルド・実行して確認する習慣を守ることが重要です。

推奨する作業順序

1. バージョンアップ前の状態をブランチまたはバックアップとして保存する。Gitを使っているならアップデート前のコミットをタグで残します。使っていない場合はプロジェクトフォルダをまるごとコピーしておきます。これが後退できる安全網になります。

1. 自動移行ツールがあれば先に実行する。UnityのAPI Updater、GodotのProject Converterなど、エンジン付属の変換ツールは機械的な置き換えを自動でやってくれます。ただし完璧ではないため、実行後にログを必ず確認します。

1. ビルドエラーを上から順に解決する。最初のエラーが後続のエラーを連鎖的に引き起こしていることが多いため、1件ずつ直してビルドし直す方が全体として速い場合があります。

1. 実行時エラーはログを再現条件とセットで記録する。「どの操作をしたときに」「どのログが出たか」をメモしながら直すと、修正の見落としを防げます。

1. 挙動の劣化は最後にまとめて確認する。見た目の問題は機能が動いてから手をつける方が、修正の影響範囲を絞りやすいです。

よくある詰まりポイントと対処

「非推奨APIを使っているがまだ動く」ケース：警告は出るが動く、という状態は修正を後回しにしたくなる場面ですが、次のマイナーアップデートで削除される可能性があります。移行ガイドに「次バージョンで削除予定」と書いてある場合は、このタイミングで置き換えておく方が安全です。

サードパーティのプラグインやアセットが対応していないケース：自分のコードではなく使っているプラグインが原因でビルドが通らないことがあります。そのプラグインの最新バージョンが対象エンジンバージョンに対応しているか、リポジトリのIssueやリリースノートを確認します。対応版がなければ、そのプラグインを使わずに済む代替手段を探すか、自分でフォークして修正するかを判断します。

シェーダーが真っ黒になるケース：レンダリングパイプラインの変更（例：UnityのBuilt-inパイプラインからURPへの移行）や、GLSLのバージョン変更に伴うシェーダー文法の違いが原因です。移行ガイドのレンダリング関連セクションを確認し、シェーダーファイルを個別に見直す必要があります。

物理演算の結果が変わったケース：重力定数、ステップ間隔（fixed delta time）、衝突判定の精度が変わると、ジャンプの高さや当たり判定のズレとして現れます。プロジェクト設定の物理関連パラメーターを新旧で比較し、必要に応じて手動で値を合わせます。

「直すか・戻すか」の判断基準

バージョンアップの対応コストが予想より大きい場合、現行バージョンに留まる選択も現実的です。以下の基準で判断すると整理しやすいです。

• セキュリティ上の脆弱性修正がアップデートに含まれる場合は、Web公開を前提とするゲームでは対応を優先する理由になります。
• 使いたい新機能がアップデートにある場合は、移行コストと新機能の開発効率向上を比較します。
• プロジェクトが完成間近で安定している場合は、リリースまで現行バージョンを維持し、次のプロジェクトから新バージョンを使う判断も合理的です。

現行バージョンに留まる場合でも、移行手順のメモだけは残しておくと、将来の対応が楽になります。

次の行動

手元のプロジェクトが影響を受けたバージョンの移行ガイドをまだ読んでいなければ、まずそこから始めてください。修正が済んだプロジェクトをWeb向けにビルドして公開できる状態になったら、アソバースへの投稿も選択肢の一つとして検討してみてください。

参考資料

• Godot Engine 公式ドキュメント「Upgrading from Godot 4.x to Godot 4.y」
• Unity 公式ドキュメント「Upgrading Unity projects」
• Phaser 公式サイト「Migration Guide」
• MDN Web Docs「WebGL best practices」