input-keyboard-mouse-touch

入力: キーボード、マウス、タッチ、ゲームパッド

Phaser は、任意の Scene で this.input を介してアクセスできる統一された入力システムを提供します。キーボードのポーリングとイベント、Game Object とのマウス/ポインター操作（クリック、ホバー、ドラッグ）、マルチタッチ、マウスホイール、ゲームパッド入力をサポートしています。入力は、イベントリスナーを通じて、または毎フレーム状態をポーリングすることで処理できます。

主要なソースパス: src/input/InputPlugin.js、src/input/Pointer.js、src/input/keyboard/KeyboardPlugin.js、src/input/keyboard/keys/Key.js、src/input/keyboard/keys/KeyCodes.js、src/input/keyboard/combo/KeyCombo.js、src/input/gamepad/GamepadPlugin.js、src/input/gamepad/Gamepad.js、src/input/events/、src/input/keyboard/events/ 関連スキル: ../sprites-and-images/SKILL.md、../events-system/SKILL.md、../scenes/SKILL.md

クイックスタート（基本的なキーボード + ポインター入力）

class MyScene extends Phaser.Scene {
    create() {
        // Keyboard: create cursor keys (up, down, left, right, space, shift)
        this.cursors = this.input.keyboard.createCursorKeys();

        // Keyboard: listen for a specific key event
        this.input.keyboard.on('keydown-SPACE', (event) => {
            console.log('Space pressed');
        });

        // Pointer: listen for click/tap anywhere on the game canvas
        this.input.on('pointerdown', (pointer) => {
            console.log('Clicked at', pointer.x, pointer.y);
        });

        // Pointer: make a Game Object interactive and clickable
        const sprite = this.add.sprite(400, 300, 'player');
        sprite.setInteractive();
        sprite.on('pointerdown', (pointer, localX, localY, event) => {
            console.log('Sprite clicked at local', localX, localY);
        });
    }

    update() {
        // Poll cursor keys each frame
        if (this.cursors.left.isDown) {
            // move left
        }
        if (this.cursors.right.isDown) {
            // move right
        }
        if (Phaser.Input.Keyboard.JustDown(this.cursors.space)) {
            // fire once per press
        }
    }
}

中核となる概念

Input プラグイン（this.input）

任意の Scene で this.input を介してアクセスできます。これは EventEmitter であり、その Scene のすべての入力を処理します。

主なプロパティ:

• this.input.enabled（boolean） - Scene の入力処理を切り替えます
• this.input.topOnly（boolean、デフォルト true） - ポインターの下にある最上位の Game Object からのイベントのみを発行します
• this.input.keyboard - KeyboardPlugin のインスタンス
• this.input.gamepad - GamepadPlugin のインスタンス
• this.input.mouse - MouseManager への参照
• this.input.activePointer - 直近でアクティブだった Pointer
• this.input.mousePointer - マウスの Pointer（pointers[0]。最初のタッチである pointer1 とは異なります）
• this.input.pointer1 から this.input.pointer10 - 個々の Pointer への参照
• this.input.dragDistanceThreshold（number、デフォルト 0） - ドラッグが開始されるまでにポインターが移動しなければならないピクセル数
• this.input.dragTimeThreshold（number、デフォルト 0） - ドラッグが開始されるまでにポインターを押し続けなければならないミリ秒数
• this.input.pollRate（number、デフォルト -1） - ポインターをポーリングする頻度。0 = 毎フレーム、-1 = 移動時のみ

主なメソッド:

• addPointer(quantity) - マルチタッチ用に追加の Pointer を追加します（デフォルトは 2、最大 10）
• setHitArea(gameObjects, hitArea, hitAreaCallback) - Game Object にカスタムヒットエリアを設定します
• setHitAreaCircle(gameObjects, x, y, radius, callback)
• setHitAreaEllipse(gameObjects, x, y, width, height, callback)
• setHitAreaRectangle(gameObjects, x, y, width, height, callback)
• setHitAreaTriangle(gameObjects, x1, y1, x2, y2, x3, y3, callback)
• setHitAreaFromTexture(gameObjects, callback) - テクスチャフレームの寸法を使用します
• setDraggable(gameObjects, value) - ドラッグを有効または無効にします
• makePixelPerfect(alphaTolerance) - ピクセルパーフェクトなヒットテスト用のコールバックを返します

