godot-adapt-desktop-to-mobile

対応：デスクトップからモバイルへ

デスクトップゲームをモバイルプラットフォームに移植するための専門ガイダンスです。

絶対にしてはいけないこと

• マウスの位置を直接使用しないでください — タッチには「ホバー」状態がありません。mouse_motion を screen_drag に置き換え、InputEventScreenTouch.pressed を確認してください。
• 小さな UI 要素をそのまま使わないでください — Apple HIG ではタッチターゲットを最低 44pt にする必要があります。Android Material では 48dp です。ボタンを 2～3 倍に拡大してください。
• 指による遮蔽を忘れないでください — ユーザーの指で半径 50～100px の範囲が隠れます。重要な情報はタッチ操作部の下ではなく、上に配置してください。
• バックグラウンドで最大パフォーマンスのまま実行しないでください — バックグラウンドでバッテリーを消耗するアプリは、モバイル OS に終了されます。アプリのフォーカスが失われたら物理演算を一時停止し、FPS を 1～5 に下げてください。
• デスクトップ専用の機能を使わないでください — マウスホバー、右クリック、キーボードショートカット、スクロールホイールはモバイルにはありません。タッチ操作で代替できる方法を用意してください。

---

利用可能なスクリプト

必須：対応するパターンを実装する前に、適切なスクリプトを読んでください。ジョイスティック／ジェスチャー／UI のチュートリアルをインラインで貼り付けないでください。

dynamic_joystick_spawner.gd

移動スティックには必須 — ユーザーが画面の左半分にタッチした位置にジョイスティックが表示されます（固定位置の方式よりもこちらを優先してください）。

virtual_joystick.gd

固定ベースのスティック Control です — UI アートで静的なスティック領域が必要な場合に使用してください。それ以外の場合は dynamic_joystick_spawner を優先してください。

gesture_combo_system.gd

スワイプ／ピンチには必須 — 継続時間／距離／マルチタッチ比率をシグナルに変換します。

mobile_ui_adapter.gd

Control の再マッピングには必須 — 親指が届く範囲と画面密度に合わせて、デスクトップの HUD を拡大縮小し、アンカーを再配置します。

resolution_scaler.gd

2D UI の鮮明さを保ちながら 60FPS を維持できるよう、scaling_3d_scale を動的に調整します。

battery_saver_mode.gd

必須 — NOTIFICATION_APPLICATION_PAUSED に応じて Engine.max_fps = 1 に設定し、物理演算を一時停止します。

ui_safe_area_margins.gd

ノッチ／パンチホールに合わせて DisplayServer.get_display_safe_area() の余白を設定します。

touch_camera_pan_zoom.gd

1 本指のパン操作と 2 本指のピンチ操作に対応した Camera2D です。

haptic_feedback_manager.gd

Input.vibrate_handheld と iOS プラグインのフックパターンです。

mobile_shader_fallback.gd

性能の低いモバイルレンダラーでは SSS／クリアコート／負荷の高いシェーディングを無効にします。

on_screen_keyboard_handler.gd

仮想キーボードによる遮蔽に合わせて UI をトゥイーンで上に移動します。LineEdit/TextEdit のフォーカス時に使用してください — HUD の拡大縮小の代わりにはなりません。

mobile_ui_adapter.gd と on_screen_keyboard_handler の使い分け

必要なこと	スクリプト
HUD の拡大縮小とアンカーの再配置、仮想スティックの生成、親指が届く範囲に合わせた画面密度の調整	mobile_ui_adapter
OS の仮想キーボードがフォーカス中のテキストフィールドを覆う場合	on_screen_keyboard_handler（多くの場合、両方を使用します。レイアウトには adapter、テキストフィールドには OSK handler を使用します）

offline_save_sync.gd

必須 — アプリの一時停止時にデータを保存してください（モバイルでの強制終了時には WM_CLOSE は信頼できません）。

---

タッチ操作方式

選択マトリックス

