input-keyboard-mouse-touch

What this skill does

# Input: Keyboard, Mouse, Touch, and Gamepad
> Phaser provides a unified input system accessed via `this.input` in any Scene. It supports keyboard polling and events, mouse/pointer interaction with Game Objects (click, hover, drag), multi-touch, mouse wheel, and gamepad input. Input can be handled through event listeners or by polling state each frame.

**Key source paths:** `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/`
**Related skills:** ../sprites-and-images/SKILL.md, ../events-system/SKILL.md, ../scenes/SKILL.md

## Quick Start (basic keyboard + pointer input)

```js
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
        }
    }
}
```

## Core Concepts

### The Input Plugin (this.input)

Accessed via `this.input` in any Scene. It is an `EventEmitter` that handles all input for that Scene.

Key properties:
- `this.input.enabled` (boolean) - toggle input processing for the Scene
- `this.input.topOnly` (boolean, default `true`) - only emit events from the top-most Game Object under the pointer
- `this.input.keyboard` - the KeyboardPlugin instance
- `this.input.gamepad` - the GamepadPlugin instance
- `this.input.mouse` - the MouseManager reference
- `this.input.activePointer` - the most recently active Pointer
- `this.input.mousePointer` - the mouse Pointer (pointers[0], distinct from pointer1 which is the first touch)
- `this.input.pointer1` through `this.input.pointer10` - individual pointer references
- `this.input.dragDistanceThreshold` (number, default 0) - pixels a pointer must move before drag starts
- `this.input.dragTimeThreshold` (number, default 0) - ms a pointer must be held before drag starts
- `this.input.pollRate` (number, default -1) - how often pointers are polled; 0 = every frame, -1 = only on movement

Key methods:
- `addPointer(quantity)` - add extra pointers for multi-touch (default is 2; max 10)
- `setHitArea(gameObjects, hitArea, hitAreaCallback)` - set custom hit area on Game Objects
- `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)` - use the texture frame dimensions
- `setDraggable(gameObjects, value)` - enable or disable dragging
- `makePixelPerfect(alphaTolerance)` - returns a callback for pixel-perfect hit testing

### Pointers

A `Pointer` object encapsulates both mouse and touch input. By default Phaser creates 2 pointers. Use `this.input.addPointer(quantity)` for more (up to 10 total).

Key properties:
- `x`, `y` - position in screen space (read from `position.x`, `position.y`)
- `worldX`, `worldY` - position translated through the most recent Camera
- `downX`, `downY` - position when button was pressed
- `upX`, `upY` - position when button was released
- `isDown` (boolean) - true if any button is held
- `primaryDown` (boolean) - true if primary button (left click / touch) is held
- `button` (number) - which button was pressed/released (0=left, 1=middle, 2=right)
- `buttons` (number) - bitmask of currently held buttons (1=left, 2=right, 4=middle, 8=back, 16=forward)
- `wasTouch` (boolean) - true if input came from touch
- `velocity` (Vector2) - smoothed velocity of pointer movement
- `angle` (number) - angle of movement in radians
- `distance` (number) - smoothed distance moved per frame
- `movementX`, `movementY` - relative movement when pointer is locked
- `deltaX`, `deltaY`, `deltaZ` - mouse wheel scroll amounts
- `locked` (boolean) - whether pointer lock is active
- `camera` - the Camera this Pointer last interacted with

Key methods:
- `leftButtonDown()`, `rightButtonDown()`, `middleButtonDown()`, `backButtonDown()`, `forwardButtonDown()` - check specific buttons
- `leftButtonReleased()`, `rightButtonReleased()`, `middleButtonReleased()` - check recent release
- `getDistance()` - distance between down position and current/up position
- `getDistanceX()`, `getDistanceY()` - horizontal/vertical distance
- `getDuration()` - ms between down and current time or up time
- `getAngle()` - angle between down and current/up position
- `updateWorldPoint(camera)` - recalculate worldX/worldY for a given camera
- `positionToCamera(camera, output)` - translate pointer position through a camera

### Interactive Game Objects (setInteractive)

Call `gameObject.setInteractive()` to enable input on a Game Object. This uses the texture frame as the hit area by default.

```js
// 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();
```

## Common Patterns

### Keyboard Input (cursors, addKey, isDown, JustDown)

**Cursor keys** return an object with `up`, `down`, `left`, `right`, `space`, `shift` Key objects:

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

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

**addKey** creates a Key object for any key:

```js
// 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** creates multiple keys at once:

```js
// 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({