godot-input-handling

入力処理

適切なバッファリングとアクセシビリティサポートにより、キーボード、マウス、ゲームパッド、タッチ入力を処理します。

必須のスクリプトトリガー（シナリオ別）

シナリオ	コーディング前に読み込むもの
ジャンプ／ダッシュ／コヨーテタイムの感触	input_buffer.gd（物理処理に連動した減衰）＋複数アクションの優先順位付け用の advanced_input_buffer.gd
設定のリマッピング UI	safe_runtime_rebind.gd（ConfigFile で user:// に保存）
アナログスティックの移動	analog_deadzone_manager.gd — ラジアルデッドゾーンなしで生の軸入力を使わないでください
「X を押す／E を押す」プロンプト	glyph_prompt_manager.gd
UI ナビゲーションとゲームプレイの決定操作	input_echo_filter.gd — 連続入力はメニューの移動に使い、「決定／戻る」には使いません
ゲームプレイとメニューのクリック	unhandled_input_priority.gd

読み込んではいけないもの（シナリオ別）

シナリオ	読み込むもの	読み込んではいけないもの
設定のリマッピング UI	safe_runtime_rebind.gd	multi_touch_gestures.gd、mouse_capture_manager.gd、コンボ／リプレイのインジェクター
モバイル／タッチジェスチャー	multi_touch_gestures.gd	mouse_capture_manager.gd、デスクトップ向けリマッピングの永続化
ジャンプ／ダッシュのバッファリングのみ	input_buffer.gd / advanced_input_buffer.gd	リマッピング、マルチタッチ、リプレイ、コンボバリデーター
FPS のマウスルック	mouse_capture_manager.gd ＋必要に応じてデッドゾーン／グリフ	multi_touch_gestures.gd、コンボ／リプレイ
コンボ／格闘シーケンス	combo_validator.gd ＋バッファー	タッチジェスチャー、マウスキャプチャ
リプレイ／仮想入力のインジェクションテスト	input_replay_buffer.gd / virtual_input_injector.gd	リマッピング UI、マルチタッチ

利用可能なスクリプト

advanced_input_buffer.gd

反応のよいジャンプ、ダッシュ、コンボ連鎖のための、フレーム単位の精度を持つ入力バッファリングシステムです。

input_buffer.gd

_physics_process による減衰を備えた時間制限付きアクションバッファーです。ウィンドウが描画 FPS ではなく、CharacterBody による入力消費に一致します。

safe_runtime_rebind.gd

競合検出と user://input_rebinds.cfg への永続化に対応した、動的な入力リマッピングです。

analog_deadzone_manager.gd

自然な追従性を維持しながらドリフトを排除する、アナログスティック用のラジアルデッドゾーン管理です。

multi_touch_gestures.gd

モバイル端末やタッチスクリーンに対応するための、タッチ、ドラッグ、ピンチズームジェスチャーの処理です。

input_echo_filter.gd

エコーイベントをフィルタリングし、長押しによるナビゲーション（UI）と一度限りのゲームプレイアクションを区別します。

mouse_capture_manager.gd

FPS やマウスを多用するシステム向けの、堅牢なマウスキャプチャと感度スケーリングのロジックです。

hold_toggle_accessibility.gd

ユーザーが設定できる「長押し」と「切り替え」のアクセシビリティ設定を、ソフトウェア側でサポートします。

glyph_prompt_manager.gd

最後に使用したデバイスに応じて、キーボードとゲームパッドの UI プロンプトをリアルタイムで切り替えます。

action_state_machine.gd

複雑な状態ロジック向けに、アクションのライフサイクル（「押した直後」「長押し中」「離した」）を追跡します。

unhandled_input_priority.gd

ゲームプレイのロジックが UI に漏れないようにする _unhandled_input の適切な使い方を示します。

virtual_input_injector.gd

CI チュートリアル／AI アシスタンス向けの Input.parse_input_event インジェクションです。物理ハードウェア用ではありません。

combo_validator.gd

必殺技の入力検証（格闘ゲーム／アクション RPG）向けの、時間制限付きシーケンスを保持するバッファーです。

input_replay_buffer.gd

フレームタグ付きの記録と、parse_input_event による決定論的なリプレイです。

入力処理で絶対にしてはいけないこと

