input

namespace input

Public Properties


keyBoardEventTarget keyboard.js:98
keyBoardEventTarget: EventTarget = undefined

EventTarget

the default target element for keyboard events (usually the window element in which the game is running)

locked pointerevent.js:504
locked: boolean = false

boolean

indicates if the pointer is currently locked

pointer pointerevent.js:494
pointer: Rect

Rect

Pointer information (current position and size)

pointerEventTarget pointerevent.js:485
pointerEventTarget: EventTarget = undefined

EventTarget

the default target element for pointer events (usually the canvas element in which the game is rendered)

preventDefault input.js:5
preventDefault: boolean = true

boolean

specify if melonJS should prevent all default browser action on registered events.

setGamepadMapping gamepad.js:450
setGamepadMapping

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


 // 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;
   }
 });
Parameters:
Name Type Attributes Description
id string

Gamepad id string

mapping object

A hash table

mapping.axes Array<number>

Standard analog control stick axis locations

mapping.buttons Array<number>

Standard digital button locations

mapping.analog Array<number>

<optional>

Analog axis locations for buttons

mapping.normalize_fn Function

<optional>

a function that returns a normalized value in range [-1.0..1.0] for the given value, axis and button

throttlingInterval pointerevent.js:513
throttlingInterval: number

number

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

Public Methods


bindGamepad gamepad.js:347
bindGamepad(index: number, button: object, keyCode: number) → {}

Associate a gamepad event to a keycode

// 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);
Parameters:
Name Type Attributes Default Description
index number

Gamepad index

button object

Button/Axis definition

button.type string

"buttons" or "axes"

button.code number

button or axis code id (See input.GAMEPAD.BUTTONS, input.GAMEPAD.AXES)

button.threshold number

<optional>

1

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

keyCode number

(See input.KEY)

bindKey keyboard.js:389
bindKey(keycode: number, action: string, lock: boolean, preventDefault: boolean) → {}

associate a user defined action to a keycode

// 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);
Parameters:
Name Type Attributes Default Description
keycode number

(See input.KEY)

action string

user defined corresponding action

lock boolean

<optional>

false

cancel the keypress event once read

preventDefault boolean

<optional>

input.preventDefault

prevent default browser action

bindPointer pointerevent.js:584
bindPointer(button: number, keyCode: input.KEY) → {}

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

// 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);
Parameters:
Name Type Attributes Default Description
button number

<optional>

input.pointer.LEFT

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

keyCode input.KEY
exitPointerLock pointerevent.js:783
exitPointerLock() → {boolean}

Initiates an exit from pointer lock state

Returns:
Type Description
boolean

return true if the request was successfully submitted

getBindingKey keyboard.js:415
getBindingKey(keycode: number) → {string}

return the action associated with the given keycode

Parameters:
Name Type Description
keycode number

(See input.KEY)

Returns:
Type Description
string

user defined associated action

globalToLocal pointerevent.js:543
globalToLocal(x: number, y: number, v: Vector2d) → {Vector2d}

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

onMouseEvent : function (pointer) {
   // convert the given into local (viewport) relative coordinates
   let pos = me.input.globalToLocal(pointer.clientX, pointer.clientY);
   // do something with pos !
};
Parameters:
Name Type Attributes Description
x number

the global x coordinate to be translated.

y number

the global y coordinate to be translated.

v Vector2d

<optional>

an optional vector object where to set the translated coordinates

Returns:
Type Description
Vector2d

A vector object with the corresponding translated coordinates

hasActiveEvents pointerevent.js:524
hasActiveEvents() → {}

return true if there are pending pointer events in the queue

Returns:
Type Description

true if there are pending events

hasRegisteredEvents pointerevent.js:533
hasRegisteredEvents() → {}

return true if there are register pointer events

Returns:
Type Description

true if there are pending events

See: registerPointerEvent
isKeyPressed keyboard.js:329
isKeyPressed(action: string) → {boolean}

return the key press status of the specified action

