godot-export

Godot エクスポートとビルド（4.x）

エクスポートプリセットとコマンドラインを使って、プロジェクトを実行可能なプラットフォーム別ビルドにし、Web／専用サーバー特有の注意点にも対処します。対象は Godot 4.7 です。

使用する場面

• 配布可能なビルドを作成するときに使用します。エクスポートテンプレートのインストール、エクスポートプリセットの作成／編集、エディターまたはヘッドレス CLI（CI）からのエクスポート、Web（HTML5）や専用サーバーへのエクスポートのトラブルシューティングが対象です。

使用しない場面： ストアへの公開手順 → steam-publish／itch-publish。サーバーのネットワークコード → godot-multiplayer（このスキルではヘッドレスでのビルドを扱います）。

基本的なワークフロー

1. エンジンのバージョンに合ったエクスポートテンプレートをインストールします。 エディターメニューから Manage Export Templates を選択してダウンロードするか、.tpz ファイルをオフラインでインストールします。バージョンはエディターと完全に一致している必要があります。
2. エクスポートプリセットを追加します。 Project > Export でプラットフォーム（Windows Desktop、macOS、Linux、Web、Android、iOS）を選び、エクスポート先のパス、アイコン、機能、リソースのインクルード／除外フィルターを設定します。プリセットは export_presets.cfg に保存されます。
3. エディターからエクスポートします。 Export Project（リリース版）または Export PCK/ZIP を使用します。
4. または、CLI からヘッドレスでエクスポートします。 自動化／CI には --export-release "<preset name>" <output path> を使用します。
5. プラットフォームごとの要件： Web でスレッドを使うにはクロスオリジン分離（COOP/COEP）が必要です。Android には SDK／キーストアが必要です。macOS／iOS では配布時に署名が必要です。
6. 配布前に対象環境でビルドのスモークテストを行います。 エクスポートしたビルドでは res:// は読み取り専用です。書き込みには user:// を使用します。

パターン

1. ヘッドレス CLI エクスポート（CI 向け）

# Preset name must match exactly what's in Project > Export (quote it).
# Run from the project directory (where project.godot lives).
godot --headless --export-release "Windows Desktop" build/windows/game.exe
godot --headless --export-release "Linux/X11"       build/linux/game.x86_64
godot --headless --export-release "Web"             build/web/index.html

# Debug build (includes debug symbols / remote debug):
godot --headless --export-debug "Windows Desktop" build/windows/game_debug.exe

# Export only the data pack (no executable):
godot --headless --export-pack "Linux/X11" build/game.pck

2. プロジェクトをヘッドレスで実行する（専用サーバー／テスト）

# No window/GPU — for a server build or automated runs.
godot --headless --path . res://server_main.tscn
# Quit after N main-loop iterations (frames, NOT seconds) — handy for a headless smoke test:
godot --headless --path . --quit-after 600

3. 実行時にビルドのコンテキストを判定する

func _ready() -> void:
    if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":
        _start_server_only()          # skip rendering/UI on a headless server
    if OS.has_feature("web"):
        _apply_web_tweaks()
    # Custom feature tags (added per preset) are also queryable:
    # if OS.has_feature("demo"): limit_content()

4. エクスポート後も保持される書き込み先を選ぶ

# res:// is READ-ONLY in exported games. Always write to user://.
func save_path() -> String:
    return "user://savegame.tres"     # resolves to the OS app-data dir

func _ready() -> void:
    print(OS.get_user_data_dir())     # where user:// actually lives

注意点

• 「エクスポートテンプレートが見つかりません」。 テンプレートはエディターのバージョン（ベータ版／リリース候補を含む）と完全に一致している必要があります。Godot のアップグレード後に Manage Export Templates から再ダウンロードしてください。
• CLI のプリセット名が一致しない。 プリセット名が "Windows Desktop" の場合、--export-release "Windows" は失敗します。名前では大文字と小文字、スペースが区別されるため、引用符で囲んでください。
• Web ビルドで空白のページが表示される／スレッドエラーが発生する。 スレッドを使用する HTML5 ビルドでは、サーバーが Cross-Origin-Opener-Policy: same-origin と Cross-Origin-Embedder-Policy: require-corp を送信する必要があります（SharedArrayBuffer 用のクロスオリジン分離）。file:// で開かず、HTTP(S) 経由で配信する必要があります。itch.io には「SharedArrayBuffer support」の切り替え設定があります。
• 実行時に res:// への書き込みが失敗する。 エクスポートでは読み取り専用で、パックされています。user:// を使用してください。
• ビルドにリソースが含まれていない。 外部の .json、.txt など、リソースではないファイルは自動的に含まれません。プリセットの Resources > Filters to export non-resource files で追加してください（例：*.json）。
• Android のエクスポートにはセットアップが必要です。 Editor Settings で Android SDK／JDK のパスを設定し、デバッグ用またはリリース用の キーストア を用意します。ネットワーク接続が必要なゲームでは INTERNET 権限も必要です。
• macOS／iOS での配布には署名／公証が必要です。 署名されていない macOS アプリは Gatekeeper によってブロックされます。
• デバッグ版とリリース版。 --export-debug を使うとリモートデバッグとデバッグチェックが有効になります。配布には --export-release を使用してください。

参考資料

• export_presets.cfg の構造、有用な CLI フラグ、カスタム機能タグ、PCK／拡張パッチ、暗号化、プラットフォームごとのセットアップ（Android キーストア、macOS の署名、Web ヘッダー）については、references/presets-and-cli.md を参照してください。

関連スキル

• godot-multiplayer — ヘッドレスでエクスポートする専用サーバーのコードです。
• steam-publish／itch-publish — ビルドをプレイヤーに届ける方法です。
• prototype-fast／game-jam — 共有用の手早い Web／デスクトップビルドです。