|
| 1 | +# @melonjs/gamepad-plugin |
| 2 | + |
| 3 | +On-screen touch controls for [melonJS](https://melonjs.org/) games, reported as a gamepad. |
| 4 | + |
| 5 | +The sticks and buttons are drawn over the game and read by the engine as a pad in a gamepad slot, so everything a game binds with `input.bindGamepad` answers to them. One set of bindings covers a real pad and the touch controls. |
| 6 | + |
| 7 | +- one or two sticks, analog, with a deadzone, and pressing the D-pad in 8 directions |
| 8 | +- any number of buttons, each pressing a pad button or a key, that a game can relabel, dim or hide |
| 9 | +- each finger followed on its own: hold the stick and press a button at the same time |
| 10 | +- a touch that starts on the controls does not reach the game |
| 11 | +- drawn over the whole frame, above every renderable and every camera (a minimap does not show them), and kept across stage changes |
| 12 | +- drawn with the renderer's own shapes: no images to load |
| 13 | +- hidden while the player uses a real pad, and back on the next touch |
| 14 | +- `input.vibrateGamepad` vibrates the phone, where the browser can |
| 15 | + |
| 16 | +## Install |
| 17 | + |
| 18 | +```sh |
| 19 | +npm install melonjs @melonjs/gamepad-plugin |
| 20 | +``` |
| 21 | + |
| 22 | +It needs melonJS 20.12 or later. |
| 23 | + |
| 24 | +## Quick start |
| 25 | + |
| 26 | +```ts |
| 27 | +import { Application, input, plugin } from "melonjs"; |
| 28 | +import { GamepadPlugin } from "@melonjs/gamepad-plugin"; |
| 29 | + |
| 30 | +const app = new Application(1024, 768, { parent: "screen", scaleMethod: "flex" }); |
| 31 | +await app.init(); |
| 32 | + |
| 33 | +// a stick and two buttons, shown on touch screens |
| 34 | +plugin.register(GamepadPlugin, "gamepad", { |
| 35 | + buttons: [{ label: "A" }, { label: "B" }], |
| 36 | +}); |
| 37 | + |
| 38 | +// the game binds the pad as it would a real one |
| 39 | +input.bindKey(input.KEY.LEFT, "left"); |
| 40 | +input.bindKey(input.KEY.RIGHT, "right"); |
| 41 | +input.bindKey(input.KEY.X, "jump", true); |
| 42 | +input.bindGamepad(0, { type: "buttons", code: input.GAMEPAD.BUTTONS.LEFT }, input.KEY.LEFT); |
| 43 | +input.bindGamepad(0, { type: "buttons", code: input.GAMEPAD.BUTTONS.RIGHT }, input.KEY.RIGHT); |
| 44 | +input.bindGamepad(0, { type: "buttons", code: input.GAMEPAD.BUTTONS.FACE_1 }, input.KEY.X); |
| 45 | +``` |
| 46 | + |
| 47 | +The stick presses the D-pad buttons as it leans, and reports its analog position on `GAMEPAD.AXES.LX` and `LY`, which a game can bind with a `threshold` or read on `event.GAMEPAD_UPDATE`. The first button presses `FACE_1`, the second `FACE_2`, and so on. |
| 48 | + |
| 49 | +A game that reads the keyboard only can have the controls press keys instead: |
| 50 | + |
| 51 | +```ts |
| 52 | +plugin.register(GamepadPlugin, "gamepad", { |
| 53 | + sticks: [{ keys: { left: input.KEY.LEFT, right: input.KEY.RIGHT } }], |
| 54 | + buttons: [{ key: input.KEY.SPACE, label: "Jump" }], |
| 55 | +}); |
| 56 | +``` |
| 57 | + |
| 58 | +## Options |
| 59 | + |
| 60 | +| Option | Default | | |
| 61 | +| --- | --- | --- | |
| 62 | +| `enabled` | `device.touch` | show the controls; on phones and tablets only by default | |
| 63 | +| `index` | `0` | the gamepad slot they report in | |
| 64 | +| `sticks` | `1` | how many sticks (0 to 2), or a list of [stick options](#sticks) | |
| 65 | +| `buttons` | `1` | how many buttons, or a list of [button options](#buttons) | |
| 66 | +| `hideOnGamepad` | `true` | hide them while a real pad is in use | |
| 67 | +| `color` | `"#ffffff"` | their color | |
| 68 | +| `opacity` | `0.35` | how opaque they are at rest; a press doubles it | |
| 69 | +| `margin` | 6% of the shorter side | the space kept from the edges of the viewport | |
| 70 | +| `vibrate` | `true` | let `input.vibrateGamepad` vibrate the phone | |
| 71 | + |
| 72 | +Sizes and positions are in viewport pixels, the same units the game is drawn in. The controls keep their place when the viewport is resized or turned. |
| 73 | + |
| 74 | +### Sticks |
| 75 | + |
| 76 | +| Option | Default | | |
| 77 | +| --- | --- | --- | |
| 78 | +| `side` | `"left"`, then `"right"` | the left stick reports `LX`/`LY`, the right one `RX`/`RY` | |
| 79 | +| `position` | its bottom corner | `{ left or right, top or bottom }`: from the edges to its center | |
| 80 | +| `radius` | 13% of the shorter side | the radius of its base | |
| 81 | +| `floating` | `false` | centered where the thumb lands on its half of the screen | |
| 82 | +| `deadzone` | `0.1` | how far it must lean (0 to 1) before it reads anything | |
| 83 | +| `dpad` | on for the left stick | press the D-pad buttons in 8 directions, past half its travel | |
| 84 | +| `keys` | none | `{ up, down, left, right }`: keys to press as it leans | |
| 85 | + |
| 86 | +### Buttons |
| 87 | + |
| 88 | +| Option | Default | | |
| 89 | +| --- | --- | --- | |
| 90 | +| `button` | `FACE_1`, `FACE_2`… | the pad button it presses; `null` for none | |
| 91 | +| `key` | none | a key to press, instead of a pad button unless `button` is also given | |
| 92 | +| `label` | none | the text on it | |
| 93 | +| `position` | gathered in the bottom-right corner | from the edges to its center | |
| 94 | +| `radius` | 7.5% of the shorter side | its radius | |
| 95 | + |
| 96 | +With a second stick, the buttons gather above it. |
| 97 | + |
| 98 | +## At run time |
| 99 | + |
| 100 | +```ts |
| 101 | +const gamepad = plugin.cache.gamepad as GamepadPlugin; |
| 102 | + |
| 103 | +// a stage that only needs a tap |
| 104 | +gamepad.enabled = false; |
| 105 | + |
| 106 | +// light the use button only when there is something in reach |
| 107 | +gamepad.buttons[1].dimmed = !nearSomething; |
| 108 | +gamepad.buttons[1].label = "Open"; |
| 109 | +gamepad.buttons[1].visible = false; |
| 110 | + |
| 111 | +// word a prompt for the player's controls |
| 112 | +const prompt = gamepad.visible ? "Tap A to start" : "Press X to start"; |
| 113 | +``` |
| 114 | + |
| 115 | +- `enabled`: switches the controls on and off |
| 116 | +- `visible`: whether they are on the screen, which is `enabled` and not hidden for a real pad |
| 117 | +- `sticks[i]`: a stick's `value` (`x`, `y` from -1 to 1), `center` and `radius` |
| 118 | +- `buttons[i]`: a button's `pressed`, and its `label`, `dimmed` and `visible`, which can be set |
| 119 | +- `destroy()`: takes the controls off the screen and out of their slot for good |
| 120 | + |
| 121 | +## Hidden for a real pad |
| 122 | + |
| 123 | +With `hideOnGamepad` (on by default) the controls hide when a real pad is connected, and come back when it is unplugged or the screen is touched. Browsers only report a pad once one of its buttons is pressed, so in practice they hide as soon as the player picks up the pad. |
| 124 | + |
| 125 | +A real pad and the touch controls can share a slot: the engine reads both, and either one presses a button. |
| 126 | + |
| 127 | +## Troubleshooting |
| 128 | + |
| 129 | +| Symptom | Cause | |
| 130 | +| --- | --- | |
| 131 | +| The controls do not show | `enabled` is `device.touch` by default, false on a desktop: pass `enabled: true` to try them there. They also hide while a real pad is connected | |
| 132 | +| Touch controls do nothing | Nothing is bound to their slot: bind with `input.bindGamepad(index, ...)` on the plugin's `index` (0 by default), or use `key` options | |
| 133 | +| The stick moves but nothing walks | The game binds the stick's axes (`LX`) with a `threshold`, or the D-pad buttons; the left stick presses the D-pad, the right one does not by default | |
| 134 | +| `gamepad 0 already holds a virtual gamepad` | Two sets of controls in one slot: give the second one another `index` | |
| 135 | + |
| 136 | +## License |
| 137 | + |
| 138 | +MIT |
0 commit comments