ジャンル	推奨される操作	スクリプト
プラットフォーマー	仮想ジョイスティック（左）＋ジャンプボタン（右）	dynamic_joystick_spawner / virtual_joystick
トップダウンシューター	デュアルスティック（左で移動、右で照準）	dynamic_joystick_spawner ×2
ターン制	ユニット／タイルを直接タップ	gesture_combo_system（タップ）
パズル	タップ、スワイプ、ピンチ	gesture_combo_system
カードゲーム	ドラッグ＆ドロップ	mobile_ui_adapter ＋ドラッグ用 Controls
レース	傾き、または左右のタップ	platform-mobile / Input センサー

移植手順（順番どおり）

1. 必須 mobile-port-checklist.md — コントロールを再マッピングする前に、移植前のインベントリとゲートの項目を確認します。
2. ホバー／右クリック／スクロールをタッチ操作に置き換えます（判断マトリクス）。
3. 必須 safe-area と mobile_ui_adapter を使用して、44～48dp のタッチターゲットを確保します。重要な HUD は指で隠れない位置に保ちます。
4. 一時停止／再開時に battery_saver_mode と offline_save_sync を接続します。
5. デバイスの FPS が安定するまで、resolution_scaler と mobile_shader_fallback を有効にします。
6. Android／iOS の IAP／権限に関する詳細は godot-platform-mobile を参照します（コントロール／UI／パフォーマンスのゲートを通過するまで、プラットフォームスキル全体をロードしないでください）。

エッジケース（チェックリスト）

• 2 本のスティックでマルチタッチのインデックスが競合する — スティックごとに event.index を追跡します
• OSK が LineEdit を覆う — on_screen_keyboard_handler.gd
• 保存されないままバックグラウンドで終了する — offline_save_sync.gd（WM_CLOSE はモバイルでは信頼できません）
• ノッチにかかる — ui_safe_area_margins.gd
• 画面端への手のひらのタッチ — 端から約 50px 以内のタップを無視します
• デスクトップのテストビルド：InputEventMouseButton と InputEventScreenTouch の両方を処理します

デバイスでのテスト（リリース前）

• 実機で 44～48dp のタッチターゲットを確認します
• HUD が指で隠れない（遮蔽距離 50～100px）
• 一時停止時に FPS が低下し、バックグラウンド移行時に保存される
• resolution_scaler.gd と mobile_shader_fallback.gd の適用後、FPS が安定する
• 縦向きと横向きのセーフエリア

移植の詳細な手順 → mobile-port-deep.md。

詳細な手順

判断マトリクスの範囲を超えて移植する場合は、必ず mobile-port-deep.md を読みます。最初のコントロール再マッピングでは、ロードしないでください。

エキスパート向けテクニック（簡易版）

• await RenderingServer.frame_post_draw とビューポート画像を使って、ストア用スクリーンショットをキャプチャします。
• デバッグオーバーレイ：OS.get_memory_info() — 監視中に負荷の高いアロケーションを大量に発生させないでください。

リファレンス

段階的な開示：特定の API を調査する場合に限り、公式ドキュメントへのリンクを開きます。 関連ドメインに作業を振り分けるときは、関連スキルをロードします。スキル群全体を事前ロードしないでください。

公式ドキュメント