• ゲームプレイアクションの入力を _process() で絶対にポーリングしないでください — _physics_process() または _unhandled_input() を使用してください。_process() はフレームレートに依存するため、FPS が低いと入力が失われます [22]。
• ハードコードしたキー判定（例：KEY_W）を絶対に使用しないでください — 必ず InputMap アクションを使用してください。ハードコードしたキーではキーの再割り当てができず、QWERTY 以外の配列との互換性も損なわれます [23]。
• アナログスティックのデッドゾーンを絶対に無視しないでください — 入力値が 0.05 程度でもスティックのドリフトが発生すると、意図しない移動につながります。コードまたは設定で、軸ごとではなく円形のデッドゾーンを実装してください [24]。
• 入力デバイスが 1 つだけだと絶対に想定しないでください — プレイヤーはセッション中にキーボードとコントローラーを切り替えることがあります。Input.joy_connection_changed を使用して、UI のプロンプトを動的に更新してください [25]。
• ゲームプレイアクションに _input() を絶対に使用しないでください — _input() は UI を含むすべてのイベントで呼び出されます。メニューのクリック中にゲームプレイのロジックが動作しないよう、_unhandled_input() を使用してください [26]。
• テンポの速いゲームで入力バッファーを絶対に省略しないでください — 着地の 50ms 前にジャンプボタンが押されると、バッファーがなければ入力が失われます。「きびきびした」操作感にするには、100～150ms のバッファーを実装してください [27]。
• 1 回限りのトリガーに Input.is_action_pressed() を絶対に使用しないでください — キーを押している間、毎フレーム true を返します。ジャンプ、攻撃、切り替え操作には _just_pressed を使用して、ロジックが連続して実行されるのを防いでください。
• 「ホールドかトグルか」のロジックを複数箇所に手動で実装することは絶対に避けてください — ゲーム全体でアクセシビリティの一貫性を保つため、設定または入力ラッパーに集約してください。
• UI ナビゲーションで InputEvent.is_echo() の処理を絶対に忘れないでください — エコーイベント（キーのリピート）でメニューを移動できるようにする一方、「決定」や「戻る」の操作が実行されることはほとんどないようにしてください。
• 「解除」用のショートカットなしでマウスを絶対にキャプチャしないでください — ゲームがクラッシュしたり ui_cancel をブロックしたりすると、ユーザーは操作不能になります。マウスキャプチャを解除するための代替手段を必ず用意してください。

---

入力の伝播と分離

Godot は入力イベントを特定の順序で伝播させます。UI とゲームプレイを分離するには、この仕組みを理解することが重要です。

1. _input(event)：優先度の高いグローバルインターセプトです。開発用コンソールやデバッグオーバーレイに使用してください。
2. _gui_input(event)：**Control ノード（UI）**によって処理されます。UI 要素がイベントを消費する場合（例：ボタンのクリック）、accept_event() を呼び出して、それ以降の伝播を停止します。
3. _unhandled_input(event)：UI 要素がイベントを消費しなかった場合にのみ呼び出されます。エキスパート向けのパターン：メニュー操作中に誤ってアクションが実行されないよう、すべてのゲームプレイロジック（ジャンプ、射撃）をここに記述してください。

InputMap のベストプラクティス

物理キーでの判定は避けてください。Project Settings > Input Map で、move_left や interact などの意味的なアクションを定義してください。

1. アナログデッドゾーン

アナログスティックではドリフトが発生します。必須：analog_deadzone_manager.gd。円形のデッドゾーンには Input.get_vector() を優先してください。軸の値を個別に差し引いて、正方形のデッドゾーンを作らないでください。

2. エキスパート向けの入力ポーリングの差分（ハードコードしたキーなし）

ゲームプレイでは _physics_process / _unhandled_input でアクションをサンプリングし、KEY_* / MOUSE_BUTTON_* の分岐は絶対に使用しません。一時停止とキャンセルは ui_cancel などの InputMap アクションにしてください。これにより、キーの再割り当てや QWERTY 以外の配列でも正しく動作します。unhandled_input_priority.gd を参照してください。

マルチモーダル入力と UI のグリフ

最新のゲームでは、コントローラーとキーボード／マウスからの同時入力をスムーズに処理する必要があります。

1. 入力モードの処理

• マウスでのエイミング：相対移動には、_unhandled_input() で InputEventMouseMotion を処理してください（mouse_capture_manager.gd）。
• スティックでの移動：analog_deadzone_manager.gd に従い、_physics_process() でベクトルをポーリングしてください。

2. グリフの動的な切り替え

最後に使用したデバイスに応じてプロンプトを切り替えるには、必須の glyph_prompt_manager.gd を使用してください。すべての HUD ウィジェットで event is InputEventJoypadButton の検出処理を個別に実装しないでください。

エキスパート向け入力拡張機能（スクリプトのみを正とする）

• 入力バッファリング — 必須：input_buffer.gd + advanced_input_buffer.gd。ジャンプタイマーのチュートリアルをインラインで貼り付けないでください。
• コヨーテタイム — 移動スキルの管轄です：godot-characterbody-2d（frame_perfect_coyote_time.gd）およびgodot-genre-platformer。このスキルのバッファーと組み合わせてください。ここでコヨーテタイムを再実装しないでください。
• マルチプレイヤー入力の同期 — ここで sync_input を RPC しないでください。 権威あるアクションスナップショットや get_remote_sender_id の検証については、godot-multiplayer-networking を参照してください。
• 仮想入力の注入 — 必須：virtual_input_injector.gd（Input.parse_input_event）。
• コンボシーケンス — 必須：combo_validator.gd。格闘ゲームの内容は godot-genre-fighting で扱います。
• 決定論的リプレイ — 必須：input_replay_buffer.gd。