Pointer

Pointer オブジェクトは、マウス入力とタッチ入力の両方をカプセル化します。デフォルトで Phaser は 2 つのポインターを生成します。さらに増やすには this.input.addPointer(quantity) を使用します（最大 10 個まで）。

主なプロパティ:

• x、y - スクリーン空間での位置（position.x、position.y から読み取ります）
• worldX、worldY - 直近の Camera を通して変換された位置
• downX、downY - ボタンが押されたときの位置
• upX、upY - ボタンが離されたときの位置
• isDown（boolean）- いずれかのボタンが押されている間は true
• primaryDown（boolean）- 主ボタン（左クリック / タッチ）が押されている間は true
• button（number）- どのボタンが押された / 離されたか（0=左、1=中央、2=右）
• buttons（number）- 現在押されているボタンのビットマスク（1=左、2=右、4=中央、8=戻る、16=進む）
• wasTouch（boolean）- 入力がタッチによるものである場合は true
• velocity（Vector2）- ポインター移動の平滑化された速度
• angle（number）- 移動方向の角度（ラジアン）
• distance（number）- 1 フレームあたりの平滑化された移動距離
• movementX、movementY - ポインターがロックされているときの相対移動量
• deltaX、deltaY、deltaZ - マウスホイールのスクロール量
• locked（boolean）- ポインターロックが有効かどうか
• camera - この Pointer が最後に操作した Camera

主なメソッド:

• leftButtonDown()、rightButtonDown()、middleButtonDown()、backButtonDown()、forwardButtonDown() - 特定のボタンをチェックします
• leftButtonReleased()、rightButtonReleased()、middleButtonReleased() - 直近の離しをチェックします
• getDistance() - 押下位置と現在位置 / 離し位置の間の距離
• getDistanceX()、getDistanceY() - 水平 / 垂直方向の距離
• getDuration() - 押下から現在時刻または離し時刻までのミリ秒
• getAngle() - 押下位置と現在位置 / 離し位置の間の角度
• updateWorldPoint(camera) - 指定したカメラに対して worldX/worldY を再計算します
• positionToCamera(camera, output) - ポインター位置をカメラを通して変換します

インタラクティブなゲームオブジェクト（setInteractive）

ゲームオブジェクトで入力を受け付けるには gameObject.setInteractive() を呼び出します。デフォルトではテクスチャフレームがヒットエリアとして使用されます。

// Default hit area from texture
sprite.setInteractive();

// Custom shape hit areas (Rectangle, Circle, Ellipse, Triangle, Polygon)
sprite.setInteractive(new Phaser.Geom.Circle(32, 32, 32), Phaser.Geom.Circle.Contains);
sprite.setInteractive(new Phaser.Geom.Ellipse(50, 50, 100, 60), Phaser.Geom.Ellipse.Contains);
sprite.setInteractive(new Phaser.Geom.Triangle(0,64,32,0,64,64), Phaser.Geom.Triangle.Contains);
sprite.setInteractive(new Phaser.Geom.Polygon(points), Phaser.Geom.Polygon.Contains);

// Pixel-perfect hit testing (expensive — use sparingly)
sprite.setInteractive({ pixelPerfect: true, alphaTolerance: 1 });
sprite.setInteractive(this.input.makePixelPerfect());
// With alpha tolerance (default 1):
sprite.setInteractive(this.input.makePixelPerfect(150));

// Config object with multiple options
sprite.setInteractive({
    draggable: true,
    dropZone: false,
    useHandCursor: true,
    cursor: 'pointer',
    pixelPerfect: true,
    alphaTolerance: 1
});

// Containers must specify a shape or call setSize first
container.setSize(200, 200);
container.setInteractive();

一般的なパターン

キーボード入力（cursors、addKey、isDown、JustDown）

カーソルキー は、up、down、left、right、space、shift の Key オブジェクトを持つオブジェクトを返します:

