Input Keyboard Mouse Touch — Reference

Detailed configuration, API tables, and source file maps for the input-keyboard-mouse-touch skill.

Events (input events with callback signatures)

Keyboard Events (on this.input.keyboard)

Key Object Events (on a Key instance)

Pointer Events (on this.input)

Game Object Pointer Events (on an interactive Game Object)

All Game Object events provide event.stopPropagation() to halt further event flow.

Scene Per-Object Pointer Events (on this.input, Level 2)

Game Object Drag Events (on an interactive, draggable Game Object)

Drag Events (on this.input)

Gamepad Events (on this.input.gamepad)

Event Dispatch Order (pointer events)

For down/up/move events, the dispatch order is:

1. GAMEOBJECT_POINTER_DOWN (on the Game Object itself)
2. GAMEOBJECT_DOWN (on this.input with Game Object as param)
3. POINTER_DOWN (on this.input, scene-wide)

Higher-priority handlers can call event.stopPropagation() to prevent lower ones from firing.

API Quick Reference

InputPlugin (this.input)

KeyboardPlugin (this.input.keyboard)

Keyboard Utility Functions

Pointer

Gamepad

Three Levels of Pointer Events

Phaser dispatches pointer events at three levels, in this order:

Level 1 — Game Object events (most specific, require setInteractive()):

gameObject.on('pointerdown', (pointer, localX, localY, event) => {});
gameObject.on('pointerup', (pointer, localX, localY, event) => {});
gameObject.on('pointermove', (pointer, localX, localY, event) => {});
gameObject.on('pointerover', (pointer, localX, localY, event) => {});
gameObject.on('pointerout', (pointer, event) => {});
gameObject.on('wheel', (pointer, dx, dy, dz, event) => {});

Level 2 — Scene input per-object events (fires with the Game Object as a parameter):

this.input.on('gameobjectdown', (pointer, gameObject, event) => {});
this.input.on('gameobjectup', (pointer, gameObject, event) => {});
this.input.on('gameobjectmove', (pointer, gameObject, event) => {});
this.input.on('gameobjectover', (pointer, gameObject, event) => {});
this.input.on('gameobjectout', (pointer, gameObject, event) => {});
this.input.on('gameobjectwheel', (pointer, gameObject, dx, dy, dz, event) => {});

Level 3 — Scene input global events (fires regardless of what is under the pointer):

this.input.on('pointerdown', (pointer, currentlyOver) => {});
this.input.on('pointerup', (pointer, currentlyOver) => {});
this.input.on('pointermove', (pointer, currentlyOver) => {});
this.input.on('wheel', (pointer, currentlyOver, dx, dy, dz, event) => {});

At any level, call event.stopPropagation() to prevent the event from reaching the next level.

Hit Area Shapes (All Geometry Types)

// Default (rectangle from texture)
gameObject.setInteractive();

// Circle
gameObject.setInteractive(new Phaser.Geom.Circle(x, y, radius), Phaser.Geom.Circle.Contains);

// Ellipse
gameObject.setInteractive(new Phaser.Geom.Ellipse(x, y, w, h), Phaser.Geom.Ellipse.Contains);

// Rectangle
gameObject.setInteractive(new Phaser.Geom.Rectangle(x, y, w, h), Phaser.Geom.Rectangle.Contains);

// Triangle
gameObject.setInteractive(new Phaser.Geom.Triangle(x1, y1, x2, y2, x3, y3), Phaser.Geom.Triangle.Contains);

// Polygon (array of {x,y} points or flat [x1,y1,x2,y2,...] array)
gameObject.setInteractive(new Phaser.Geom.Polygon(points), Phaser.Geom.Polygon.Contains);

// Pixel-perfect (expensive — only use where needed)
gameObject.setInteractive({ pixelPerfect: true, alphaTolerance: 1 });

Full setInteractive Config Object

gameObject.setInteractive({
    hitArea: shape,              // Geom shape (Circle, Rectangle, etc.)
    hitAreaCallback: callback,   // Contains function for the shape
    draggable: false,            // Enable drag-and-drop
    dropZone: false,             // Mark as a drop zone
    useHandCursor: false,        // Show hand cursor on hover
    cursor: 'pointer',           // CSS cursor string
    pixelPerfect: false,         // Use pixel-perfect hit testing
    alphaTolerance: 1            // Alpha threshold for pixel-perfect (0-255)
});

