godot-platform-web

絶対に行わないこと（上級者向け Web ルール）

永続化とストレージ

• 永続的な Web 保存に FileAccess だけを絶対に使わないでください — web_local_storage_wrapper.gd（JavaScriptBridge 経由の localStorage／IndexedDB）を優先してください。
• localStorage が永続的だと絶対に考えないでください — 本番環境ではクラウド保存へのフォールバックを実装してください。

レンダリングとロジック

• Web で Forward+ レンダラーを絶対に使わないでください — Compatibility（WebGL 2.0）を使用してください。
• ブラウザーのイベントループを絶対にブロックしないでください — 長時間の同期処理は「ページを終了」させます。利用可能な場合は await／スレッドワーカーを使用してください。
• COOP/COEP を絶対に無視しないでください — スレッド／SharedArrayBuffer にはクロスオリジン分離が必要です。

UX とセキュリティ

• タブのフォーカス喪失を絶対に忘れないでください — visibilitychange で音声を一時停止してください。
• クリックなしでフルスクリーン／マウスロックを絶対に開始しないでください — ユーザージェスチャー内で実行する必要があります。
• HTML シェルで絶対パスを絶対に使わないでください — サブディレクトリでホストする場合は相対パスを使用してください。

---

ホスト側チェックリスト（手順）

1. HTTPS — 多くのブラウザー API（クリップボード、一部のストレージポリシー、安全なコンテキスト）で必要です。
2. COOP / COEP — スレッド／SharedArrayBuffer を有効にする場合は分離ヘッダーを配信してください（exporting-for-web ドキュメントを参照）。
3. 相対シェルパス — カスタムの index.html／PCK/WASM URL は、/game/ のサブパスで動作するよう相対パスにする必要があります。
4. beforeunload — 未保存の進行状況がある場合は、web_navigation_guard.gd を接続してください。
5. Compatibility レンダラー＋テクスチャ圧縮 — デスクトップブラウザーでは、適切に S3TC/BPTC を使用してください。パーティクル数／描画予算は低く抑えてください。

利用可能なスクリプト

必須：保存には web_local_storage_wrapper.gd を読み込んでください — JavaScriptBridge.eval("localStorage.setItem...") の文字列レシピを貼り付けないでください。

web_local_storage_wrapper.gd

get_interface ＋ JSON による、クォータに安全な localStorage（eval 文字列補間は使用しません）。

web_javascript_bridge_callback.gd

create_callback による双方向 JS↔GD 通信（コールバック参照を有効なまま保持してください）。

web_responsive_canvas_adaptor.gd

ブラウザービューポートに合わせてキャンバスをリサイズします。

web_browser_input_guard.gd

コンテキストメニュー／スペースバーによるスクロールのデフォルト動作を抑制します。

web_resource_lazy_loader.gd

リモート PCK／リソースの取得パターンです。

web_clipboard_interface.gd

Navigator API を介した非同期クリップボード機能です。

web_visibility_auto_pause.gd

タブが非表示になったときにエンジン／音声を一時停止します。

web_navigation_guard.gd

未保存の進行状況を保護する beforeunload ガードです。

web_external_url_opener.gd

noopener を指定して window.open を実行します。

web_performance_profiler.gd

VRAM／描画統計を JS コンソールに出力します。

scripts/ にあるその他のスクリプト

• platform_web_patterns.gd — 各種 Web 機能のゲートです。
• web_bridge_sync.gd — 構造化ブリッジ同期ヘルパーです。
• web_json_rpc_bridge.gd — JSON-RPC create_callback ブリッジです（参照を有効なまま保持してください）。

上級者向けの理由（重要）

注意： JavaScriptBridge.eval("localStorage.setItem('%s')" % data) で絶対に永続化しないでください — インジェクション／エスケープのバグにつながります。web_local_storage_wrapper.gd を使用してください。

• PWA の更新 — pwa_needs_update() の場合、pwa_update_available → pwa_update() を実行します。
• WebGPU — Godot 4.x の Web レンダラーではありません。Compatibility（WebGL 2.0）を提供してください。
• JSON-RPC ホストページ — 構造化された双方向ブリッジ：web_json_rpc_bridge.gd。

詳細（必要に応じて読み込み）

PWA のライフサイクル、JSON-RPC ブリッジ、localStorage のアンチパターン、サイズ調整項目については、references/web-elite-patterns.md を参照してください。

ローディングシェル（カスタム HTML）

<div id="loading-screen">
    <div class="progress-bar"><div id="progress" style="width: 0%"></div></div>
    <p id="status-text">Loading...</p>
</div>
<script>
const engine = new Engine(CONFIG);
engine.startGame({
    onProgress: function(current, total) {
        const percent = Math.floor((current / total) * 100);
        document.getElementById('progress').style.width = percent + '%';
        document.getElementById('status-text').innerText = `Loading ${percent}%`;
    }
}).then(() => {
    document.getElementById('loading-screen').style.display = 'none';
});
</script>

機能ゲート