this.cursors = this.input.keyboard.createCursorKeys();

// In update():
if (this.cursors.up.isDown) { /* held */ }
if (this.cursors.space.isDown) { /* held */ }

addKey は、任意のキーの Key オブジェクトを作成します:

// By string name
const keyW = this.input.keyboard.addKey('W');
// By key code
const keySpace = this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);
// With options: addKey(key, enableCapture, emitOnRepeat)
const keyA = this.input.keyboard.addKey('A', true, false);

addKeys は、複数のキーを一度に作成します:

// Comma-separated string returns { W, S, A, D } Key objects
const keys = this.input.keyboard.addKeys('W,S,A,D');
if (keys.W.isDown) { /* ... */ }

// Object form with custom names
const keys = this.input.keyboard.addKeys({
    up: Phaser.Input.Keyboard.KeyCodes.W,
    down: Phaser.Input.Keyboard.KeyCodes.S,
    left: Phaser.Input.Keyboard.KeyCodes.A,
    right: Phaser.Input.Keyboard.KeyCodes.D
});

ポーリングとイベント:

// Polling in update() - check every frame
if (keyW.isDown) { /* key is currently held */ }
if (keyW.isUp) { /* key is currently released */ }

// JustDown - returns true only once per press, resets after check
if (Phaser.Input.Keyboard.JustDown(keyW)) { /* fire once */ }
if (Phaser.Input.Keyboard.JustUp(keyW)) { /* released once */ }

// checkDown with duration - throttled polling
if (this.input.keyboard.checkDown(keySpace, 250)) {
    // true at most once every 250ms while held
}

// Event-driven: listen for specific key
this.input.keyboard.on('keydown-SPACE', (event) => { /* ... */ });
this.input.keyboard.on('keyup-SPACE', (event) => { /* ... */ });

// Event-driven: listen for any key
this.input.keyboard.on('keydown', (event) => {
    console.log(event.key); // native DOM KeyboardEvent
});

// Event on a Key object itself
const spaceBar = this.input.keyboard.addKey('SPACE');
spaceBar.on('down', (key, event) => { /* Key object + native event */ });
spaceBar.on('up', (key, event) => { /* ... */ });

Key オブジェクトのプロパティ:

• isDown / isUp（boolean）
• keyCode（number）
• altKey、ctrlKey、shiftKey、metaKey（boolean）- 押されたときの修飾キーの状態
• duration（number）- 直前の押下から離しまでのサイクルで押されていたミリ秒
• timeDown、timeUp（number）- タイムスタンプ
• repeats（number）- 押し続けている間のリピート回数
• emitOnRepeat（boolean）- true の場合、リピートごとに 'down' イベントを発火します
• enabled（boolean）- このキーを処理できるかどうか

ブラウザのデフォルト動作を防ぐ:

// Capture specific keys to prevent browser scrolling etc.
this.input.keyboard.addCapture('SPACE,UP,DOWN,LEFT,RIGHT');
this.input.keyboard.addCapture([ 32, 37, 38, 39, 40 ]);
this.input.keyboard.removeCapture('SPACE');
// Note: captures are global across all Scenes

一般的な KeyCodes: BACKSPACE(8)、TAB(9)、ENTER(13)、SHIFT(16)、CTRL(17)、ALT(18)、ESC(27)、SPACE(32)、LEFT(37)、UP(38)、RIGHT(39)、DOWN(40)、A-Z(65-90)、ZERO-NINE(48-57)、F1-F12(112-123)。アクセスするには Phaser.Input.Keyboard.KeyCodes.SPACE などを使用します。

マウス / ポインターのクリックとホバー

シーンレベルのポインターイベント（キャンバス上のどこででも発火します）:

this.input.on('pointerdown', (pointer, currentlyOver) => {
    // pointer: Pointer object, currentlyOver: array of interactive Game Objects under pointer
});
this.input.on('pointerup', (pointer, currentlyOver) => { /* ... */ });
this.input.on('pointermove', (pointer, currentlyOver) => { /* ... */ });
this.input.on('wheel', (pointer, currentlyOver, deltaX, deltaY, deltaZ) => { /* ... */ });

