Input Keyboard Mouse Touch

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 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.

// 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:

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:

// 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:

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