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)