# p5.joystick

> Connect and play with physical joysticks

Latest version **1.0.0** (published 2024-03-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install p5.joystick
pnpm add p5.joystick
yarn add p5.joystick
bun add p5.joystick
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2024-03-13 |
| First published | 2024-03-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 50.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Author | Vamoss |
| Maintainers | vamoss |
| Keywords | p5js, joystick, gamepad, physical, calibration, hardware |

## Links

- npm: https://www.npmjs.com/package/p5.joystick
- Repository: https://github.com/Vamoss/p5.joystick
- Homepage: https://github.com/Vamoss/p5.joystick#readme
- Issues: https://github.com/Vamoss/p5.joystick/issues
- npm.io page: https://npm.io/package/p5.joystick

## Recent versions

- 1.0.0 (latest) — 2024-03-13

## README

# p5.joystick.js

![p5.joystick Thumbnail](thumbnail.jpg)

## 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](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_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:
```js
<script src="js/p5.js"></script>
<script src="p5.joystick.js"></script>
<script src="sketch.js"></script>
```

### Usage

```js
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](calibration.gif)



## 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.
```js
joystick.onButtonPressed(function(eventObj){});
```

### onButtonReleased

Triggered when a button is released.
```js
joystick.onButtonReleased(function(eventObj){});
```

### onAxesPressed

Triggered when an axes is pressed.
```js
joystick.onAxesPressed(function(eventObj){});
```

### onAxesReleased

Triggered when an axes is released.
```js
joystick.onAxesReleased(function(eventObj){});
```

---
_Source: https://npm.io/package/p5.joystick · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._