• InputEvent の使用 — イベントの処理パイプラインと、モバイルではホバーやマウス移動を前提とせず、InputEventScreenTouch／InputEventScreenDrag を使用する理由を説明します。
• マウスと入力座標 — ビューポートとキャンバスの変換について説明し、タッチ位置がデスクトップのマウステストと同じ UI／ゲーム空間に配置されるようにします。
• 入力例 — 仮想ジョイスティック、スワイプ、ピンチジェスチャーに応用できる、実践的なマルチタッチとドラッグのパターンを紹介します。
• 複数の解像度 — スマートフォンやタブレットのレイアウトでタッチターゲットを見やすく保つための、ストレッチモード、アスペクト比、コンテンツスケールについて説明します。
• 解像度スケーリング — モバイル GPU がフレーム予算を超過した際の、アダプティブ品質で使われる scaling_3d_scale／FSR のトレードオフについて説明します。
• 3 つのレンダリング方式の概要 — フィルレートと機能セットの観点から、移植時に Forward+ より Mobile または Compatibility を優先すべき理由を説明します。
• 終了要求の処理 — モバイル OS で、確実なウィンドウ終了時の保存の代わりに使われる NOTIFICATION_APPLICATION_PAUSED／再開のライフサイクルについて説明します。
• DisplayServer — ノッチや OSK による画面の遮蔽に関係する get_display_safe_area()、仮想キーボード API、画面情報について説明します。
• コンテナの使用 — セーフエリアの余白や大きなタッチターゲットに関する、Margin／Box／Grid コンテナの仕様を説明します。
• TouchScreenButton — カスタムのヒットテストなしで Input アクションを発行する、組み込みの画面上ボタンです。
• Android 向けのエクスポート — 操作／UI の移植が完了した後に行う、権限、APK／AAB、デバイステストの確認事項について説明します。
• iOS 向けのエクスポート — デスクトップ向けの残存要素が遅い段階で見つかる、Xcode エクスポート、ケイパビリティ、App Store の制約について説明します。

関連スキル

前提条件

• godot-input-handling — 仮想ジョイスティックやスワイプコンボを構築する前に、共有の InputEvent バッファリング、デッドゾーン、マルチタッチジェスチャーの基礎を学びます。
• godot-ui-containers — アンカー、コンテナ、最小サイズについて学び、44～48px のタッチターゲットとセーフエリアの余白がレイアウトに正しく収まるようにします。
• godot-project-foundations — すべての移植ブランチが依存する、機能タグ（mobile／android／ios）、ディスプレイのストレッチ、レンダラーのデフォルト設定について学びます。

補完

• godot-platform-mobile — デスクトップからタッチ操作への再マッピングを済ませた後に必要となる、Android/iOS のプラットフォーム API（権限、IAP、サーマル制御）について詳しく説明します。
• godot-performance-optimization — 適応型の scaling_3d_scale とマテリアルのフォールバックだけでは不十分な場合に、プロファイリングと CPU/GPU の負荷削減を行います。
• godot-save-load-systems — デスクトップ専用の終了通知ではなく、一時停止／再開に連動する永続的なセーブ管理を実現します。
• godot-camera-systems — 1 本指のパンと 2 本指のピンチ操作コントローラーで使用する、Camera2D/3D の追従およびズームの仕様を扱います。
• godot-shaders-basics — モバイル GPU 向けにデスクトップ専用の視覚機能を削る際に使用する、負荷の低い CanvasItem/Spatial シェーダーの手法を紹介します。
• godot-3d-materials — 低性能なレンダラーで mobile_shader_fallback が無効にする StandardMaterial3D の機能フラグ（SSS、クリアコート）を扱います。
• godot-tweening — OS の仮想キーボードが LineEdit/TextEdit を覆う場合に、UI を滑らかに持ち上げる方法を紹介します。
• godot-autoload-architecture — 触覚フィードバック、バッテリーセーバー、オフラインセーブ同期マネージャー向けのシングルトンの配置先を扱います。

下流／利用側

• godot-export-builds — デバイスでタッチ操作／UI／パフォーマンスの基準を満たした後の、パッケージ化、署名、CI エクスポートプリセットを扱います。
• godot-platform-desktop — モバイル対応後も同じプロジェクトで複数の入力方式をサポートする場合に、デスクトップのマウス／キーボード操作を引き続き機能させます。
• godot-genre-puzzle — このスキルのジェスチャーと UI スケーリングのパターンを活用する、タップ／スワイプ／ピンチの操作方式を扱います。

マスター

• godot-master — ライブラリのルーターであり、関連ドメインと並べてこの適応スキルを見つけるためのミラー化されたモジュールエントリです。