ゲームオブジェクトのポインターイベント（setInteractive が必要です）:

sprite.setInteractive();

// pointerdown on this specific object
sprite.on('pointerdown', (pointer, localX, localY, event) => {
    // localX/localY are relative to the Game Object's top-left
    // event.stopPropagation() prevents the event from going further
});

sprite.on('pointerup', (pointer, localX, localY, event) => { /* ... */ });
sprite.on('pointermove', (pointer, localX, localY, event) => { /* ... */ });
sprite.on('pointerover', (pointer, localX, localY, event) => { /* ... */ });
sprite.on('pointerout', (pointer, event) => { /* ... */ });
sprite.on('wheel', (pointer, deltaX, deltaY, deltaZ, event) => { /* ... */ });

右クリックの処理:

this.input.on('pointerdown', (pointer) => {
    if (pointer.rightButtonDown()) {
        // right-click
    }
});

// Disable context menu
this.input.mouse.disableContextMenu();

ポインターロック（FPS スタイルのマウスキャプチャ）:

// Request lock on click
this.input.on('pointerdown', () => {
    this.input.mouse.requestPointerLock();
});

this.input.on('pointerlockchange', (event, locked) => {
    // locked: boolean
});

// Read relative movement while locked
// pointer.movementX, pointer.movementY

ドラッグアンドドロップ

const sprite = this.add.sprite(400, 300, 'item');
sprite.setInteractive();
this.input.setDraggable(sprite);

// Or use config:
// sprite.setInteractive({ draggable: true });

// Drag events on the Scene input
this.input.on('dragstart', (pointer, gameObject) => {
    gameObject.setTint(0xff0000);
});

this.input.on('drag', (pointer, gameObject, dragX, dragY) => {
    gameObject.x = dragX;
    gameObject.y = dragY;
});

this.input.on('dragend', (pointer, gameObject) => {
    gameObject.clearTint();
});

// Drop zones
const zone = this.add.zone(600, 300, 200, 200).setRectangleDropZone(200, 200);

this.input.on('drop', (pointer, gameObject, dropZone) => {
    gameObject.x = dropZone.x;
    gameObject.y = dropZone.y;
});

this.input.on('dragenter', (pointer, gameObject, dropZone) => { /* ... */ });
this.input.on('dragleave', (pointer, gameObject, dropZone) => { /* ... */ });
this.input.on('dragover', (pointer, gameObject, dropZone) => { /* ... */ });

ゲームオブジェクトレベルのドラッグイベントも利用できます:

sprite.on('drag', (pointer, dragX, dragY) => {
    sprite.x = dragX;
    sprite.y = dragY;
});
sprite.on('dragstart', (pointer, dragX, dragY) => { /* ... */ });
sprite.on('dragend', (pointer, dragX, dragY) => { /* ... */ });
sprite.on('drop', (pointer, dropZone) => { /* ... */ });

ドラッグのしきい値:

this.input.dragDistanceThreshold = 16; // must move 16px before drag starts
this.input.dragTimeThreshold = 200;    // must hold 200ms before drag starts

ポインターイベントの 3 つのレベル

ポインターイベントは 3 つのレベルで発火します（詳細はリファレンスを参照してください）:

1. ゲームオブジェクト: gameObject.on('pointerdown', (pointer, localX, localY, event) => {})
2. シーンのオブジェクト単位: this.input.on('gameobjectdown', (pointer, gameObject, event) => {})
3. シーンのグローバル: this.input.on('pointerdown', (pointer, currentlyOver) => {})

入力デバッグ、topOnly、マルチタッチの設定

// Debug visualize hit areas
this.input.enableDebug(gameObject);
this.input.enableDebug(gameObject, 0xff00ff);
this.input.removeDebug(gameObject);

// Let all objects under pointer receive events (not just top-most)
this.input.topOnly = false;
this.input.setTopOnly(false);

マルチタッチ: 起動時にポインタースロットを確保するには config.input.activePointers を設定するか、実行時に this.input.addPointer(num) を呼び出します。this.input.pointer1 から pointer10 でアクセスできます。

