Mouse, keyboard and touch control pitfalls
Mouse, keyboard and touch control pitfalls
Input is where web games most often break. These are the failures reviewers see most.
Page scrolling#
Arrow keys, space and the mouse wheel scroll the page that hosts your game unless you cancel them. Prevent the default for those events (outside text fields). See the snippet in technical requirements.
Focus#
Keys only reach your game if the game's frame has focus. After an ad, a dialog or a click on the portal's UI, focus may have moved.
window.addEventListener("focus", resume);
canvas.tabIndex = 0;
canvas.focus();
// after an ad:
canvas.focus();Also clear held keys on blur so a character does not keep walking:
window.addEventListener("blur", () => keys.clear());Key codes#
Use event.code (physical key) for movement, so WASD works on non-QWERTY layouts, and event.key for text. Offer rebinding if you can.
Mouse#
- Right-click shows the browser menu. Call
preventDefaultoncontextmenuif you use it. - Use pointer events (
pointerdown,pointermove,pointerup) instead of separate mouse and touch handlers, and callsetPointerCapturefor drags. - Pointer lock needs a user gesture and the sandbox allows it. Handle the player pressing Escape: pointer lock exits and your game should pause.
- Do not rely on
mouseleave; the cursor can leave the iframe while a button is held.
Touch#
- Do not detect mobile by
"ontouchstart" in window. Laptops report touch. UseSDK.user.systemInfo.device.type. - Set
touch-action: noneon the canvas to stop the browser panning or zooming. - Provide touch targets of at least 44 px, away from screen edges where the OS has gestures.
- Support multi-touch deliberately: track touches by
identifier. - Do not require hover.
- On iOS, resume audio inside a gesture handler.
Text input#
Use a real <input> for text and the on-screen keyboard. Canvas-drawn fields do not bring up the keyboard on mobile. When the keyboard opens the visual viewport shrinks; make sure the field stays visible.
Gamepads#
If you support gamepads, use the Gamepad API and show the right prompts. The portal frame allows gamepad access.
Fullscreen and orientation#
The portal supplies a fullscreen button and a rotate prompt. Do not add your own fullscreen toggle or lock orientation in code.
Test checklist#
- Hold a key, click elsewhere, return: nothing is stuck.
- Wheel and arrows never scroll the page.
- Right-click never opens the browser menu in-game.
- On a phone: no accidental zoom, no text selection, no pull-to-refresh.
- After an ad, input works without clicking first.