if OS.has_feature("web"):
    # Web-only: storage wrapper, visibility pause, navigation guard
    pass

サイズ／パフォーマンス調整

[rendering]
textures/vram_compression/import_s3tc_bptc=true
textures/vram_compression/import_etc2_astc=true

• ミドルレンジのブラウザーで約60 FPSを目指し、パーティクル、ドローコール、大容量テクスチャを削減します。
• ドキュメント／ソースに除外フィルターを適用し、ダウンロードサイズを実用的な範囲（約50MB）に抑えます。

PWA 更新フック

func _ready() -> void:
    if OS.has_feature("web"):
        JavaScriptBridge.pwa_update_available.connect(_on_pwa_update)

func _on_pwa_update() -> void:
    if JavaScriptBridge.pwa_needs_update():
        JavaScriptBridge.pwa_update()

参考資料

段階的開示：特定のAPIを調査するときに限り、公式ドキュメントのリンクを開きます。 作業を関連する領域の担当者に振り分ける際は、関連スキルを読み込みます。スキルの全体を事前に読み込まないでください。

公式ドキュメント

• Web向けのエクスポート — エクスポートプリセット、Compatibility／WebGLの制限、およびスレッド／SharedArrayBuffer にCOOP／COEP分離が必要な理由。
• Webエクスポート — ブラウザー専用APIを組み込む前に確認する、HTML5ホスティングの制約に関するプラットフォーム概要。
• JavaScriptBridgeシングルトン — 双方向GD↔JSブリッジにおける eval、get_interface、create_callback の仕様。
• Webエクスポート用のカスタムHTMLページ — ビルドをサブディレクトリで動作させるための相対アセットパスとカスタム読み込みシェル。
• HTML5 shellクラスリファレンス — カスタム読み込み画面で使われる Engine／startGame の進捗コールバック。
• JavaScriptBridge — PWA更新シグナルに加え、JSコールバックの参照を保持する必要があるクリップボード／ダウンロード用ヘルパー。
• 3つのレンダリング方式の概要 — WebエクスポートでForward+ではなくCompatibility（WebGL 2.0）を出荷すべき理由。
• Godotプロジェクトのファイルパス — ブラウザーのサンドボックスでは user://／FileAccess による永続化が不安定で、localStorage／IndexedDB を使うべき理由。
• ゲームの保存 — ブラウザーのストレージAPIでラップする前に、保存データをシリアライズし、バージョンを付与します。
• 複数の解像度 — ストレッチ／アスペクト比／コンテンツスケールと、レスポンシブなWebビューポート向けのHTMLキャンバスのリサイズ方針。
• 終了リクエストの処理 — タブの visibilitychange や beforeunload のガードに対応する、一時停止／再開のライフサイクル。
• GPUの最適化 — WebGLのフレーム時間を大きく左右する、ドローコール、テクスチャ、パーティクルの予算。

関連スキル

前提条件

• godot-project-foundations — すべてのHTML5エクスポート分岐が依存する機能タグ（web）、Compatibilityレンダラーのデフォルト設定、ディスプレイのストレッチ設定。
• godot-input-handling — ブラウザーのデフォルト動作（コンテキストメニュー、スペースキーによるスクロール）を抑制したり、キャンバスのフォーカスを再割り当てしたりする前に確認するInputEventの所有権。
• godot-save-load-systems — バージョン管理されたセーブデータの所有権とクラウドへのフォールバック用フック。localStorage ラッパーで独自にその場しのぎの実装をしないようにします。

補完

• godot-platform-mobile — 同じビルドをモバイルブラウザーでプレイする際に重なる、タッチ操作やライフサイクルのパターンです。
• godot-platform-desktop — 1つのプロジェクトでデスクトップとウェブを両方対象にする場合に、ネイティブのデスクトップ向けパスを健全に保ちます。
• godot-audio-systems — タブが非表示になったときにバックグラウンド再生を防ぐための、バスや音声の制御です。
• godot-performance-optimization — Compatibility と圧縮を適用しても WebGL の予算内で 60 FPS に届かない場合の、プロファイリングと CPU／GPU の負荷削減です。
• godot-ui-containers — デスクトップやスマートフォンのウェブ環境でブラウザーのキャンバスサイズが変わっても、読みやすさを保つコントロールのレイアウトです。
• godot-autoload-architecture — JavaScriptBridge マネージャー、ストレージラッパー、常時有効な表示状態ガードのためのシングルトンの配置先です。
• godot-multiplayer-networking — ゲームをブラウザーでホストする際に LAN 前提の構成に代わる、WebSocket／WebRTC ピアです。
• godot-resource-data-patterns — ウェブ上でのリモート遅延読み込み取得フローで使用する PCK／リソースのパッキングに関する契約です。

下流／利用側

• godot-export-builds — ブラウザー API と Compatibility の設定を確定した後の、CI プリセット、成果物のホスティング、サイズ制限です。

マスター

• godot-master — 関連する領域と並べてこのプラットフォームスキルを見つけるための、ライブラリルーター兼ミラー化されたモジュールのエントリーポイントです。