Joystick Controller

A fully customizable JavaScript virtual joystick controller for both desktop and mobile devices supporting multi instances. Live Demo

Installation

npm install joystick-controller

Quick Start

import JoystickController from "joystick-controller";

const joystick = new JoystickController({}, (data) => console.log(data));

JoystickController also supports CommonJS and global (CDN) import styles.

CDN / unpkg

<script src="https://unpkg.com/joystick-controller/dist/joystick-controller.umd.js"></script>
<script>
  // Unwrap the module namespace to get the class
  const JoystickController = window.JoystickController.default;
  const joystick = new JoystickController({}, (data) => console.log(data));
</script>

Browser Support

Requires the Pointer Events API, supported in all modern browsers (Chrome 55+, Firefox 59+, Safari 13+, Edge 12+).

Options

You can pass a set of options as the first argument to further customize your joystick controller.

| Name | Type | Default | Description | | --------------------- | -------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | maxRange | number | 100 | Maximum range of the joystick dot (number of pixels) | | level | number | 10 | Number of levels of the joystick (e.g. 10 returns integers between -10 and 10) | | radius | number | 50 | Radius of the joystick container (number of pixels) | | joystickRadius | number | 30 | Radius of the joystick inner dot (number of pixels) | | opacity | number | 0.8 | Opacity of the joystick | | containerClass | string | '' | Class for the joystick container for adding additional styles (outer container) | | controllerClass | string | '' | Class for the joystick controller for adding additional styles (inner container) | | joystickClass | string | '' | Class for the joystick dot for adding additional styles | | leftToRight | boolean | true | x position from left (ignored if dynamicPosition=true) | | bottomToUp | boolean | true | y position from bottom (ignored if dynamicPosition=true) | | x | string | '50%' | x position on screen — maps to CSS left/right (ignored if dynamicPosition=true) | | y | string | '50%' | y position on screen — maps to CSS bottom/top (ignored if dynamicPosition=true) | | distortion | boolean | false | If true, the joystick dot distorts visually when pushed to the edge | | dynamicPosition | boolean | false | Shows the joystick at the position where the user clicks/touches | | dynamicPositionTarget | HTMLElement | null | If dynamicPosition is true, listens for events on this element (defaults to document) | | mouseClickButton | string|number | "ALL" (-1) | Mouse button that activates the joystick (ALL, LEFT, MIDDLE, RIGHT, or a button number from -1 to 4; -1 for all) | | hideContextMenu | boolean | false | If true, suppresses the context menu on right-click (recommended with dynamicPosition) |

Callback Arguments

The callback fires on every move event and once on release (all values reset to 0).

| Name | Type | Description | | -------- | ------ | ---------------------------------------------------------------------------------------- | | x | number | x position of the joystick relative to its center | | y | number | y position of the joystick relative to its center | | leveledX | number | x scaled and rounded to an integer between -level and +level | | leveledY | number | y scaled and rounded to an integer between -level and +level | | angle | number | angle of the line from the center to the dot, in radians | | distance | number | distance of the dot from the center |

Customized Example

All options are optional. A fully customized instance looks like this:

// Static joystick
const staticJoystick = new JoystickController(
  {
    maxRange: 70,
    level: 10,
    radius: 50,
    joystickRadius: 30,
    opacity: 0.5,
    leftToRight: false,
    bottomToUp: true,
    containerClass: "joystick-container",
    controllerClass: "joystick-controller",
    joystickClass: "joystick",
    distortion: true,
    x: "25%",
    y: "25%",
    mouseClickButton: "ALL",
    hideContextMenu: false,
  },
  ({ x, y, leveledX, leveledY, distance, angle }) =>
    console.log(x, y, leveledX, leveledY, distance, angle)
);

// Dynamic position joystick
const dynamicJoystick = new JoystickController(
  {
    maxRange: 70,
    level: 10,
    radius: 50,
    joystickRadius: 30,
    opacity: 0.5,
    containerClass: "joystick-container",
    controllerClass: "joystick-controller",
    joystickClass: "joystick",
    distortion: true,
    dynamicPosition: true,
    dynamicPositionTarget: document.getElementById("root"),
    mouseClickButton: "ALL",
    hideContextMenu: true,
  },
  ({ x, y, leveledX, leveledY, distance, angle }) =>
    console.log(x, y, leveledX, leveledY, distance, angle)
);

Clean Up

Call destroy() to remove all event listeners and the joystick element from the DOM.

joystick.destroy();

Copyright(c) Cyrus Mobini 2024

License MIT