Skip to content

Commit e79c9b3

Browse files
committed
gamepad-plugin: on-screen touch controls, reported as a gamepad (#1719)
A new package, @melonjs/gamepad-plugin, built from the plugin template and following the in-repo plugins. It draws sticks and buttons and puts a virtual pad in a gamepad slot (input.addVirtualGamepad), so a game's bindGamepad bindings answer to the touch controls as to a real pad. - one or two analog sticks with a deadzone; the left one presses the D-pad in 8 directions. Fixed or floating (centered where the thumb lands). Keys can be pressed instead, for keyboard-only games - any number of buttons, FACE_1, FACE_2... by default or a key; a game can relabel, dim or hide them at run time - each finger followed by its own pointer id from DOM pointer events, caught in the capture phase on the canvas's parent: a touch starting on the controls never reaches the engine or the game, and a stick keeps its finger when the thumb drifts off its base - drawn after the stage, over every camera and every renderable, whatever their z, and so never inside a minimap; nothing to load, only the renderer's shapes; kept across stage changes - `enabled` (device.touch by default) and `visible`; hidden while a real pad is in use (hideOnGamepad), back when it is unplugged or the screen is touched - input.vibrateGamepad vibrates the phone through navigator.vibrate - the minimum engine version comes from peerDependencies (>= 20.12.0, the release with addVirtualGamepad) 33 browser tests on the Canvas renderer, including that touches are kept from the game and the controls are drawn over a full-screen overlay; checked by hand on WebGL. Also: README, CHANGELOG, the API docs entry, the melonjs-input skill (with symptom entries), CI test and publish wiring, and the root README plugin list. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01JnzwA4xBNBw7cEZzG1bUru
1 parent 979f34f commit e79c9b3

22 files changed

Lines changed: 2246 additions & 2 deletions

File tree

‎.github/workflows/main.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ jobs:
104104
- run: pnpm -F @melonjs/matter-adapter test
105105
- run: pnpm -F @melonjs/planck-adapter test
106106
- run: pnpm -F @melonjs/debug-plugin test
107+
- run: pnpm -F @melonjs/gamepad-plugin test
107108

108109
# Windows build — only on master push, not on PRs
109110
windows:

‎.github/workflows/publish.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ on:
1515
- matter-adapter
1616
- planck-adapter
1717
- capacitor-plugin
18+
- gamepad-plugin
1819
- create-melonjs
1920
dry-run:
2021
description: "Dry run (skip actual publish)"
@@ -74,6 +75,9 @@ jobs:
7475
elif [ "${{ inputs.package }}" = "capacitor-plugin" ]; then
7576
echo "dir=packages/capacitor-plugin" >> "$GITHUB_OUTPUT"
7677
echo "build_cmd=pnpm clean && pnpm build" >> "$GITHUB_OUTPUT"
78+
elif [ "${{ inputs.package }}" = "gamepad-plugin" ]; then
79+
echo "dir=packages/gamepad-plugin" >> "$GITHUB_OUTPUT"
80+
echo "build_cmd=pnpm clean && pnpm build" >> "$GITHUB_OUTPUT"
7781
elif [ "${{ inputs.package }}" = "create-melonjs" ]; then
7882
echo "dir=packages/create-melonjs" >> "$GITHUB_OUTPUT"
7983
echo "build_cmd=echo 'No build step needed'" >> "$GITHUB_OUTPUT"

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,7 @@ Here is the list of official plugins maintained by the melonJS team:
248248
- [debug-plugin](https://github.com/melonjs/melonJS/tree/master/packages/debug-plugin) - a debug panel for inspecting game objects
249249
- [tiled-inflate-plugin](https://github.com/melonjs/melonJS/tree/master/packages/tiled-inflate-plugin) - enable loading and parsing of zlib, gzip and zstd compressed [Tiled](https://www.mapeditor.org/) maps
250250
- [spine-plugin](https://github.com/melonjs/melonJS/tree/master/packages/spine-plugin) - [Spine](http://esotericsoftware.com) runtime integration to render Spine skeletal animations, with a dedicated batcher on each renderer (WebGPU, WebGL and Canvas)
251+
- [gamepad-plugin](https://github.com/melonjs/melonJS/tree/master/packages/gamepad-plugin) - on-screen touch controls (sticks and buttons) reported as a gamepad, so the same bindings cover a real pad and a touch screen
251252
- [capacitor-plugin](https://github.com/melonjs/melonJS/tree/master/packages/capacitor-plugin) - bridges [Capacitor](https://capacitorjs.com/)'s native lifecycle (pause/resume, hardware back-button, orientation lock, splash) for melonJS games wrapped as iOS / Android apps
252253

253254
If you wish to develop your own plugin, we also provide a [plugin template](https://github.com/melonjs/plugin-template) to help you get started.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Changelog
2+
3+
## [1.0.0] - _unreleased_
4+
5+
### Added
6+
- Initial release ([#1719](https://github.com/melonjs/melonJS/issues/1719)). `GamepadPlugin` draws on-screen sticks and buttons and reports them as a gamepad in a gamepad slot, through melonJS's `input.addVirtualGamepad`, so a game's `input.bindGamepad` bindings answer to them as to a real pad. One or two analog sticks with a deadzone, pressing the D-pad in 8 directions; any number of buttons pressing a pad button or a key, which a game can relabel, dim or hide; each finger followed on its own; touches on the controls kept from the game; drawn over the whole frame and across stages; hidden while a real pad is in use; phone vibration through `input.vibrateGamepad`

‎packages/gamepad-plugin/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (C) 2011 - 2026 Olivier Biot (AltByte Pte Ltd)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎packages/gamepad-plugin/README.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
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
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
{
2+
"name": "@melonjs/gamepad-plugin",
3+
"version": "1.0.0",
4+
"description": "melonJS virtual gamepad plugin",
5+
"homepage": "https://www.npmjs.com/package/@melonjs/gamepad-plugin",
6+
"type": "module",
7+
"keywords": [
8+
"2D",
9+
"HTML5",
10+
"javascript",
11+
"TypeScript",
12+
"ES6",
13+
"Canvas",
14+
"WebGL",
15+
"WebGPU",
16+
"melonjs",
17+
"plugin",
18+
"gamepad",
19+
"joystick",
20+
"touch",
21+
"mobile",
22+
"controls"
23+
],
24+
"repository": {
25+
"type": "git",
26+
"url": "git+https://github.com/melonjs/melonJS.git",
27+
"directory": "packages/gamepad-plugin"
28+
},
29+
"bugs": {
30+
"url": "https://github.com/melonjs/melonJS/issues"
31+
},
32+
"license": "MIT",
33+
"author": "AltByte Pte Ltd",
34+
"funding": "https://github.com/sponsors/melonjs",
35+
"engines": {
36+
"node": ">=24.0.0"
37+
},
38+
"exports": {
39+
".": "./build/index.js"
40+
},
41+
"types": "./build/index.d.ts",
42+
"sideEffects": false,
43+
"files": [
44+
"build/",
45+
"package.json",
46+
"README.md",
47+
"LICENSE",
48+
"CHANGELOG.md"
49+
],
50+
"peerDependencies": {
51+
"melonjs": ">=20.12.0"
52+
},
53+
"devDependencies": {
54+
"@types/node": "^25.6.0",
55+
"concurrently": "^9.2.1",
56+
"esbuild": "^0.28.0",
57+
"melonjs": "workspace:*",
58+
"tsconfig": "workspace:*",
59+
"tsx": "^4.23.1",
60+
"typescript": "^6.0.2",
61+
"vitest": "^4.1.11"
62+
},
63+
"scripts": {
64+
"dev": "concurrently --raw \"pnpm build:watch\" \"pnpm tsc:watch\"",
65+
"build": "tsx scripts/build.ts && pnpm types",
66+
"build:watch": "tsx scripts/build.ts watch",
67+
"prepublishOnly": "pnpm clean && pnpm build",
68+
"clean": "tsx scripts/clean.ts",
69+
"types": "tsc --project tsconfig.build.json",
70+
"tsc:watch": "tsc --project tsconfig.build.json --watch --noUnusedParameters false --noUnusedLocals false --preserveWatchOutput",
71+
"test": "vitest run",
72+
"test:types": "tsc",
73+
"lint": "eslint src tests"
74+
}
75+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import esbuild, { type BuildOptions } from "esbuild";
2+
import packageJson from "../package.json" with { type: "json" };
3+
4+
const banner = [
5+
"/*!",
6+
` * ${packageJson.description} - ${packageJson.version}`,
7+
" * http://www.melonjs.org",
8+
` * ${packageJson.name} is licensed under the MIT License.`,
9+
" * http://www.opensource.org/licenses/mit-license",
10+
` * @copyright (C) 2011 - ${new Date().getFullYear()} ${packageJson.author}`,
11+
" */",
12+
].join("\n");
13+
14+
const buildOptions = {
15+
entryPoints: ["src/index.ts"],
16+
external: ["melonjs"],
17+
format: "esm",
18+
outdir: "build",
19+
sourcemap: true,
20+
bundle: true,
21+
banner: {
22+
js: banner,
23+
},
24+
} satisfies BuildOptions;
25+
26+
if (process.argv[2] === "watch") {
27+
const ctx = await esbuild.context(buildOptions);
28+
await ctx.watch({});
29+
} else {
30+
await esbuild.build(buildOptions);
31+
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
import { rm } from "node:fs/promises";
2+
3+
await rm("build", { recursive: true, force: true });

0 commit comments

Comments
 (0)