p5.joystick

p5.joystick.js

Overview

The p5.joystick library aims to facilitate integration with physical Joysticks.

It also has an easy calibration system, allowing you to configure different types of joysticks with the standard button format.

This library uses the gamepad API.

Through them it is possible to read directly the status of each joystick. This library also make possible an event based approach.

Installation

It is necessary to insert p5.joystick.js in your html:

<script src="js/p5.js"></script>
<script src="p5.joystick.js"></script>
<script src="sketch.js"></script>

Usage

var joystick;

function setup() {
  createCanvas(window.innerWidth, window.innerHeight);

  joystick = createJoystick();
  if(!joystick.calibrated())
    joystick.calibrate(true);
  joystick.onButtonPressed(onJoystick);
  joystick.onButtonReleased(onJoystick);
  joystick.onAxesPressed(onJoystick);
  joystick.onAxesReleased(onJoystick);
}

function draw(){
  background(100);
  joystick.draw(width/2, height/2);
}

function onJoystick(e) {
  console.log("onJoystick", e);
}

Calibrating

Calibration associates each button on the virtual joystick with the physical joystick. You can make different combinations as you wish.

The calibration is automatically saved and loaded into a cookie.

Methods

createJoystick([debug])

Initializes built-in listeners to integrate with gamepad API.

Parameter	Type	Required	Description
debug	Boolean	No	If true, adds html elements to monitor all connected joysticks and the state of each button.

draw(x, y, [width], [height])

Draws a joystick on the screen in the desired position and size.

Parameter	Type	Required	Description
x	Number	Yes	horizontal position on screen.
y	Number	Yes	vertical position on the screen.
width	Number	No	Width of the joystick. Standard value: 440.
height	Number	No	Height of the joystick. Standard value: 200.

Notice: The drawing axis is centered, so the joystick is drawn around the x and y coordinates.

calibrate(enable)

Enable/Disable calibration mode.

Parameter	Type	Required	Description
enable	Boolean	Yes	Enable/Disable calibration mode.

getButtonPressedByName(name)

Returns a boolean button state: true or false.

Parameter	Type	Required	Description
gamepadIndex	Integer	Yes	Joystick index.
name	String	Yes	Button name: sholderLeft, sholderRight, axesUp, axesDown, axesLeft, axesRight, buttonBlue, buttonYellow, buttonRed, buttonGreen, start or select.

Notice: Only works when calibrated.

getButtonPressedByIndex(gamepadIndex, buttonIndex)

Returns a boolean button state: true or false.

Parameter	Type	Required	Description
gamepadIndex	Integer	Yes	Joystick index.
buttonIndex	Integer	Yes	Button index.

getAxesValueByIndex(gamepadIndex, axesIndex)

Returns a integer axis state: -1, 0, 1.

Parameter	Type	Required	Description
gamepadIndex	Integer	Yes	Joystick index.
axesIndex	Integer	Yes	Axes index.

Events

Events return an object with the following properties:

Property	Type	Description
gamepadName	String	Joystick name.
gamepadIndex	Integer	Joystick index.
index	Integer	Button index.
name	String	Button name: sholderLeft, sholderRight, axesUp, axesDown, axesLeft, axesRight, buttonBlue, buttonYellow, buttonRed, buttonGreen, start or select. Return empty "" if the joystick is not calibrated.
pressed	Boolean	Button is pressed or not.
type	String	Button type: axes or button.
value	Integer	"axes" can return directions -1, 0 or 1, and buttons can return 0 or 1.

There are 4 types of events:

onButtonPressed

Triggered when a button is pressed.

joystick.onButtonPressed(function(eventObj){});

onButtonReleased

Triggered when a button is released.

joystick.onButtonReleased(function(eventObj){});

onAxesPressed

Triggered when an axes is pressed.

joystick.onAxesPressed(function(eventObj){});

onAxesReleased

Triggered when an axes is released.

joystick.onAxesReleased(function(eventObj){});