me.input

Namespaces

GAMEPAD

KEY

Members

static pointer :me.Rect

Pointer information (current position and size)
properties :
LEFT : constant for left button
MIDDLE : constant for middle button
RIGHT : constant for right button

static preventDefault :Boolean

Global flag to specify if melonJS should prevent all default browser action on registered events. default : true

static throttlingInterval :Number

time interval for event throttling in milliseconds
default value : "1000/me.sys.fps" ms
set to 0 ms to disable the feature

Methods

static bindGamepad(index, button, keyCode)

Associate a gamepad event to a keycode

Parameters:
Name Type Description
index Number

Gamepad index

button Object

Button/Axis definition

Properties
Name Type Attributes Default Description
type String

"buttons" or "axes"

code me.input.GAMEPAD.BUTTONS | me.input.GAMEPAD.AXES

button or axis code id

threshold Number <optional>
1

value indicating when the axis should trigger the keycode (e.g. -0.5 or 0.5)

keyCode me.input.KEY
Example
// enable the keyboard
me.input.bindKey(me.input.KEY.X, "shoot");
...
// map the lower face button on the first gamepad to the X key
me.input.bindGamepad(0, {type:"buttons", code: me.input.GAMEPAD.BUTTONS.FACE_1}, me.input.KEY.X);
// map the left axis value on the first gamepad to the LEFT key
me.input.bindGamepad(0, {type:"axes", code: me.input.GAMEPAD.AXES.LX, threshold: -0.5}, me.input.KEY.LEFT);

static bindKey(keycode, action, lockopt, preventDefaultopt)

associate a user defined action to a keycode

Parameters:
Name Type Attributes Default Description
keycode me.input.KEY
action String

user defined corresponding action

lock Boolean <optional>
false

cancel the keypress event once read

preventDefault Boolean <optional>
me.input.preventDefault

prevent default browser action

Example
// enable the keyboard
me.input.bindKey(me.input.KEY.LEFT,  "left");
me.input.bindKey(me.input.KEY.RIGHT, "right");
me.input.bindKey(me.input.KEY.X,     "jump", true);
me.input.bindKey(me.input.KEY.F1,    "options", true, true);

static bindPointer(buttonopt, keyCode)

Associate a pointer event to a keycode
Left button – 0 Middle button – 1 Right button – 2

Parameters:
Name Type Attributes Default Description
button Number <optional>
me.input.pointer.LEFT

(accordingly to W3C values : 0,1,2 for left, middle and right buttons)

keyCode me.input.KEY
Example
// enable the keyboard
me.input.bindKey(me.input.KEY.X, "shoot");
// map the left button click on the X key (default if the button is not specified)
me.input.bindPointer(me.input.KEY.X);
// map the right button click on the X key
me.input.bindPointer(me.input.pointer.RIGHT, me.input.KEY.X);

static globalToLocal(x, y, vopt) → {me.Vector2d}

Translate the specified x and y values from the global (absolute) coordinate to local (viewport) relative coordinate.

Parameters:
Name Type Attributes Description
x Number

the global x coordinate to be translated.

y Number

the global y coordinate to be translated.

v Number <optional>

an optional vector object where to set the

Returns:
me.Vector2d -

A vector object with the corresponding translated coordinates.

Example
onMouseEvent : function (pointer) {
   // convert the given into local (viewport) relative coordinates
   var pos = me.input.globalToLocal(pointer.clientX, pointer.clientY);
   // do something with pos !
};

static isKeyPressed(action) → {Boolean}

return the key press status of the specified action

Parameters:
Name Type Description
action String

user defined corresponding action

Returns:
Boolean -

true if pressed

Example
if (me.input.isKeyPressed('left'))
{
   //do something
}
else if (me.input.isKeyPressed('right'))
{
   //do something else...
}

static keyStatus(action) → {Boolean}

return the key status of the specified action

Parameters:
Name Type Description
action String

user defined corresponding action

Returns:
Boolean -

down (true) or up(false)

static registerPointerEvent(eventType, region, callback)

allows registration of event listeners on the object target.
melonJS will pass a me.Pointer object to the defined callback.

Parameters:
Name Type Description
eventType String

The event type for which the object is registering
melonJS currently supports:

  • "pointermove"
  • "pointerdown"
  • "pointerup"
  • "pointerenter"
  • "pointerover"
  • "pointerleave"
  • "pointercancel"
  • "wheel"
region me.Rect | me.Polygon | me.Line | me.Ellipse

a shape representing the region to register on

callback function

methods to be called when the event occurs. Returning false from the defined callback will prevent the event to be propagated to other objects

