Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

melonjs-input

Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, which of several overlapping objects receives an event and how to consume it, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, pointermove, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, virtual gamepad, touch controls, joystick, gamepad-plugin, floating stick, floating button, floating joystick, two thumbs, tap to fire, hideAtRest, mobile controls, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click.

melonjs · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add melonjs/melonJS --skill melonjs-input

About this skill


name: melonjs-input description: "Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, which of several overlapping objects receives an event and how to consume it, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, pointermove, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, virtual gamepad, touch controls, joystick, gamepad-plugin, floating stick, floating button, floating joystick, two thumbs, tap to fire, hideAtRest, mobile controls, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click." license: MIT

Input: keyboard, pointer and gamepad

Keyboard goes through named actions

Do not poll key codes. Bind a key to an action string, then poll the action — this is what lets gamepad and virtual controls map onto the same handling.

import { input } from "melonjs";

input.bindKey(input.KEY.LEFT,  "left");
input.bindKey(input.KEY.RIGHT, "right");
input.bindKey(input.KEY.X,     "jump", true);   // true = locked: one press per keydown

// in update()
if (input.isKeyPressed("left"))  { /* … */ }
if (input.isKeyPressed("jump"))  { /* fires once per press, not per frame */ }

The third argument to bindKey is lock (default false). Without it, isKeyPressed stays true for as long as the key is held — correct for movement, wrong for jump or fire. A locked action stays consumed until the key is released or you call input.unlockKey("jump"). Use input.keyStatus(action) when you want the raw held/not-held state regardless of locking.

A poll can miss a press entirely

isKeyPressed is sampled once per frame, and keyup decrements the key's counter the moment it arrives — locked or not. A press that goes down and up between two frames therefore leaves the counter back at zero and is never seen. At 60fps that is anything under ~16ms: rare from a human finger, routine from a synthetic event, and more likely the slower the frame rate.

For a screen where a missed press is a dead end — a splash, a "press any key", a notice to acknowledge — listen for the event instead, which cannot be missed:

import { event } from "melonjs";

// action is the bound action name, or undefined for an unbound key
const onKey = (action) => { if (action === "menuSelect") continue(); };
event.on(event.KEYDOWN, onKey);      // in onResetEvent
event.off(event.KEYDOWN, onKey);     // in onDestroyEvent — it does not self-remove

KEYDOWN fires for every key, bound or not, so matching on action is what narrows it; it also repeats while the key is held, so guard anything that must happen once. Keep polling for movement and for a menu cursor, where one step per press and a key held across a state change are the things that matter.

The full signature is bindKey(keyCode, action, lock?, preventDefault?); preventDefault defaults to input.preventDefault (itself true). Pass the fourth argument per binding, or change the global default with input.setPreventDefault(false) — assigning input.preventDefault = false does not work, it is a read-only module binding.

Pointer events need isKinematic = false

This is the trap. Renderable.isKinematic defaults to true, and both the broadphase and the pointer dispatcher skip any candidate whose isKinematic is still true. The handler registers successfully and simply never fires.

class Button extends Renderable {
    constructor(x, y, w, h) {
        super(x, y, w, h);
        this.isKinematic = false;               // ← required
    }
    onActivateEvent() {
        input.registerPointerEvent("pointerdown", this, this.onDown.bind(this));
    }
    onDeactivateEvent() {
        input.releasePointerEvent("pointerdown", this);
    }
}

Container, Camera2d, Draggable, DropTarget and the UI* elements set it to false for you, and so does attaching a physics body (Body's constructor sets ancestor.isKinematic = false) — so plain Renderable and Sprite subclasses with no body are the ones that catch people.

Register in onActivateEvent and release in onDeactivateEvent, not in the constructor — pooled objects are reused and would otherwise accumulate handlers.

app.viewport works as a whole-screen region when you want global clicks. Note it is asked before everything else, not as a fallback after nothing matched: the dispatcher appends it to the candidate list and walks that list from the end. So a viewport handler must not return false unless it really means to swallow every pointer event in the game.

The accepted event names are exactly "pointerdown", "pointerup", "pointermove", "pointercancel", "pointerenter", "pointerover", "pointerleave" and "wheel". Anything else — "click", "mousedown", "touchstart" — makes both registerPointerEvent and releasePointerEvent throw invalid event type. melonJS maps the canonical name onto whichever mouse/touch events the device actually supports, so you always register the pointer name.

Which object gets the event

The dispatcher collects the regions near the pointer from the broadphase, bounds-checks each one, orders them the way they are drawn and asks the topmost first, walking down until something consumes.

A handler consumes by returning false. This is the DOM sense and it reads backwards: false means handled, and anything else, undefined included, lets the walk carry on to whatever is underneath.

input.registerPointerEvent("pointerdown", this, () => {
    this.fire();
    return false;        // nothing under this gets the click
});

Three things decide the order, and only the first

Read the complete source ↗