if (me.input.isKeyPressed('left')) {
   //do something
}
else if (me.input.isKeyPressed('right')) {
   //do something else...
}
Parameters:
Name Type Description
action string

user defined corresponding action

Returns:
Type Description
boolean

true if pressed

keyStatus keyboard.js:354
keyStatus(action: string) → {boolean}

return the key status of the specified action

Parameters:
Name Type Description
action string

user defined corresponding action

Returns:
Type Description
boolean

down (true) or up(false)

registerPointerEvent pointerevent.js:631
registerPointerEvent(eventType: string, region: Rect | Polygon | Line | Ellipse, callback: Function) → {}

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

  // onActivate function
  onActivateEvent: function () {
     // register on the 'pointerdown' event
     me.input.registerPointerEvent('pointerdown', this, (e) => this.pointerDown(e));
  },

  // pointerDown event callback
  pointerDown: function (pointer) {
    // do something
    ....
    // don"t propagate the event to other objects
    return false;
  },
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 Rect | Polygon | Line | 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:
releaseAllPointerEvents pointerevent.js:745
releaseAllPointerEvents(region: Rect | Polygon | Line | Ellipse) → {}

allows the removal of all registered event listeners from the object target.

// release all registered event on the
me.input.releaseAllPointerEvents(this);
Parameters:
Name Type Description
region Rect | Polygon | Line | Ellipse

the registered region to release event from

releasePointerEvent pointerevent.js:702
releasePointerEvent(eventType: string, region: Rect | Polygon | Line | Ellipse, callback: Function) → {}

allows the removal of event listeners from the object target.

// release the registered region on the 'pointerdown' event
me.input.releasePointerEvent('pointerdown', this);
Parameters:
Name Type Attributes Default Description
eventType string

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

region Rect | Polygon | Line | Ellipse

the registered region to release for this event

callback Function

<optional>

"all"

if specified unregister the event only for the specific callback

See: W3C Pointer Event list
requestPointerLock pointerevent.js:761
requestPointerLock() → {boolean}

request for the pointer to be locked on the parent DOM element. (Must be called in a click event or an event that requires user interaction)

// register on the pointer lock change event
event.on(event.POINTERLOCKCHANGE, (locked)=> {
    console.log("pointer lock: " + locked);
});
// request for pointer lock
me.input.requestPointerLock();
Returns:
Type Description
boolean

return true if the request was successfully submitted

setGamepadDeadzone gamepad.js:438
setGamepadDeadzone(value: number) → {}

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

setTouchAction pointerevent.js:572
setTouchAction(element: HTMLCanvasElement, value: string) → {}

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: https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action
triggerKeyEvent keyboard.js:367
triggerKeyEvent(keycode: number, status: boolean, mouseButton: number) → {}

trigger the specified key (simulated) event

// trigger a key press
me.input.triggerKeyEvent(me.input.KEY.LEFT, true);
Parameters:
Name Type Attributes Default Description
keycode number

(See input.KEY)

status boolean

<optional>

false

true to trigger a key down event, or false for key up event

mouseButton number

<optional>

the mouse button to trigger

unbindGamepad gamepad.js:421
unbindGamepad(index: number, button: number) → {}

unbind the defined keycode

me.input.unbindGamepad(0, me.input.GAMEPAD.BUTTONS.FACE_1);
Parameters:
Name Type Description
index number

Gamepad index

button number

(See input.GAMEPAD.BUTTONS)

unbindKey keyboard.js:443
unbindKey(keycode: number) → {}

unbind the defined keycode

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

(See input.KEY)

unbindPointer pointerevent.js:615
unbindPointer(button: number) → {}

unbind the defined keycode

me.input.unbindPointer(me.input.pointer.LEFT);
Parameters:
Name Type Attributes Default Description
button number

<optional>

input.pointer.LEFT

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

unlockKey keyboard.js:427
unlockKey(action: string) → {}

unlock a key manually

// Unlock jump when touching the ground
if (!this.falling && !this.jumping) {
    me.input.unlockKey("jump");
}
Parameters:
Name Type Description
action string

user defined corresponding action


Powered by webdoc!