melonjs 14.1.2 → 14.3.0

package/dist/types/renderable/renderable.d.ts

@@ -0,0 +1,402 @@
+/**
+ * @classdesc
+ * A base class for renderable objects.
+ * @augments Rect
+ */
+export default class Renderable extends Rect {
+    /**
+     * to identify the object as a renderable object
+     * @ignore
+     */
+    isRenderable: boolean;
+    /**
+     * If true then physic collision and input events will not impact this renderable
+     * @type {boolean}
+     * @default true
+     */
+    isKinematic: boolean;
+    /**
+     * the renderable physic body
+     * @type {Body}
+     * @example
+     *  // define a new Player Class
+     *  class PlayerEntity extends me.Sprite {
+     *      // constructor
+     *      constructor(x, y, settings) {
+     *          // call the parent constructor
+     *          super(x, y , settings);
+     *
+     *          // define a basic walking animation
+     *          this.addAnimation("walk",  [...]);
+     *          // define a standing animation (using the first frame)
+     *          this.addAnimation("stand",  [...]);
+     *          // set the standing animation as default
+     *          this.setCurrentAnimation("stand");
+     *
+     *          // add a physic body
+     *          this.body = new me.Body(this);
+     *          // add a default collision shape
+     *          this.body.addShape(new me.Rect(0, 0, this.width, this.height));
+     *          // configure max speed, friction, and initial force to be applied
+     *          this.body.setMaxVelocity(3, 15);
+     *          this.body.setFriction(0.4, 0);
+     *          this.body.force.set(3, 0);
+     *
+     *          // set the display to follow our position on both axis
+     *          me.game.viewport.follow(this.pos, me.game.viewport.AXIS.BOTH);
+     *      }
+     *
+     *      ...
+     *
+     * }
+     */
+    body: Body;
+    /**
+     * the renderable default transformation matrix
+     * @type {Matrix2d}
+     */
+    currentTransform: Matrix2d;
+    /**
+     * (G)ame (U)nique (Id)entifier" <br>
+     * a GUID will be allocated for any renderable object added <br>
+     * to an object container (including the `me.game.world` container)
+     * @type {string}
+     */
+    GUID: string;
+    /**
+     * an event handler that is called when the renderable leave or enter a camera viewport
+     * @type {Function}
+     * @default undefined
+     * @example
+     * this.onVisibilityChange = function(inViewport) {
+     *     if (inViewport === true) {
+     *         console.log("object has entered the in a camera viewport!");
+     *     }
+     * };
+     */
+    onVisibilityChange: Function;
+    /**
+     * Whether the renderable object will always update, even when outside of the viewport<br>
+     * @type {boolean}
+     * @default false
+     */
+    alwaysUpdate: boolean;
+    /**
+     * Whether to update this object when the game is paused.
+     * @type {boolean}
+     * @default false
+     */
+    updateWhenPaused: boolean;
+    /**
+     * make the renderable object persistent over level changes<br>
+     * @type {boolean}
+     * @default false
+     */
+    isPersistent: boolean;
+    /**
+     * If true, this renderable will be rendered using screen coordinates,
+     * as opposed to world coordinates. Use this, for example, to define UI elements.
+     * @type {boolean}
+     * @default false
+     */
+    floating: boolean;
+    /**
+     * The anchor point is used for attachment behavior, and/or when applying transformations.<br>
+     * The coordinate system places the origin at the top left corner of the frame (0, 0) and (1, 1) means the bottom-right corner<br>
+     * <img src="images/anchor_point.png"/><br>
+     * a Renderable's anchor point defaults to (0.5,0.5), which corresponds to the center position.<br>
+     * <br>
+     * <i><b>Note:</b> Object created through Tiled will have their anchorPoint set to (0, 0) to match Tiled Level editor implementation.
+     * To specify a value through Tiled, use a json expression like `json:{"x":0.5,"y":0.5}`. </i>
+     * @type {ObservableVector2d}
+     * @default <0.5,0.5>
+     */
+    anchorPoint: ObservableVector2d;
+    /**
+     * When enabled, an object container will automatically apply
+     * any defined transformation before calling the child draw method.
+     * @type {boolean}
+     * @default true
+     * @example
+     * // enable "automatic" transformation when the object is activated
+     * onActivateEvent: function () {
+     *     // reset the transformation matrix
+     *     this.currentTransform.identity();
+     *     // ensure the anchor point is the renderable center
+     *     this.anchorPoint.set(0.5, 0.5);
+     *     // enable auto transform
+     *     this.autoTransform = true;
+     *     ....
+     * }
+     */
+    autoTransform: boolean;
+    /**
+     * Define the renderable opacity<br>
+     * Set to zero if you do not wish an object to be drawn
+     * @see Renderable#setOpacity
+     * @see Renderable#getOpacity
+     * @type {number}
+     * @default 1.0
+     */
+    alpha: number;
+    /**
+     * a reference to the parent object that contains this renderable
+     * @type {Container|Entity}
+     * @default undefined
+     */
+    ancestor: Container | Entity;
+    /**
+     * A mask limits rendering elements to the shape and position of the given mask object.
+     * So, if the renderable is larger than the mask, only the intersecting part of the renderable will be visible.
+     * @type {Rect|RoundRect|Polygon|Line|Ellipse}
+     * @default undefined
+     * @example
+     * // apply a mask in the shape of a Star
+     * myNPCSprite.mask = new me.Polygon(myNPCSprite.width / 2, 0, [
+     *    // draw a star
+     *    {x: 0, y: 0},
+     *    {x: 14, y: 30},
+     *    {x: 47, y: 35},
+     *    {x: 23, y: 57},
+     *    {x: 44, y: 90},
+     *    {x: 0, y: 62},
+     *    {x: -44, y: 90},
+     *    {x: -23, y: 57},
+     *    {x: -47, y: 35},
+     *    {x: -14, y: 30}
+     * ]);
+     */
+    mask: Rect | RoundRect | Polygon | Line | Ellipse;
+    /**
+     * the blend mode to be applied to this renderable (see renderer setBlendMode for available blend mode)
+     * @type {string}
+     * @default "normal"
+     * @see CanvasRenderer#setBlendMode
+     * @see WebGLRenderer#setBlendMode
+     */
+    blendMode: string;
+    /**
+     * The name of the renderable
+     * @type {string}
+     * @default ""
+     */
+    name: string;
+    /**
+     * Position of the Renderable relative to its parent container
+     * @public
+     * @type {ObservableVector3d}
+     */
+    public pos: ObservableVector3d;
+    /**
+     * when true the renderable will be redrawn during the next update cycle
+     * @type {boolean}
+     * @default false
+     */
+    isDirty: boolean;
+    _flip: {
+        x: boolean;
+        y: boolean;
+    };
+    _inViewport: boolean;
+    /**
+     * Whether the renderable object is floating, or contained in a floating container
+     * @see Renderable#floating
+     * @type {boolean}
+     */
+    get isFloating(): boolean;
+    set tint(arg: Color);
+    /**
+     * define a tint for this renderable. a (255, 255, 255) r, g, b value will remove the tint effect.
+     * @type {Color}
+     * @default (255, 255, 255)
+     * @example
+     * // add a red tint to this renderable
+     * this.tint.setColor(255, 128, 128);
+     * // remove the tint
+     * this.tint.setColor(255, 255, 255);
+     */
+    get tint(): Color;
+    _tint: object | undefined;
+    set inViewport(arg: boolean);
+    /**
+     * Whether the renderable object is visible and within the viewport
+     * @type {boolean}
+     * @default false
+     */
+    get inViewport(): boolean;
+    /**
+     * returns true if this renderable is flipped on the horizontal axis
+     * @public
+     * @see Renderable#flipX
+     * @type {boolean}
+     */
+    public get isFlippedX(): boolean;
+    /**
+     * returns true if this renderable is flipped on the vertical axis
+     * @public
+     * @see Renderable#flipY
+     * @type {boolean}
+     */
+    public get isFlippedY(): boolean;
+    /**
+     * get the renderable alpha channel value<br>
+     * @returns {number} current opacity value between 0 and 1
+     */
+    getOpacity(): number;
+    /**
+     * set the renderable alpha channel value<br>
+     * @param {number} alpha - opacity value between 0.0 and 1.0
+     */
+    setOpacity(alpha: number): void;
+    /**
+     * flip the renderable on the horizontal axis (around the center of the renderable)
+     * @see Matrix2d#scaleX
+     * @param {boolean} [flip=true] - `true` to flip this renderable.
+     * @returns {Renderable} Reference to this object for method chaining
+     */
+    flipX(flip?: boolean | undefined): Renderable;
+    /**
+     * flip the renderable on the vertical axis (around the center of the renderable)
+     * @see Matrix2d#scaleY
+     * @param {boolean} [flip=true] - `true` to flip this renderable.
+     * @returns {Renderable} Reference to this object for method chaining
+     */
+    flipY(flip?: boolean | undefined): Renderable;
+    /**
+     * multiply the renderable currentTransform with the given matrix
+     * @see Renderable#currentTransform
+     * @param {Matrix2d} m - the transformation matrix
+     * @returns {Renderable} Reference to this object for method chaining
+     */
+    transform(m: Matrix2d): Renderable;
+    /**
+     * return the angle to the specified target
+     * @param {Renderable|Vector2d|Vector3d} target
+     * @returns {number} angle in radians
+     */
+    angleTo(target: Renderable | Vector2d | Vector3d): number;
+    /**
+     * return the distance to the specified target
+     * @param {Renderable|Vector2d|Vector3d} target
+     * @returns {number} distance
+     */
+    distanceTo(target: Renderable | Vector2d | Vector3d): number;
+    /**
+     * Rotate this renderable towards the given target.
+     * @param {Renderable|Vector2d|Vector3d} target - the renderable or position to look at
+     * @returns {Renderable} Reference to this object for method chaining
+     */
+    lookAt(target: Renderable | Vector2d | Vector3d): Renderable;
+    /**
+     * Rotate this renderable by the specified angle (in radians).
+     * @param {number} angle - The angle to rotate (in radians)
+     * @param {Vector2d|ObservableVector2d} [v] - an optional point to rotate around
+     * @returns {Renderable} Reference to this object for method chaining
+     */
+    rotate(angle: number, v?: Vector2d | ObservableVector2d): Renderable;
+    /**
+     * scale the renderable around his anchor point.  Scaling actually applies changes
+     * to the currentTransform member wich is used by the renderer to scale the object
+     * when rendering.  It does not scale the object itself.  For example if the renderable
+     * is an image, the image.width and image.height properties are unaltered but the currentTransform
+     * member will be changed.
+     * @param {number} x - a number representing the abscissa of the scaling vector.
+     * @param {number} [y=x] - a number representing the ordinate of the scaling vector.
+     * @returns {Renderable} Reference to this object for method chaining
+     */
+    scale(x: number, y?: number | undefined): Renderable;
+    /**
+     * scale the renderable around his anchor point
+     * @param {Vector2d} v - scaling vector
+     * @returns {Renderable} Reference to this object for method chaining
+     */
+    scaleV(v: Vector2d): Renderable;
+    /**
+     * update function (automatically called by melonJS).
+     * @param {number} dt - time since the last update in milliseconds.
+     * @returns {boolean} true if the renderable is dirty
+     */
+    update(dt: number): boolean;
+    /**
+     * update the renderable's bounding rect (private)
+     * @ignore
+     */
+    updateBoundsPos(newX: any, newY: any): void;
+    /**
+     * return the renderable absolute position in the game world
+     * @returns {Vector2d}
+     */
+    getAbsolutePosition(): Vector2d;
+    _absPos: object | undefined;
+    /**
+     * called when the anchor point value is changed
+     * @private
+     * @param {number} x - the new X value to be set for the anchor
+     * @param {number} y - the new Y value to be set for the anchor
+     */
+    private onAnchorUpdate;
+    /**
+     * Prepare the rendering context before drawing (automatically called by melonJS).
+     * This will apply any defined transforms, anchor point, tint or blend mode and translate the context accordingly to this renderable position.
+     * @see Renderable#draw
+     * @see Renderable#postDraw
+     * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer object
+     */
+    preDraw(renderer: CanvasRenderer | WebGLRenderer): void;
+    /**
+     * Draw this renderable (automatically called by melonJS).
+     * All draw operations for renderable are made respectively
+     * to the position or transforms set or applied by the preDraw method.
+     * The main draw loop will first call preDraw() to prepare the context for drawing the renderable,
+     * then draw() to draw the renderable, and finally postDraw() to clear the context.
+     * If you override this method, be mindful about the drawing logic; for example if you draw a shape
+     * from the draw method, you should make sure that your draw it at the 0, 0 coordinates.
+     * @see Renderable#preDraw
+     * @see Renderable#postDraw
+     * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+     * @param {Camera2d} [viewport] - the viewport to (re)draw
+     */
+    draw(renderer: CanvasRenderer | WebGLRenderer, viewport?: any): void;
+    /**
+     * restore the rendering context after drawing (automatically called by melonJS).
+     * @see Renderable#preDraw
+     * @see Renderable#draw
+     * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer object
+     */
+    postDraw(renderer: CanvasRenderer | WebGLRenderer): void;
+    /**
+     * onCollision callback, triggered in case of collision,
+     * when this renderable body is colliding with another one
+     * @param {ResponseObject} response - the collision response object
+     * @param {Renderable} other - the other renderable touching this one (a reference to response.a or response.b)
+     * @returns {boolean} true if the object should respond to the collision (its position and velocity will be corrected)
+     * @example
+     * // colision handler
+     * onCollision(response) {
+     *     if (response.b.body.collisionType === me.collision.types.ENEMY_OBJECT) {
+     *         // makes the other object solid, by substracting the overlap vector to the current position
+     *         this.pos.sub(response.overlapV);
+     *         this.hurt();
+     *         // not solid
+     *         return false;
+     *     }
+     *     // Make the object solid
+     *     return true;
+     * },
+     */
+    onCollision(response: ResponseObject, other: Renderable): boolean;
+    /**
+     * Destroy function<br>
+     * @ignore
+     */
+    destroy(...args: any[]): void;
+    /**
+     * OnDestroy Notification function<br>
+     * Called by engine before deleting the object
+     */
+    onDestroyEvent(): void;
+}
+import Rect from "./../geometries/rectangle.js";
+import ObservableVector2d from "./../math/observable_vector2.js";
+import ObservableVector3d from "./../math/observable_vector3.js";
+import Color from "./../math/color.js";