Input Debug Mode

Visualize hit areas for debugging interactive objects:

// Enable debug overlay (default green outline)
this.input.enableDebug(gameObject);

// Custom color
this.input.enableDebug(gameObject, 0xff00ff);

// Remove debug overlay
this.input.removeDebug(gameObject);

Multi-touch Configuration

By default, Phaser creates 2 pointers (mouse + 1 touch). Configure more at startup or runtime:

// At startup via game config
const config = {
    input: {
        activePointers: 4  // reserve 4 pointer slots
    }
};

// At runtime
this.input.addPointer(3); // add 3 more pointers (up to 10 total)

// Access individual pointers
this.input.pointer1; // first touch pointer
this.input.pointer2; // second touch pointer
// ... through this.input.pointer10
this.input.mousePointer; // the mouse (always pointer index 0)

Keyboard Combos (String Array Form)

// Using key name strings
const combo = this.input.keyboard.createCombo(['UP', 'UP', 'DOWN', 'DOWN'], {
    resetOnWrongKey: true,
    maxKeyDelay: 0,
    resetOnMatch: false
});

this.input.keyboard.on('keycombomatch', (keyCombo, event) => {
    console.log('Combo matched:', keyCombo);
});

Gamepad Additional Methods

// Get all connected gamepads as an array
const pads = this.input.gamepad.getAll();

// Get a specific gamepad by index
const pad = this.input.gamepad.getPad(0);

// Gamepad instance events (different callback signature from plugin-level)
// Plugin-level: (gamepad, button, value)
pad.on('down', (buttonIndex, value, button) => {});
pad.on('up', (buttonIndex, value, button) => {});

Gotchas and Common Mistakes

1. Must call setInteractive() before listening for Game Object events. Without it, pointerdown etc. will never fire on that object.

2. Containers need a size for hit testing. Call container.setSize(w, h) or pass a shape to setInteractive(). Pixel-perfect testing does not work on Containers.

3. JustDown/JustUp only return true once per check. They consume the flag on read, so calling JustDown(key) twice in the same frame gives true then false. Store the result in a variable if needed in multiple places.

4. Keyboard captures are global. Calling addCapture('SPACE') in one Scene prevents the browser default for all Scenes, not just the calling Scene.

5. Browser extensions can interfere with keyboard input. Extensions like Vimium can intercept keys (e.g. D key). Check extensions when debugging missing key events.

6. Pointer worldX/worldY are only accurate inside input handlers. Outside of event callbacks, call pointer.updateWorldPoint(camera) first to get correct camera-translated coordinates.

7. topOnly defaults to true. Only the top-most interactive Game Object under the pointer receives events. Set this.input.topOnly = false to emit to all objects below the pointer.

8. Gamepad requires SSL in modern browsers. Chrome and others block the Gamepad API on non-HTTPS pages. The browser may also require a button press before exposing the gamepad.

9. Gamepad may already be connected. The 'connected' event only fires on new connections. Check this.input.gamepad.total on Scene start and use pad1-pad4 if already present.

10. Drag events require both setInteractive and setDraggable. Just calling setInteractive() is not enough; you must also call this.input.setDraggable(sprite) or use the { draggable: true } config.

11. Pointer lock must be requested from a user gesture. Call this.input.mouse.requestPointerLock() from inside a pointerdown or pointerup handler.

12. Key.emitOnRepeat defaults to false. By default, holding a key only emits one 'down' event. Set emitOnRepeat to true in addKey() or on the Key to get continuous events.

13. Pixel-perfect hit testing is expensive. It checks every pixel under the pointer against the texture alpha. Only use pixelPerfect: true where irregular shapes truly require it; prefer geometric hit areas (Circle, Polygon) for performance.

14. No touch input events during the preload stage. Touch/pointer events are not dispatched while the Scene is in the preload phase. Wait for create to set up interactive objects.

15. In multi-camera scenes, check pointer.camera. When a Scene has multiple cameras, the pointer event includes which camera received it via pointer.camera. Use this to determine which camera viewport was clicked.

16. Gamepad callback signatures differ between plugin and instance. Plugin-level events use (gamepad, button, value) while per-gamepad instance events use (buttonIndex, value, button). Mixing these up is a common source of bugs.

Source File Map