ゲームパッド入力

ゲームの設定でゲームパッドを有効にします:

const config = {
    input: {
        gamepad: true
    }
};

this.input.gamepad でアクセスできます。ゲームパッドは pad1 から pad4 として利用できます:

// Wait for connection
this.input.gamepad.once('connected', (pad) => {
    console.log('Gamepad connected:', pad.id);
});

// If already connected, check total
if (this.input.gamepad.total > 0) {
    const pad = this.input.gamepad.pad1;
}

update() でのゲームパッド状態のポーリング:

update() {
    const pad = this.input.gamepad.pad1;
    if (!pad) return;

    // D-pad (boolean properties)
    if (pad.up) { /* d-pad up */ }
    if (pad.down) { /* d-pad down */ }
    if (pad.left) { /* d-pad left */ }
    if (pad.right) { /* d-pad right */ }

    // Face buttons (boolean) - Xbox naming convention
    if (pad.A) { /* bottom button (Xbox A / PS X) */ }
    if (pad.B) { /* right button (Xbox B / PS Circle) */ }
    if (pad.X) { /* left button (Xbox X / PS Square) */ }
    if (pad.Y) { /* top button (Xbox Y / PS Triangle) */ }

    // Shoulder buttons (float 0-1)
    if (pad.L1 > 0) { /* left shoulder top (LB) */ }
    if (pad.L2 > 0) { /* left shoulder bottom / trigger (LT) */ }
    if (pad.R1 > 0) { /* right shoulder top (RB) */ }
    if (pad.R2 > 0) { /* right shoulder bottom / trigger (RT) */ }

    // Analog sticks (Vector2, values -1 to 1)
    const lx = pad.leftStick.x;  // left stick horizontal
    const ly = pad.leftStick.y;  // left stick vertical
    const rx = pad.rightStick.x;
    const ry = pad.rightStick.y;

    // Raw axis/button access
    pad.getAxisValue(0);    // float
    pad.getButtonValue(0);  // float 0-1
    pad.isButtonDown(0);    // boolean
    pad.setAxisThreshold(0.1); // ignore values below threshold
}

ゲームパッドのイベント:

// Plugin-level events (any gamepad)
this.input.gamepad.on('connected', (pad, event) => { /* ... */ });
this.input.gamepad.on('disconnected', (pad, event) => { /* ... */ });
this.input.gamepad.on('down', (pad, button, value) => { /* any button on any pad */ });
this.input.gamepad.on('up', (pad, button, value) => { /* ... */ });

// Gamepad-instance events
pad.on('down', (index, value, button) => { /* button on this specific pad */ });
pad.on('up', (index, value, button) => { /* ... */ });

振動（実験的、ハードウェア/ブラウザーに依存）:

if (pad.vibration) {
    pad.vibration.playEffect('dual-rumble', {
        duration: 200,
        strongMagnitude: 1.0,
        weakMagnitude: 0.5
    });
}

キーの組み合わせ

一連のキー入力をリッスンします:

// String-based combo
this.input.keyboard.createCombo('PHASER');

// Array of key codes (Konami code)
this.input.keyboard.createCombo(
    [ 38, 38, 40, 40, 37, 39, 37, 39, 66, 65, 13 ],
    { resetOnMatch: true }
);

// Listen for match
this.input.keyboard.on('keycombomatch', (keyCombo, event) => {
    console.log('Combo matched!');
});

createCombo(keys, config):

• keys: 文字列（各文字がキー）またはキーコード / Key オブジェクトの配列
• config.resetOnWrongKey（boolean、デフォルト true） - 間違ったキーが押された場合に進行状況をリセットします
• config.maxKeyDelay（number、デフォルト 0） - キー入力間の最大ミリ秒。0 = 制限なし
• config.resetOnMatch（boolean、デフォルト false） - 一致に成功した後にコンボをリセットします
• config.deleteOnMatch（boolean、デフォルト false） - 最初の一致後にコンボを削除します

詳細な設定オプション、API リファレンスの表、ソースファイルのマップについては、リファレンスガイドを参照してください。