Merged input plugin for Phaser 3

A Phaser 3 plugin to map input from keyboard, gamepad & mouse to player actions.

The merged input plugin listens to input from keyboard, connected gamepads and the mouse pointer, updating ‘player’ objects that you may interrogate instead of writing separate input handlers in your game. Each player object contains direction and button actions. These are updated by the corresponding gamepad input, as well as any keys that you assign to the action.

Benefits

. Single place to handle all your input.
. Keyboard, Gamepad & Mouse input is amalgamated.
. Handle input for multiple player objects to easily create multiplayer games.
. Assign and reassign keys to actions for each player, allowing for ‘redefine keys’ function.
. Assign multiple keys to a single action.
. Interrogate current state of all buttons.
. Global events emitted on button down/up.
. Check for gamepad button presses (i.e. ‘justDown()’ functionality for gamepads)
. Check the last device type used for interaction.

Setup

Set up a player object for each player in your game with addPlayer(). Then assign keys to each action with the defineKey() function, e.g.

var player1 = mergedInput.addPlayer(0);
mergedInput.defineKey(0, 'UP', 'W')
    .defineKey(0, 'DOWN', 'S')
    .defineKey(0, 'LEFT', 'A')
    .defineKey(0, 'RIGHT', 'D')
    .defineKey(0, 'B0', 'U')
    .defineKey(0, 'B1', 'I')
    .defineKey(0, 'B2', 'O')
    .defineKey(0, 'B3', 'P')

var player2 = mergedInput.addPlayer(1);
mergedInput.defineKey(1, 'UP', 'UP')
    .defineKey(1, 'DOWN', 'DOWN')
    .defineKey(1, 'LEFT', 'LEFT')
    .defineKey(1, 'RIGHT', 'RIGHT')
    .defineKey(1, 'B0', 'NUMPAD_0')
    .defineKey(1, 'B1', 'NUMPAD_1')
    .defineKey(1, 'B2', 'NUMPAD_2')
    .defineKey(1, 'B3', 'NUMPAD_3')

Then, interrogate your player objects to check for the state of the action, rather than the key, e.g.

    if(player1.direction.DOWN) {
        // Move your player down
    }

    if(player2.buttons.B0 > 0) {
        // Player two is pressing the first button
    }

Demo / Dev

A demo scene is included in the repository.

Install with npm install, then use npm run dev to spin up a development server and run the demo scene.

Build plugin

Build the plugin including minified version. Targets the dist folder. npm run build

Changelog

v1.1.0 - 2020-04-19 Plugin now handles secondary directional movement from the second stick on a gamepad. Bearings and degrees have been added to direction objects.

v1.2.0 - 2020-04-27 You are now able to pass a player's X/Y position to a player object, whereupon the position of the mouse in relation to that player will be used to determine mouse bearings and degrees

v1.2.1 - 2020-04-27 Actually added the build files.

v1.2.2 - 2020-05-03 Added secondary direction key detection, so that secondary directions may be instigated through a keypress as well as the right stick of a gamepad. Added timestamps to interactions making it possible to tell which was last used, e.g. keyboard vs mouse.

v1.2.3 - 2020-05-08 Added extra handling for 'null' gamepads.

v1.2.4 - 2020-05-08 And again, remembering to include the built files would be a bonus.

v1.2.5 - 2021-05-04 Updated buttondown and buttonup event listeners from per pad, to per input system. It seems the per pad listeners weren't firing for pad 2 and this method works around the problem. Also added an addPlayer call if the corresponding player is missing. Updated phaser dependancy

v1.2.6 - 2021-05-04 Guess who forgot to build again??

v1.2.7 - 2021-07-06 Changed the order of buffer/pressed checking in update loop.

Credits

Written by Gary Stanton
Built from the Plugin Starter Kit by Niklas Berg
Demo sprites by Nicolae Berbece

Functions

addPlayer(index): Add a new player object to the players array.
If an index is provided and a player object at that index already exists, this will be returned instead of another object created
getPlayer(thisPlayer): Get player object
setupControls(): Returns a struct to hold input control information Set up a struct for each player in the game Direction and Buttons contain the input from the devices The keys struct contains arrays of keyboard characters or mouse buttons that will trigger the action
defineKey(player, action, value, append): Define a key for a player/action combination
checkKeyboardInput(): Iterate through players and check for interaction with defined keys
gamepadButtonDown(index, value, button): When a gamepad button is pressed down, this function will emit a mergedInput event in the global registry. The event contains a reference to the player assigned to the gamepad, and passes a mapped action and value
gamepadButtonUp(index, value, button): When a gamepad button is released, this function will emit a mergedInput event in the global registry. The event contains a reference to the player assigned to the gamepad, and passes a mapped action and value
checkGamepadInput(): Iterate through gamepads and handle interactions

addPlayer()

Add a new player object to the players array

Param	Type
index	`number`

getPlayer(index)

Get player object

Param	Type
thisPlayer	`number`

setupControls()

Returns a struct to hold input control information Set up a struct for each player in the game Direction and Buttons contain the input from the devices The keys struct contains arrays of keyboard characters that will trigger the action

defineKey(player, action, value, append)

Define a key for a player/action combination

Param	Type	Default	Description
player	`number`	`0`	The player on which we're defining a key
action	`string`		The action to define
value	`string`		The key to use
append	`boolean`	`false`	When true, this key definition will be appended to the existing key(s) for this action

checkKeyboardInput()

Iterate through players and check for interaction with defined keys

gamepadButtonDown(index, value, button)

When a gamepad button is pressed down, this function will emit a mergedInput event in the global registry. The event contains a reference to the player assigned to the gamepad, and passes a mapped action and value

Param	Type	Description
index	`number`	Button index
value	`number`	Button value
button	`Phaser.Input.Gamepad.Button`	Phaser Button object

gamepadButtonUp(index, value, button)

When a gamepad button is released, this function will emit a mergedInput event in the global registry. The event contains a reference to the player assigned to the gamepad, and passes a mapped action and value

Param	Type	Description
index	`number`	Button index
value	`number`	Button value
button	`Phaser.Input.Gamepad.Button`	Phaser Button object

checkGamepadInput()

Iterate through gamepads and handle interactions

bbugh/phaser3-merged-input