See:
Example
// onActivate function
 onActivateEvent: function () {
    // register on the 'pointerdown' event
    me.input.registerPointerEvent('pointerdown', this, this.pointerDown.bind(this));
 },

 // pointerDown event callback
 pointerDown: function (pointer) {
   // do something
   ....
   // don"t propagate the event to other objects
   return false;
 },

static releasePointerEvent(eventType, region, callbackopt)

allows the removal of event listeners from the object target.

Parameters:
Name Type Attributes Default Description
eventType String

The event type for which the object was registered. See me.input.registerPointerEvent

region me.Rect | me.Polygon | me.Line | me.Ellipse

the registered region to release for this event

callback function <optional>
"all"

if specified unregister the event only for the specific callback

See:
Example
// release the registered region on the 'pointerdown' event
me.input.releasePointerEvent('pointerdown', this);

static setGamepadDeadzone(value)

Set deadzone for analog gamepad inputs
The default deadzone is 0.1 (10%) Analog values less than this will be ignored

Parameters:
Name Type Description
value Number

Deadzone value

static setGamepadMapping(id, mapping)

specify a custom mapping for a specific gamepad id
see below for the default mapping :


Parameters:
Name Type Description
id String

Gamepad id string

mapping Object

A hash table

Properties
Name Type Attributes Description
axes Array.<Number>

Standard analog control stick axis locations

buttons Array.<Number>

Standard digital button locations

analog Array.<Number> <optional>

Analog axis locations for buttons

normalize_fn me.input~normalize_fn <optional>

Axis normalization function

Example
// A weird controller that has its axis mappings reversed
me.input.setGamepadMapping("Generic USB Controller", {
  "axes" : [ 3, 2, 1, 0 ],
  "buttons" : [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ]
});

// Mapping extra axes to analog buttons
me.input.setGamepadMapping("Generic Analog Controller", {
  "axes" : [ 0, 1, 2, 3 ],
  "buttons" : [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ],

  // Raw axis 4 is mapped to GAMEPAD.BUTTONS.FACE_1
  // Raw axis 5 is mapped to GAMEPAD.BUTTONS.FACE_2
  // etc...
  // Also maps left and right triggers
  "analog" : [ 4, 5, 6, 7, -1, -1, 8, 9, -1, -1, -1, -1, -1, -1, -1, -1, -1 ],

  // Normalize the value of button L2: [-1.0..1.0] => [0.0..1.0]
  "normalize_fn" : function (value, axis, button) {
    return ((button === me.input.GAMEPAD.BUTTONS.L2) ? ((value + 1) / 2) : value) || 0;
  }
});

static setTouchAction(element, valueopt)

enable/disable all gestures on the given element.
by default melonJS will disable browser handling of all panning and zooming gestures.

Parameters:
Name Type Attributes Default Description
element HTMLCanvasElement
value String <optional>
"none"
See:

static triggerKeyEvent(keycode, statusopt)

trigger the specified key (simulated) event

Parameters:
Name Type Attributes Default Description
keycode me.input.KEY
status Boolean <optional>
false

true to trigger a key press, or false for key release

Example
// trigger a key press
me.input.triggerKeyEvent(me.input.KEY.LEFT, true);

static unbindGamepad(index, button)

unbind the defined keycode

Parameters:
Name Type Description
index Number

Gamepad index

button me.input.GAMEPAD.BUTTONS
Example
me.input.unbindGamepad(0, me.input.GAMEPAD.BUTTONS.FACE_1);

static unbindKey(keycode)

unbind the defined keycode

Parameters:
Name Type Description
keycode me.input.KEY
Example
me.input.unbindKey(me.input.KEY.LEFT);

static unbindPointer(buttonopt)

unbind the defined keycode

Parameters:
Name Type Attributes Default Description
button Number <optional>
me.input.pointer.LEFT

(accordingly to W3C values : 0,1,2 for left, middle and right buttons)

Example
me.input.unbindPointer(me.input.pointer.LEFT);

static unlockKey(action)

unlock a key manually

Parameters:
Name Type Description
action String

user defined corresponding action

Example
// Unlock jump when touching the ground
if (!this.falling && !this.jumping) {
    me.input.unlockKey("jump");
}

Type Definitions

normalize_fn(value, axis, button)

A function that returns a normalized value in range [-1.0..1.0], or 0.0 if the axis is unknown.

Parameters:
Name Type Description
value Number

The raw value read from the gamepad driver

axis Number

The axis index from the standard mapping, or -1 if not an axis

button Number

The button index from the standard mapping, or -1 if not a button