package/dist/types/renderable/sprite.d.ts

@@ -0,0 +1,268 @@
+/**
+ * @classdesc
+ * An object to display a fixed or animated sprite on screen.
+ * @augments Renderable
+ */
+export default class Sprite extends Renderable {
+    /**
+     * @param {number} x - the x coordinates of the sprite object
+     * @param {number} y - the y coordinates of the sprite object
+     * @param {object} settings - Configuration parameters for the Sprite object
+     * @param {HTMLImageElement|HTMLCanvasElement|TextureAtlas|string} settings.image - reference to spritesheet image, a texture atlas or to a texture atlas
+     * @param {string} [settings.name=""] - name of this object
+     * @param {string} [settings.region] - region name of a specific region to use when using a texture atlas, see {@link TextureAtlas}
+     * @param {number} [settings.framewidth] - Width of a single frame within the spritesheet
+     * @param {number} [settings.frameheight] - Height of a single frame within the spritesheet
+     * @param {string|Color} [settings.tint] - a tint to be applied to this sprite
+     * @param {number} [settings.flipX] - flip the sprite on the horizontal axis
+     * @param {number} [settings.flipY] - flip the sprite on the vertical axis
+     * @param {Vector2d} [settings.anchorPoint={x:0.5, y:0.5}] - Anchor point to draw the frame at (defaults to the center of the frame).
+     * @example
+     * // create a single sprite from a standalone image, with anchor in the center
+     * var sprite = new me.Sprite(0, 0, {
+     *     image : "PlayerTexture",
+     *     framewidth : 64,
+     *     frameheight : 64,
+     *     anchorPoint : new me.Vector2d(0.5, 0.5)
+     * });
+     *
+     * // create a single sprite from a packed texture
+     * game.texture = new me.TextureAtlas(
+     *     me.loader.getJSON("texture"),
+     *     me.loader.getImage("texture")
+     * );
+     * var sprite = new me.Sprite(0, 0, {
+     *     image : game.texture,
+     *     region : "npc2.png",
+     * });
+     */
+    constructor(x: number, y: number, settings: {
+        image: HTMLImageElement | HTMLCanvasElement | TextureAtlas | string;
+        name?: string | undefined;
+        region?: string | undefined;
+        framewidth?: number | undefined;
+        frameheight?: number | undefined;
+        tint?: string | Color | undefined;
+        flipX?: number | undefined;
+        flipY?: number | undefined;
+        anchorPoint?: any;
+    });
+    /**
+     * pause and resume animation
+     * @public
+     * @type {boolean}
+     * @default false
+     * @name Sprite#animationpause
+     */
+    public animationpause: boolean;
+    /**
+     * animation cycling speed (delay between frame in ms)
+     * @public
+     * @type {number}
+     * @default 100
+     * @name Sprite#animationspeed
+     */
+    public animationspeed: number;
+    /**
+     * global offset for the position to draw from on the source image.
+     * @public
+     * @type {Vector2d}
+     * @default <0.0,0.0>
+     * @name offset
+     * @memberof Sprite#
+     */
+    public offset: Vector2d;
+    /**
+     * The source texture object this sprite object is using
+     * @public
+     * @type {TextureAtlas}
+     * @name source
+     * @memberof Sprite#
+     */
+    public source: TextureAtlas;
+    anim: {};
+    resetAnim: Function | (() => Sprite) | undefined;
+    current: {
+        name: string;
+        length: number;
+        offset: object;
+        width: number;
+        height: number;
+        angle: number;
+        idx: number;
+    };
+    dt: number;
+    _flicker: {
+        isFlickering: boolean;
+        duration: number;
+        callback: null;
+        state: boolean;
+    };
+    image: HTMLCanvasElement | HTMLImageElement;
+    textureAtlas: any;
+    atlasIndices: any;
+    /**
+     * return the flickering state of the object
+     * @name isFlickering
+     * @memberof Sprite
+     * @returns {boolean}
+     */
+    isFlickering(): boolean;
+    /**
+     * make the object flicker
+     * @name flicker
+     * @memberof Sprite
+     * @param {number} duration - expressed in milliseconds
+     * @param {Function} callback - Function to call when flickering ends
+     * @returns {Sprite} Reference to this object for method chaining
+     * @example
+     * // make the object flicker for 1 second
+     * // and then remove it
+     * this.flicker(1000, function () {
+     *     me.game.world.removeChild(this);
+     * });
+     */
+    flicker(duration: number, callback: Function): Sprite;
+    /**
+     * add an animation <br>
+     * For fixed-sized cell sprite sheet, the index list must follow the
+     * logic as per the following example :<br>
+     * <img src="images/spritesheet_grid.png"/>
+     * @name addAnimation
+     * @memberof Sprite
+     * @param {string} name - animation id
+     * @param {number[]|string[]|object[]} index - list of sprite index or name
+     * defining the animation. Can also use objects to specify delay for each frame, see below
+     * @param {number} [animationspeed] - cycling speed for animation in ms
+     * @returns {number} frame amount of frame added to the animation (delay between each frame).
+     * @see Sprite#animationspeed
+     * @example
+     * // walking animation
+     * this.addAnimation("walk", [ 0, 1, 2, 3, 4, 5 ]);
+     * // standing animation
+     * this.addAnimation("stand", [ 11, 12 ]);
+     * // eating animation
+     * this.addAnimation("eat", [ 6, 6 ]);
+     * // rolling animation
+     * this.addAnimation("roll", [ 7, 8, 9, 10 ]);
+     * // slower animation
+     * this.addAnimation("roll", [ 7, 8, 9, 10 ], 200);
+     * // or get more specific with delay for each frame. Good solution instead of repeating:
+     * this.addAnimation("turn", [{ name: 0, delay: 200 }, { name: 1, delay: 100 }])
+     * // can do this with atlas values as well:
+     * this.addAnimation("turn", [{ name: "turnone", delay: 200 }, { name: "turntwo", delay: 100 }])
+     * // define an dying animation that stop on the last frame
+     * this.addAnimation("die", [{ name: 3, delay: 200 }, { name: 4, delay: 100 }, { name: 5, delay: Infinity }])
+     * // set the standing animation as default
+     * this.setCurrentAnimation("stand");
+     */
+    addAnimation(name: string, index: number[] | string[] | object[], animationspeed?: number | undefined): number;
+    /**
+     * set the current animation
+     * this will always change the animation & set the frame to zero
+     * @name setCurrentAnimation
+     * @memberof Sprite
+     * @param {string} name - animation id
+     * @param {string|Function} [resetAnim] - animation id to switch to when complete, or callback
+     * @param {boolean} [preserve_dt=false] - if false will reset the elapsed time counter since last frame
+     * @returns {Sprite} Reference to this object for method chaining
+     * @example
+     * // set "walk" animation
+     * this.setCurrentAnimation("walk");
+     *
+     * // set "walk" animation if it is not the current animation
+     * if (this.isCurrentAnimation("walk")) {
+     *     this.setCurrentAnimation("walk");
+     * }
+     *
+     * // set "eat" animation, and switch to "walk" when complete
+     * this.setCurrentAnimation("eat", "walk");
+     *
+     * // set "die" animation, and remove the object when finished
+     * this.setCurrentAnimation("die", (function () {
+     *    me.game.world.removeChild(this);
+     *    return false; // do not reset to first frame
+     * }).bind(this));
+     *
+     * // set "attack" animation, and pause for a short duration
+     * this.setCurrentAnimation("die", (function () {
+     *    this.animationpause = true;
+     *
+     *    // back to "standing" animation after 1 second
+     *    setTimeout(function () {
+     *        this.setCurrentAnimation("standing");
+     *    }, 1000);
+     *
+     *    return false; // do not reset to first frame
+     * }).bind(this));
+     */
+    setCurrentAnimation(name: string, resetAnim?: string | Function | undefined, preserve_dt?: boolean | undefined): Sprite;
+    /**
+     * reverse the given or current animation if none is specified
+     * @name reverseAnimation
+     * @memberof Sprite
+     * @param {string} [name] - animation id
+     * @returns {Sprite} Reference to this object for method chaining
+     * @see Sprite#animationspeed
+     */
+    reverseAnimation(name?: string | undefined): Sprite;
+    /**
+     * return true if the specified animation is the current one.
+     * @name isCurrentAnimation
+     * @memberof Sprite
+     * @param {string} name - animation id
+     * @returns {boolean}
+     * @example
+     * if (!this.isCurrentAnimation("walk")) {
+     *     // do something funny...
+     * }
+     */
+    isCurrentAnimation(name: string): boolean;
+    /**
+     * change the current texture atlas region for this sprite
+     * @see Texture.getRegion
+     * @name setRegion
+     * @memberof Sprite
+     * @param {object} region - typically returned through me.Texture.getRegion()
+     * @returns {Sprite} Reference to this object for method chaining
+     * @example
+     * // change the sprite to "shadedDark13.png";
+     * mySprite.setRegion(game.texture.getRegion("shadedDark13.png"));
+     */
+    setRegion(region: object): Sprite;
+    /**
+     * force the current animation frame index.
+     * @name setAnimationFrame
+     * @memberof Sprite
+     * @param {number} [idx=0] - animation frame index
+     * @returns {Sprite} Reference to this object for method chaining
+     * @example
+     * // reset the current animation to the first frame
+     * this.setAnimationFrame();
+     */
+    setAnimationFrame(idx?: number | undefined): Sprite;
+    /**
+     * return the current animation frame index.
+     * @name getCurrentAnimationFrame
+     * @memberof Sprite
+     * @returns {number} current animation frame index
+     */
+    getCurrentAnimationFrame(): number;
+    /**
+     * Returns the frame object by the index.
+     * @name getAnimationFrameObjectByIndex
+     * @memberof Sprite
+     * @ignore
+     * @param {number} id - the frame id
+     * @returns {number} if using number indices. Returns {object} containing frame data if using texture atlas
+     */
+    getAnimationFrameObjectByIndex(id: number): number;
+    /**
+     * Destroy function<br>
+     * @ignore
+     */
+    destroy(): void;
+}
+import Renderable from "./renderable.js";
+import { TextureAtlas } from "./../video/texture/atlas.js";
+import Color from "../math/color.js";