melonjs 10.2.0 → 10.3.0

package/src/input/pointer.js

@@ -3,6 +3,7 @@ import device from "./../system/device.js";
 import Bounds from "./../physics/bounds.js";
 import { viewport } from "./../game.js";
 import { globalToLocal } from "./input.js";
+import { locked } from "./pointerevent.js";
 
 
 /**
@@ -14,10 +15,9 @@ var tmpVec = new Vector2d();
 /**
  * @classdesc
  * a pointer object, representing a single finger on a touch enabled device.
- * @class
- * @extends me.Bounds
- * @memberOf me
- * @constructor
+ * @class Pointer
+ * @augments me.Bounds
+ * @memberof me
  */
 class Pointer extends Bounds {
 
@@ -35,27 +35,27 @@ class Pointer extends Bounds {
         /**
          * constant for left button
          * @public
-         * @type {Number}
+         * @type {number}
          * @name LEFT
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.LEFT = 0;
 
         /**
          * constant for middle button
          * @public
-         * @type {Number}
+         * @type {number}
          * @name MIDDLE
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.MIDDLE = 1;
 
         /**
          * constant for right button
          * @public
-         * @type {Number}
+         * @type {number}
          * @name RIGHT
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.RIGHT = 2;
 
@@ -67,17 +67,17 @@ class Pointer extends Bounds {
          * @see https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent
          * @see https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent
          * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.event = undefined;
 
         /**
          * a string containing the event's type.
          * @public
-         * @type {String}
+         * @type {string}
          * @name type
          * @see https://developer.mozilla.org/en-US/docs/Web/API/Event/type
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.type = undefined;
 
@@ -85,100 +85,120 @@ class Pointer extends Bounds {
         /**
          * the button property indicates which button was pressed on the mouse to trigger the event.
          * @public
-         * @type {Number}
+         * @type {number}
          * @name button
          * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.button = 0;
 
         /**
          * indicates whether or not the pointer device that created the event is the primary pointer.
          * @public
-         * @type {Boolean}
+         * @type {boolean}
          * @name isPrimary
          * @see https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/isPrimary
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.isPrimary = false;
 
         /**
          * the horizontal coordinate at which the event occurred, relative to the left edge of the entire document.
          * @public
-         * @type {Number}
+         * @type {number}
          * @name pageX
          * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/pageX
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.pageX = 0;
 
         /**
          * the vertical coordinate at which the event occurred, relative to the left edge of the entire document.
          * @public
-         * @type {Number}
+         * @type {number}
          * @name pageY
          * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/pageY
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.pageY = 0;
 
         /**
          * the horizontal coordinate within the application's client area at which the event occurred
          * @public
-         * @type {Number}
+         * @type {number}
          * @name clientX
          * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/clientX
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.clientX = 0;
 
        /**
         * the vertical coordinate within the application's client area at which the event occurred
         * @public
-        * @type {Number}
+        * @type {number}
         * @name clientY
         * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/clientY
-        * @memberOf me.Pointer
+        * @memberof me.Pointer
         */
         this.clientY = 0;
 
+        /**
+         * the difference in the X coordinate of the pointer since the previous move event
+         * @public
+         * @type {number}
+         * @name movementX
+         * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/movementX
+         * @memberof me.Pointer
+         */
+        this.movementX = 0;
+
+       /**
+        * the difference in the Y coordinate of the pointer since the previous move event
+        * @public
+        * @type {number}
+        * @name movementY
+        * @see https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/movementY
+        * @memberof me.Pointer
+        */
+        this.movementY = 0;
+
         /**
          * an unsigned long representing the unit of the delta values scroll amount
          * @public
-         * @type {Number}
+         * @type {number}
          * @name deltaMode
          * @see https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/deltaMode
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.deltaMode = 0;
 
         /**
          * a double representing the horizontal scroll amount in the Wheel Event deltaMode unit.
          * @public
-         * @type {Number}
+         * @type {number}
          * @name deltaX
          * @see https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/deltaX
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.deltaX = 0;
 
         /**
          * a double representing the vertical scroll amount in the Wheel Event deltaMode unit.
          * @public
-         * @type {Number}
+         * @type {number}
          * @name deltaY
          * @see https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/deltaY
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.deltaY = 0;
 
         /**
          * a double representing the scroll amount in the z-axis, in the Wheel Event deltaMode unit.
          * @public
-         * @type {Number}
+         * @type {number}
          * @name deltaZ
          * @see https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/deltaZ
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.deltaZ = 0;
 
@@ -186,9 +206,9 @@ class Pointer extends Bounds {
          * Event normalized X coordinate within the game canvas itself<br>
          * <img src="images/event_coord.png"/>
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameX
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameX = 0;
 
@@ -196,75 +216,93 @@ class Pointer extends Bounds {
          * Event normalized Y coordinate within the game canvas itself<br>
          * <img src="images/event_coord.png"/>
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameY
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameY = 0;
 
         /**
          * Event X coordinate relative to the viewport
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameScreenX
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameScreenX = 0;
 
         /**
          * Event Y coordinate relative to the viewport
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameScreenY
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameScreenY = 0;
 
         /**
          * Event X coordinate relative to the map
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameWorldX
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameWorldX = 0;
 
         /**
          * Event Y coordinate relative to the map
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameWorldY
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameWorldY = 0;
 
         /**
          * Event X coordinate relative to the holding container
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameLocalX
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameLocalX = 0;
 
         /**
          * Event Y coordinate relative to the holding container
          * @public
-         * @type {Number}
+         * @type {number}
          * @name gameLocalY
-         * @memberOf me.Pointer
+         * @memberof me.Pointer
          */
         this.gameLocalY = 0;
 
        /**
-         * The unique identifier of the contact for a touch, mouse or pen
+        * The unique identifier of the contact for a touch, mouse or pen
+        * @public
+        * @type {number}
+        * @name pointerId
+        * @memberof me.Pointer
+        * @see https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pointerId
+        */
+        this.pointerId = undefined;
+
+        /**
+         * true if not originally a pointer event
          * @public
-         * @type {Number}
-         * @name pointerId
-         * @memberOf me.Pointer
-         * @see https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pointerId
+         * @type {boolean}
+         * @name isNormalized
+         * @memberof me.Pointer
          */
-        this.pointerId = undefined;
+        this.isNormalized = false;
+
+        /**
+         * true if the pointer is currently locked
+         * @public
+         * @type {boolean}
+         * @name locked
+         * @memberof me.Pointer
+         */
+        this.locked = false;
 
         // bind list for mouse buttons
         this.bind = [ 0, 0, 0 ];
@@ -276,11 +314,11 @@ class Pointer extends Bounds {
      * @private
      * @function
      * @param {Event} event the original Event object
-     * @param {Number} [pageX=0] the horizontal coordinate at which the event occurred, relative to the left edge of the entire document
-     * @param {Number} [pageY=0] the vertical coordinate at which the event occurred, relative to the left edge of the entire document
-     * @param {Number} [clientX=0] the horizontal coordinate within the application's client area at which the event occurred
-     * @param {Number} [clientX=0] the vertical coordinate within the application's client area at which the event occurred
-     * @param {Number} [pointedId=1] the Pointer, Touch or Mouse event Id (1)
+     * @param {number} [pageX=0] the horizontal coordinate at which the event occurred, relative to the left edge of the entire document
+     * @param {number} [pageY=0] the vertical coordinate at which the event occurred, relative to the left edge of the entire document
+     * @param {number} [clientX=0] the horizontal coordinate within the application's client area at which the event occurred
+     * @param {number} [clientY=0] the vertical coordinate within the application's client area at which the event occurred
+     * @param {number} [pointerId=1] the Pointer, Touch or Mouse event Id (1)
      */
     setEvent(event, pageX = 0, pageY = 0, clientX = 0, clientY = 0, pointerId = 1) {
         // the original event object
@@ -299,6 +337,10 @@ class Pointer extends Bounds {
         // true if not originally a pointer event
         this.isNormalized = !device.PointerEvent || (device.PointerEvent && !(event instanceof window.PointerEvent));
 
+        this.locked = locked;
+        this.movementX = event.movementX || 0;
+        this.movementY = event.movementY || 0;
+
         if (event.type === "wheel") {
             this.deltaMode = event.deltaMode || 0;
             this.deltaX = event.deltaX || 0;
@@ -320,8 +362,6 @@ class Pointer extends Bounds {
 
         this.type = event.type;
 
-
-
         // get the current screen to game world offset
         if (typeof viewport !== "undefined") {
             viewport.localToWorld(this.gameScreenX, this.gameScreenY, tmpVec);

package/src/input/pointerevent.js

@@ -1,23 +1,20 @@
 import {preventDefault} from "./input.js";
 import {getBindingKey, triggerKeyEvent} from "./keyboard.js";
-import Vector2d from "./../math/vector2.js";
-import { renderer, scaleRatio } from "./../video/video.js";
-import * as fctUtil from "./../utils/function.js";
-import * as arrayUtil from "./../utils/array.js";
+import { renderer, scaleRatio, getParent } from "./../video/video.js";
+import { throttle } from "./../utils/function.js";
+import { remove } from "./../utils/array.js";
 import * as event from "./../system/event.js";
 import timer from "./../system/timer.js";
 import pool from "./../system/pooling.js";
 import device from "./../system/device.js";
 import Pointer from "./pointer.js";
-import Rect from "./../shapes/rectangle.js";
+import Rect from "./../geometries/rectangle.js";
 import Container from "./../renderable/container.js";
-import Renderable from "./../renderable/renderable.js";
 import { world, viewport } from "./../game.js";
 
-
 /**
  * A pool of `Pointer` objects to cache pointer/touch event coordinates.
- * @type {Array.<Vector>}
+ * @type {Array.<me.Vector2d>}
  * @ignore
  */
 var T_POINTERS = [];
@@ -181,7 +178,7 @@ function enablePointerEvent() {
                 if (activeEventList.indexOf(events[i]) !== -1) {
                     pointerEventTarget.addEventListener(
                         events[i],
-                        fctUtil.throttle(
+                        throttle(
                             onMoveEvent,
                             throttlingInterval,
                             false
@@ -194,6 +191,17 @@ function enablePointerEvent() {
         // disable all gesture by default
         setTouchAction(pointerEventTarget);
 
+        // set a on change listener on pointerlock if supported
+        if (device.hasPointerLockSupport) {
+            document.addEventListener("pointerlockchange", () => {
+                // change the locked status accordingly
+                locked = document.pointerLockElement === getParent();
+                // emit the corresponding internal event
+                event.emit(event.POINTERLOCKCHANGE, locked);
+            }, true);
+        }
+
+        // all done !
         pointerInitialized = true;
     }
 }
@@ -292,7 +300,7 @@ function dispatchEvent(normalizedEvents) {
                 var bounds = region.getBounds();
                 var eventInBounds = false;
 
-                if (region.floating === true) {
+                if (region.isFloating === true) {
                     pointer.gameX = pointer.gameLocalX = pointer.gameScreenX;
                     pointer.gameY = pointer.gameLocalY = pointer.gameScreenY;
                 } else {
@@ -308,10 +316,11 @@ function dispatchEvent(normalizedEvents) {
                     pointer.gameLocalY = pointer.gameY - parentBounds.y;
                 }
 
+                var gameX = pointer.gameX;
+                var gameY = pointer.gameY;
+
                 // apply inverse transformation for renderable
-                if (region instanceof Renderable) {
-                    var gameX = pointer.gameX;
-                    var gameY = pointer.gameY;
+                if (typeof region.currentTransform !== "undefined") {
                     if (!region.currentTransform.isIdentity()) {
                         var invV = region.currentTransform.applyInverse(
                             pool.pull("Vector2d", gameX, gameY)
@@ -320,14 +329,8 @@ function dispatchEvent(normalizedEvents) {
                         gameY = invV.y;
                         pool.push(invV);
                     }
-                    eventInBounds = bounds.contains(gameX, gameY);
-                } else {
-                    eventInBounds =
-                        bounds.contains(pointer.gameX, pointer.gameY) &&
-                        (bounds === region ||
-                        // if the given target is another shape than me.Rect
-                        region.contains(pointer.gameLocalX, pointer.gameLocalY));
                 }
+                eventInBounds = bounds.contains(gameX, gameY);
 
                 switch (pointer.type) {
                     case POINTER_MOVE[0]:
@@ -498,9 +501,9 @@ function onPointerEvent(e) {
  /**
   * the default target element for pointer events (usually the canvas element in which the game is rendered)
   * @public
-  * @type EventTarget
+  * @type {EventTarget}
   * @name pointerEventTarget
-  * @memberOf me.input
+  * @memberof me.input
   */
  export var pointerEventTarget = null;
 
@@ -509,18 +512,28 @@ function onPointerEvent(e) {
  * @public
  * @type {me.Rect}
  * @name pointer
- * @memberOf me.input
+ * @memberof me.input
  */
 export var pointer = new Pointer(0, 0, 1, 1);
 
+
+/**
+ * indicates if the pointer is currently locked
+ * @public
+ * @type {boolean}
+ * @name locked
+ * @memberof me.input
+ */
+export var locked = false;
+
 /**
  * time interval for event throttling in milliseconds<br>
  * default value : "1000/me.timer.maxfps" ms<br>
  * set to 0 ms to disable the feature
  * @public
- * @type Number
+ * @type {number}
  * @name throttlingInterval
- * @memberOf me.input
+ * @memberof me.input
  */
 export var throttlingInterval;
 
@@ -528,13 +541,13 @@ export var throttlingInterval;
  * Translate the specified x and y values from the global (absolute)
  * coordinate to local (viewport) relative coordinate.
  * @name globalToLocal
- * @memberOf me.input
+ * @memberof me.input
  * @public
  * @function
- * @param {Number} x the global x coordinate to be translated.
- * @param {Number} y the global y coordinate to be translated.
+ * @param {number} x the global x coordinate to be translated.
+ * @param {number} y the global y coordinate to be translated.
  * @param {me.Vector2d} [v] an optional vector object where to set the translated coordinates
- * @return {me.Vector2d} A vector object with the corresponding translated coordinates
+ * @returns {me.Vector2d} A vector object with the corresponding translated coordinates
  * @example
  * onMouseEvent : function (pointer) {
  *    // convert the given into local (viewport) relative coordinates
@@ -543,7 +556,7 @@ export var throttlingInterval;
  * };
  */
 export function globalToLocal(x, y, v) {
-    v = v || new Vector2d();
+    v = v || pool.pull("Vector2d");
     var rect = device.getElementBounds(renderer.getScreenCanvas());
     var pixelRatio = device.devicePixelRatio;
     x -= rect.left + (window.pageXOffset || 0);
@@ -560,12 +573,12 @@ export function globalToLocal(x, y, v) {
  * enable/disable all gestures on the given element.<br>
  * by default melonJS will disable browser handling of all panning and zooming gestures.
  * @name setTouchAction
- * @memberOf me.input
+ * @memberof me.input
  * @see https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action
  * @public
  * @function
  * @param {HTMLCanvasElement} element
- * @param {String} [value="none"]
+ * @param {string} [value="none"]
  */
 export function setTouchAction(element, value) {
     element.style["touch-action"] = value || "none";
@@ -577,10 +590,10 @@ export function setTouchAction(element, value) {
  * Middle button – 1
  * Right button – 2
  * @name bindPointer
- * @memberOf me.input
+ * @memberof me.input
  * @public
  * @function
- * @param {Number} [button=me.input.pointer.LEFT] (accordingly to W3C values : 0,1,2 for left, middle and right buttons)
+ * @param {number} [button=me.input.pointer.LEFT] (accordingly to W3C values : 0,1,2 for left, middle and right buttons)
  * @param {me.input.KEY} keyCode
  * @example
  * // enable the keyboard
@@ -608,10 +621,10 @@ export function bindPointer() {
 /**
  * unbind the defined keycode
  * @name unbindPointer
- * @memberOf me.input
+ * @memberof me.input
  * @public
  * @function
- * @param {Number} [button=me.input.pointer.LEFT] (accordingly to W3C values : 0,1,2 for left, middle and right buttons)
+ * @param {number} [button=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);
  */
@@ -630,10 +643,10 @@ export function unbindPointer(button) {
  * @see me.Pointer
  * @see {@link http://www.w3.org/TR/pointerevents/#list-of-pointer-events|W3C Pointer Event list}
  * @name registerPointerEvent
- * @memberOf me.input
+ * @memberof me.input
  * @public
  * @function
- * @param {String} eventType The event type for which the object is registering <br>
+ * @param {string} eventType The event type for which the object is registering <br>
  * melonJS currently supports: <br>
  * <ul>
  *   <li><code>"pointermove"</code></li>
@@ -702,10 +715,10 @@ export function registerPointerEvent(eventType, region, callback) {
  * allows the removal of event listeners from the object target.
  * @see {@link http://www.w3.org/TR/pointerevents/#list-of-pointer-events|W3C Pointer Event list}
  * @name releasePointerEvent
- * @memberOf me.input
+ * @memberof me.input
  * @public
  * @function
- * @param {String} eventType The event type for which the object was registered. See {@link me.input.registerPointerEvent}
+ * @param {string} eventType The event type for which the object was registered. See {@link me.input.registerPointerEvent}
  * @param {me.Rect|me.Polygon|me.Line|me.Ellipse} region the registered region to release for this event
  * @param {Function} [callback="all"] if specified unregister the event only for the specific callback
  * @example
@@ -726,7 +739,7 @@ export function releasePointerEvent(eventType, region, callback) {
             eventType = eventTypes[i];
             if (handlers.callbacks[eventType]) {
                 if (typeof (callback) !== "undefined") {
-                    arrayUtil.remove(handlers.callbacks[eventType], callback);
+                    remove(handlers.callbacks[eventType], callback);
                 } else {
                     while (handlers.callbacks[eventType].length > 0) {
                         handlers.callbacks[eventType].pop();
@@ -747,7 +760,7 @@ export function releasePointerEvent(eventType, region, callback) {
 /**
  * allows the removal of all registered event listeners from the object target.
  * @name releaseAllPointerEvents
- * @memberOf me.input
+ * @memberof me.input
  * @public
  * @function
  * @param {me.Rect|me.Polygon|me.Line|me.Ellipse} region the registered region to release event from
@@ -762,3 +775,45 @@ export function releaseAllPointerEvents(region) {
         }
     };
 };
+
+/**
+ * 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)
+ * @name requestPointerLock
+ * @memberof me.input
+ * @public
+ * @function
+ * @param {Function} [success] callback if the request is successful
+ * @returns {boolean} return true if the request was successfully submitted
+ * @example
+ * // register on the pointer lock change event
+ * event.on(event.POINTERLOCKCHANGE, (locked)=> {
+ *     console.log("pointer lock: " + locked);
+ * });
+ * // request for pointer lock
+ * me.input.requestPointerLock();
+ */
+export function requestPointerLock() {
+    if (device.hasPointerLockSupport) {
+        var element = getParent();
+        element.requestPointerLock();
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Initiates an exit from pointer lock state
+ * @name exitPointerLock
+ * @memberof me.input
+ * @public
+ * @function
+ * @returns {boolean} return true if the request was successfully submitted
+ */
+export function exitPointerLock() {
+    if (device.hasPointerLockSupport) {
+        document.exitPointerLock();
+        return true;
+    }
+    return false;
+}