詳細なレシピ（必要に応じて）

トピック	リファレンス／スクリプト
バッファリング／コヨーテタイム／MP 同期	input-event-processing.md
仮想入力の注入／コンボ／リプレイ	expert-input-extensions.md
InputMap とデバイス ID	inputmap-best-practices.md

リファレンス

段階的開示：特定の API を調査するときにのみ公式ドキュメントへのリンクを開き、関連スキルは関連分野へ案内するときに読み込んでください。スキル全体をあらかじめ読み込まないでください。

公式ドキュメント

• InputEvent の使用 — イベントの伝播順（_input → GUI → _unhandled_input）と、UI がイベントを処理した後にゲームプレイ入力を扱うべき理由です。
• 入力の例 — このスキルの基盤となる、InputMap アクションの実用的なポーリング、マウスボタン、キーボードのパターンです。
• コントローラー、ゲームパッド、ジョイスティック — リマッパーやボタン表示の切り替えに必要な、ゲームパッドの接続、ボタン／軸イベント、複数デバイスのマッピングです。
• コントローラーの振動と機能 — コンソールスタイルのフィードバックを実装する際に役立つ、基本的なボタン以外の拡張パッド機能です。
• マウスと入力座標 — クリック、照準、キャプチャ相対移動におけるビューポート座標と画面座標の違いです。
• マウスカーソルのカスタマイズ — Input.mouse_mode によるキャプチャ／解除の流れと併せて使うカーソル形状です。
• 終了要求の処理 — マウスキャプチャでプレイヤーを閉じ込めないための、安全な ESC／戻る／終了の処理方法です。
• Input — シングルトン API：is_action_*、get_vector、mouse_mode、parse_input_event、ゲームパッド接続シグナルです。
• InputMap — 安全なキー割り当て変更のための、実行時の action_add_event／削除／競合チェックです。
• InputEvent — is_echo()、is_action_pressed()、デバイス ID などを含む基本イベント API です。
• アイドル処理と物理処理 — 保持中のゲームプレイ入力をフレーム依存の _process ではなく _physics_process でポーリングすべき理由です。
• Control — メニューが _unhandled_input のゲームプレイ処理より前にイベントを停止するための _gui_input／accept_event です。

関連スキル

前提条件

• godot-project-foundations — リマッパーやボタン表示管理機能を配置する、Project Settings の Input Map、シーンの起動、Autoload の登録です。
• godot-gdscript-mastery — バッファーやデバイスルーターで使う、型付き InputEvent 分岐、StringName アクション、安全なシグナル／await パターンです。

補完

• godot-ui-containers — フォーカスと _gui_input の所有権を制御し、メニューがクリックを消費してから、ゲームプレイの _unhandled_input に届くようにします。
• godot-signal-architecture — device_changed と再割り当てイベントは、UIへのハード参照を使わずにHUDやプロンプトのリスナーへシグナルを送信します。
• godot-autoload-architecture — シーン変更後も存続する InputBuffer／GlyphPrompt／Remapper サービスのシングルトン所有権を扱います。
• godot-characterbody-2d — 物理ステップ内で、バッファーされたジャンプやダッシュ、get_vector による移動を処理します。
• godot-camera-systems — マウスルックの感度とキャプチャモードは、FPSカメラリグと組み合わせて使用します。
• godot-state-machine-advanced — アクションの押下直後／押下中／解放の各フェーズにより、ポーリングの過剰な繰り返しなしにFSMの遷移を制御します。
• godot-save-load-systems — InputMap の再割り当てと、長押し／切り替え式のアクセシビリティ設定を user:// の設定に保存します。
• godot-adapt-desktop-to-mobile — 仮想ジョイスティックとタッチカメラにより、このスキルのマルチタッチジェスチャーパターンを拡張します。

下流／利用側

• godot-genre-platformer — コヨーテタイムとジャンプバッファーは、入力バッファリングの主な利用例です。
• godot-genre-shooter-fps — マウスのキャプチャによる照準、押下直後の射撃、ゲームパッドによる視点操作には、このスキルのキャプチャ／デッドゾーンの仕組みが必要です。
• godot-genre-fighting — コンボシーケンスの検証とフレーム単位で正確なバッファーが、必殺技の検出に使われます。
• godot-multiplayer-networking — 権威あるピアには、生のローカルキーコードではなく、サニタイズ済みのアクションスナップショットやRPC経由の入力が必要です。

マスター

• godot-master — ライブラリのルーター兼ミラー化されたモジュールのエントリです。複数領域にまたがる入力の懸念をどのドメインスキルが扱うのかを確認する際に開いてください。