Godot 3から4への移行：Web書き出しで変わったこと
遊びをつくる執筆にClaudeを使用しています。
Godot 4へ移行しようとしたとき、最初に壁になりやすいのがWeb書き出しです。ゲーム本体の動作確認が終わっても、「ブラウザで動かない」「音が出ない」「画面が真っ黒のまま」といった問題が出やすく、Godot 3のころとは対処法が変わっています。 この記事では、Godot 3と4のWeb書き出しで何が変わったかを整理し、移行時に判断が必要な点と、つまずきやすい手順上の注意をまとめます。ゲームエンジンの基礎知識がある方を想定しています。
この記事の目次
最大の変化：スレッドとSharedArrayBuffer
Godot 4のWeb書き出しが必要とする最も大きな変化は、SharedArrayBufferとCross-Origin Isolation（クロスオリジン分離）への対応です。
Godot 4のWebエクスポートはWasm（WebAssembly）のスレッド機能を使います。スレッドを使うにはブラウザのセキュリティ要件として、サーバーが次の2つのHTTPヘッダーを返す必要があります。
- Cross-Origin-Opener-Policy: same-origin
- Cross-Origin-Embedder-Policy: require-corp
Godot 3ではこの要件がなく、静的なHTMLとJSファイルをただ置けば多くの環境で動いていました。Godot 4では、このヘッダーを返せないホスティング環境では起動すらしません。ローカルでgodot --serveを使った確認時には動くのに、アップロード先で真っ黒になる原因の大半はここにあります。
対処法は二つです。一つは、上記ヘッダーを設定できるサーバーやホスティングサービスを選ぶこと。もう一つは、Godotのエクスポート設定で「スレッドを使わない（Threads Disabled）」を選ぶことです。スレッドなしにするとパフォーマンスは落ちますが、ヘッダー要件がなくなり、静的ホスティングでも動きます。どちらを選ぶかは、ゲームの処理の重さと公開先の環境によって判断してください。
音声の扱いとAutoplay制限
Godot 3でも存在した課題ですが、Godot 4ではエンジン側の音声実装が刷新されたため、Web上でのAutoplay制限への対応をあらためて確認する必要があります。
ブラウザはページ読み込み直後に音声を自動再生することを原則禁止しています。Godot 4のWebエクスポートは、ユーザーの最初の操作（クリック・タップ）を受け取ってからAudioContextを初期化する仕組みになっています。そのため、ゲームの冒頭でユーザー操作なしに音楽を鳴らそうとするスクリプトは、エクスポート後にサイレントになります。
移行時の確認点は次のとおりです。
- タイトル画面やスプラッシュで「クリックして開始」のような操作を挟んでいるか
- _ready()の中で直接AudioStreamPlayer.play()を呼んでいる箇所がないか
- Godot 4で追加されたAudioServerの挙動を想定した実装になっているか
Godot 3から持ち込んだスクリプトをそのまま使う場合、_ready()で音を鳴らしているシーンは特に注意してください。
エクスポートテンプレートとバージョン対応
Godot 4ではエクスポートテンプレート（Export Templates）の仕組みはGodot 3と同様ですが、バージョンの一致がより厳密になっています。
Godot 3では、マイナーバージョンが異なるテンプレートでもある程度動作することがありました。Godot 4では、エンジン本体とテンプレートのバージョンが一致していないと、エクスポート自体が失敗するか、動作が不安定になります。バージョンを上げたときは必ずテンプレートを再ダウンロードしてください。
また、Godot 4のWebテンプレートには「デバッグ用」と「リリース用」の2種類があります。デバッグ用はファイルサイズが大きく、ブラウザのコンソールに詳細なログが出ます。開発中はデバッグ用で動作確認し、公開前にリリース用に切り替える運用が基本です。リリース用はデバッグシンボルが省かれる分、初回ロードの時間が短くなります。
GDExtensionとC#のWeb対応状況
Godot 4で導入されたGDExtension（ネイティブ拡張）は、執筆時点でWebエクスポートへの対応が限定的です。GDExtensionを使ったアドオンやプラグインをプロジェクトに組み込んでいる場合、Webビルドでそのまま動くとは限りません。アドオンの配布ページやGitHubリポジトリで「Web export supported」の記載を確認するのが確実です。
C#（Mono/.NET）についても状況が異なります。Godot 3のMonoビルドはWebエクスポートをサポートしていませんでした。Godot 4ではC#のWebサポートが開発中で、対応状況はバージョンごとに変わっています。C#でゲームを書いている場合は、使用するGodotバージョンのリリースノートで「C# Web export」の状況を必ず確認してください。GDScriptのみで書かれたプロジェクトはこの制限を受けません。
移行前に確認しておく判断チェックリスト
Godot 3のプロジェクトをGodot 4に移行してWebに出す前に、次の点を確認しておくと手戻りを減らせます。
- 公開先のサーバーがCross-Origin Isolationヘッダーを設定できるか できない場合はスレッドなし書き出しを選ぶ。
- ゲームの最初にユーザー操作を挟んでいるか 音声を使うなら必須。
- エクスポートテンプレートのバージョンがエンジンと一致しているか 移行後に再ダウンロードする。
- GDExtensionやC#を使っているか 使っている場合はWebビルドの可否を個別に確認する。
- デバッグ用テンプレートで動作確認してからリリース用に切り替えているか 順序を逆にすると原因調査が難しくなる。
Godot 3からのコンバートツール（godot --convert-3to4相当の機能）はシーンやスクリプトの構文を変換しますが、Web書き出しに関するプロジェクト設定は自動では変わりません。変換後にエクスポートの設定タブを開いて、Webのターゲットが正しく設定されているかを目視で確認してください。
次の行動
公開先が静的ホスティングであれば、まずGodot 4のエクスポート設定でスレッドを無効にしたビルドを試し、ブラウザのコンソールにエラーが出ないかを確認してください。動作が確認できたら、アソバースへのZIPアップロードを使って公開の流れも検証できます。Godot 4の最新のWebエクスポート仕様はGodot公式ドキュメントの「Exporting for the Web」ページで随時確認してください。
参考資料
- Godot Engine 公式ドキュメント「Exporting for the Web」
- Godot Engine 公式ドキュメント「Upgrading from Godot 3 to Godot 4」
- Godot Engine GitHub リリースノート（各バージョン）
