# Phaserjs Phaser Phaser > Input: Keyboard, Mouse, Touch, and Gamepad - Skill: `tomevault-io/phaserjs-phaser-phaser` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/phaserjs-phaser-phaser` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/phaserjs-phaser-phaser/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/phaserjs-phaser-phaser --- # 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({ up: Phaser.Input.Keyboard.KeyCodes.W, down: Phaser.Input.Keyboard.KeyCodes.S, left: Phaser.Input.Keyboard.KeyCodes.A, right: Phaser.Input.Keyboard.KeyCodes.D }); ``` **Polling vs events:** ```js // Polling in update() - check every frame if (keyW.isDown) { /* key is currently held */ } if (keyW.isUp) { /* key is currently released */ } // JustDown - returns true only once per press, resets after check if (Phaser.Input.Keyboard.JustDown(keyW)) { /* fire once */ } if (Phaser.Input.Keyboard.JustUp(keyW)) { /* released once */ } // checkDown with duration - throttled polling if (this.input.keyboard.checkDown(keySpace, 250)) { // true at most once every 250ms while held } // Event-driven: listen for specific key this.input.keyboard.on('keydown-SPACE', (event) => { /* ... */ }); this.input.keyboard.on('keyup-SPACE', (event) => { /* ... */ }); // Event-driven: listen for any key this.input.keyboard.on('keydown', (event) => { console.log(event.key); // native DOM KeyboardEvent }); // Event on a Key object itself const spaceBar = this.input.keyboard.addKey('SPACE'); spaceBar.on('down', (key, event) => { /* Key object + native event */ }); spaceBar.on('up', (key, event) => { /* ... */ }); ``` **Key object properties:** - `isDown` / `isUp` (boolean) - `keyCode` (number) - `altKey`, `ctrlKey`, `shiftKey`, `metaKey` (boolean) - modifier state when pressed - `duration` (number) - ms held in previous down-up cycle - `timeDown`, `timeUp` (number) - timestamps - `repeats` (number) - repeat count while held - `emitOnRepeat` (boolean) - if true, fires 'down' event on each repeat - `enabled` (boolean) - can this key be processed **Prevent browser default behavior:** ```js // Capture specific keys to prevent browser scrolling etc. this.input.keyboard.addCapture('SPACE,UP,DOWN,LEFT,RIGHT'); this.input.keyboard.addCapture([ 32, 37, 38, 39, 40 ]); this.input.keyboard.removeCapture('SPACE'); // Note: captures are global across all Scenes ``` **Common KeyCodes:** `BACKSPACE(8)`, `TAB(9)`, `ENTER(13)`, `SHIFT(16)`, `CTRL(17)`, `ALT(18)`, `ESC(27)`, `SPACE(32)`, `LEFT(37)`, `UP(38)`, `RIGHT(39)`, `DOWN(40)`, `A-Z(65-90)`, `ZERO-NINE(48-57)`, `F1-F12(112-123)`. Access via `Phaser.Input.Keyboard.KeyCodes.SPACE` etc. ### Mouse/Pointer Click and Hover **Scene-level pointer events** (fire anywhere on the canvas): ```js this.input.on('pointerdown', (pointer, currentlyOver) => { // pointer: Pointer object, currentlyOver: array of interactive Game Objects under pointer }); this.input.on('pointerup', (pointer, currentlyOver) => { /* ... */ }); this.input.on('pointermove', (pointer, currentlyOver) => { /* ... */ }); this.input.on('wheel', (pointer, currentlyOver, deltaX, deltaY, deltaZ) => { /* ... */ }); ``` **Game Object pointer events** (require setInteractive): ```js sprite.setInteractive(); // pointerdown on this specific object sprite.on('pointerdown', (pointer, localX, localY, event) => { // localX/localY are relative to the Game Object's top-left // event.stopPropagation() prevents the event from going further }); sprite.on('pointerup', (pointer, localX, localY, event) => { /* ... */ }); sprite.on('pointermove', (pointer, localX, localY, event) => { /* ... */ }); sprite.on('pointerover', (pointer, localX, localY, event) => { /* ... */ }); sprite.on('pointerout', (pointer, event) => { /* ... */ }); sprite.on('wheel', (pointer, deltaX, deltaY, deltaZ, event) => { /* ... */ }); ``` **Right-click handling:** ```js this.input.on('pointerdown', (pointer) => { if (pointer.rightButtonDown()) { // right-click } }); // Disable context menu this.input.mouse.disableContextMenu(); ``` **Pointer lock (FPS-style mouse capture):** ```js // Request lock on click this.input.on('pointerdown', () => { this.input.mouse.requestPointerLock(); }); this.input.on('pointerlockchange', (event, locked) => { // locked: boolean }); // Read relative movement while locked // pointer.movementX, pointer.movementY ``` ### Drag and Drop ```js const sprite = this.add.sprite(400, 300, 'item'); sprite.setInteractive(); this.input.setDraggable(sprite); // Or use config: // sprite.setInteractive({ draggable: true }); // Drag events on the Scene input this.input.on('dragstart', (pointer, gameObject) => { gameObject.setTint(0xff0000); }); this.input.on('drag', (pointer, gameObject, dragX, dragY) => { gameObject.x = dragX; gameObject.y = dragY; }); this.input.on('dragend', (pointer, gameObject) => { gameObject.clearTint(); }); // Drop zones const zone = this.add.zone(600, 300, 200, 200).setRectangleDropZone(200, 200); this.input.on('drop', (pointer, gameObject, dropZone) => { gameObject.x = dropZone.x; gameObject.y = dropZone.y; }); this.input.on('dragenter', (pointer, gameObject, dropZone) => { /* ... */ }); this.input.on('dragleave', (pointer, gameObject, dropZone) => { /* ... */ }); this.input.on('dragover', (pointer, gameObject, dropZone) => { /* ... */ }); ``` Game Object-level drag events are also available: ```js sprite.on('drag', (pointer, dragX, dragY) => { sprite.x = dragX; sprite.y = dragY; }); sprite.on('dragstart', (pointer, dragX, dragY) => { /* ... */ }); sprite.on('dragend', (pointer, dragX, dragY) => { /* ... */ }); sprite.on('drop', (pointer, dropZone) => { /* ... */ }); ``` Drag thresholds: ```js this.input.dragDistanceThreshold = 16; // must move 16px before drag starts this.input.dragTimeThreshold = 200; // must hold 200ms before drag starts ``` ### Three Levels of Pointer Events Pointer events fire at three levels (see [reference](references/REFERENCE.md#three-levels-of-pointer-events) for details): 1. **Game Object**: `gameObject.on('pointerdown', (pointer, localX, localY, event) => {})` 2. **Scene per-object**: `this.input.on('gameobjectdown', (pointer, gameObject, event) => {})` 3. **Scene global**: `this.input.on('pointerdown', (pointer, currentlyOver) => {})` ### Input Debug, topOnly, and Multi-touch Config ```js // Debug visualize hit areas this.input.enableDebug(gameObject); this.input.enableDebug(gameObject, 0xff00ff); this.input.removeDebug(gameObject); // Let all objects under pointer receive events (not just top-most) this.input.topOnly = false; this.input.setTopOnly(false); ``` Multi-touch: set `config.input.activePointers` to reserve pointer slots at startup, or call `this.input.addPointer(num)` at runtime. Access via `this.input.pointer1` through `pointer10`. ### Gamepad Input Enable gamepads in the game config: ```js const config = { input: { gamepad: true } }; ``` Access via `this.input.gamepad`. Gamepads are available as `pad1` through `pad4`: ```js // Wait for connection this.input.gamepad.once('connected', (pad) => { console.log('Gamepad connected:', pad.id); }); // If already connected, check total if (this.input.gamepad.total > 0) { const pad = this.input.gamepad.pad1; } ``` **Polling gamepad state in update():** ```js update() { const pad = this.input.gamepad.pad1; if (!pad) return; // D-pad (boolean properties) if (pad.up) { /* d-pad up */ } if (pad.down) { /* d-pad down */ } if (pad.left) { /* d-pad left */ } if (pad.right) { /* d-pad right */ } // Face buttons (boolean) - Xbox naming convention if (pad.A) { /* bottom button (Xbox A / PS X) */ } if (pad.B) { /* right button (Xbox B / PS Circle) */ } if (pad.X) { /* left button (Xbox X / PS Square) */ } if (pad.Y) { /* top button (Xbox Y / PS Triangle) */ } // Shoulder buttons (float 0-1) if (pad.L1 > 0) { /* left shoulder top (LB) */ } if (pad.L2 > 0) { /* left shoulder bottom / trigger (LT) */ } if (pad.R1 > 0) { /* right shoulder top (RB) */ } if (pad.R2 > 0) { /* right shoulder bottom / trigger (RT) */ } // Analog sticks (Vector2, values -1 to 1) const lx = pad.leftStick.x; // left stick horizontal const ly = pad.leftStick.y; // left stick vertical const rx = pad.rightStick.x; const ry = pad.rightStick.y; // Raw axis/button access pad.getAxisValue(0); // float pad.getButtonValue(0); // float 0-1 pad.isButtonDown(0); // boolean pad.setAxisThreshold(0.1); // ignore values below threshold } ``` **Gamepad events:** ```js // Plugin-level events (any gamepad) this.input.gamepad.on('connected', (pad, event) => { /* ... */ }); this.input.gamepad.on('disconnected', (pad, event) => { /* ... */ }); this.input.gamepad.on('down', (pad, button, value) => { /* any button on any pad */ }); this.input.gamepad.on('up', (pad, button, value) => { /* ... */ }); // Gamepad-instance events pad.on('down', (index, value, button) => { /* button on this specific pad */ }); pad.on('up', (index, value, button) => { /* ... */ }); ``` **Vibration (experimental, hardware/browser dependent):** ```js if (pad.vibration) { pad.vibration.playEffect('dual-rumble', { duration: 200, strongMagnitude: 1.0, weakMagnitude: 0.5 }); } ``` ### Key Combos Listen for a sequence of keys: ```js // String-based combo this.input.keyboard.createCombo('PHASER'); // Array of key codes (Konami code) this.input.keyboard.createCombo( [ 38, 38, 40, 40, 37, 39, 37, 39, 66, 65, 13 ], { resetOnMatch: true } ); // Listen for match this.input.keyboard.on('keycombomatch', (keyCombo, event) => { console.log('Combo matched!'); }); ``` **createCombo(keys, config):** - `keys`: a string (each character is a key) or an array of key codes / Key objects - `config.resetOnWrongKey` (boolean, default true) - reset progress if wrong key is pressed - `config.maxKeyDelay` (number, default 0) - max ms between key presses; 0 = no limit - `config.resetOnMatch` (boolean, default false) - reset combo after a successful match - `config.deleteOnMatch` (boolean, default false) - remove combo after first match For detailed configuration options, API reference tables, and source file maps, see [the reference guide](references/REFERENCE.md). --- > Source: [phaserjs/phaser](https://github.com/phaserjs/phaser) — distributed by [TomeVault](https://tomevault.io).