/p5.joystick

Connect and play with physical joysticks

Primary LanguageJavaScriptMIT LicenseMIT

p5.joystick.js

p5.joystick Thumbnail

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.

p5.joystick calibration process

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){});