/input-keyboard-mouse-touch

name: input-keyboard-mouse-touch
description: "Use this skill when handling user input in Phaser 4. Covers keyboard keys, mouse clicks and movement, touch events, pointer handling, drag and drop, hit areas, interactive objects, and gamepad support. Triggers on: keyboard, mouse, touch, pointer, drag, drop, click, input, gamepad, cursor keys."

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)

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