diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b8421470..8fa21460b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,8 +49,43 @@ being passed to the simulation. The default value is 1 to remain consistent with * The ComputedSize Component now has `setSize` and `setDisplaySize` methods. This component is used for Game Objects that have a non-texture based size. * The GamepadManager now extends EventEmitter directly, just like the KeyboardManager does. * The Gamepad Axis threshold has been increased from 0.05 to 0.1. -* Animation.updateFrame will now call `setSizeToFrame` on the Game Object, which will adjust the Game Objects `width` and `height` properties to match the frame size. Fix #3473 (thanks @wtravO @jp-gc) -* Animation.updateFrame now supports animation frames with custom pivot points and injects these into the Game Object origin. + +### Animation Component Updates + +We have refactored a large part of the Animation API to make it more consistent with the rest of Phaser 3 and to fix some issues. The following changes all apply to the Animation Component: + +* `delay` method has been removed. +* `setDelay` allows you to define the delay before playback begins. +* `getDelay` returns the animation playback delay value. +* `delayedPlay` now returns the parent Game Object instead of the component. +* `load` now returns the parent Game Object instead of the component. +* `pause` now returns the parent Game Object instead of the component. +* `resume` now returns the parent Game Object instead of the component. +* `isPaused` returns a boolean indicating the paused state of the animation. +* `paused` method has been removed. +* `play` now returns the parent Game Object instead of the component. +* `progress` method has been removed. +* `getProgress` returns the animation progress value. +* `repeat` method has been removed. +* `getRepeat` returns the animation repeat value. +* `setRepeat` sets the number of times the current animation will repeat. +* `repeatDelay` method has been removed. +* `getRepeatDelay` returns the animation repeat delay value. +* `setRepeatDelay` sets the delay time between each repeat. +* `restart` now returns the parent Game Object instead of the component. +* `stop` now returns the parent Game Object instead of the component. +* `timeScale` method has been removed. +* `getTimeScale` returns the animation time scale value. +* `setTimeScale` sets the time scale value. +* `totalFrames` method has been removed. +* `getTotalFrames` returns the total number of frames in the animation. +* `totalProgres` method has been removed as it did nothing and was mis-spelt. +* `yoyo` method has been removed. +* `getYoYo` returns if the animation will yoyo or not. +* `setYoYoScale` sets if the animation will yoyo or not. +* `updateFrame` will now call `setSizeToFrame` on the Game Object, which will adjust the Game Objects `width` and `height` properties to match the frame size. Fix #3473 (thanks @wtravO @jp-gc) +* `updateFrame` now supports animation frames with custom pivot points and injects these into the Game Object origin. +* `destroy` now removes events, references to the Animation Manager and parent Game Object, clears the current animation and frame and empties internal arrays. Also, my thanks to the following for helping with the Phaser 3 Examples and Docs, either by reporting errors, fixing them or helping author the docs: @gabegordon @melissaelopez @samid737 @nbs @tgrajewski @pagesrichie @hexus @mbrickn @erd0s @icbat @Matthew-Herman diff --git a/src/gameobjects/components/Animation.js b/src/gameobjects/components/Animation.js index d8700c538..07474f5cf 100644 --- a/src/gameobjects/components/Animation.js +++ b/src/gameobjects/components/Animation.js @@ -55,8 +55,6 @@ var Animation = new Class({ */ this.isPlaying = false; - // Reference to the Phaser.Animation object - /** * The current Animation loaded into this Animation Controller. * @@ -272,24 +270,32 @@ var Animation = new Class({ * Sets the amount of time, in seconds that the animation will be delayed before starting playback. * * @method Phaser.GameObjects.Components.Animation#delay - * @since 3.0.0 + * @since 3.4.0 * - * @param {number} value - The amount of time, in seconds, to wait before starting playback. + * @param {number} [value=0] - The amount of time, in seconds, to wait before starting playback. * - * @return {Phaser.GameObjects.GameObject} This Game Object. + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ - delay: function (value) + setDelay: function (value) { - if (value === undefined) - { - return this._delay; - } - else - { - this._delay = value; + if (value === undefined) { value = 0; } - return this; - } + this._delay = value; + + return this.parent; + }, + + /** + * Gets the amount of time, in seconds that the animation will be delayed before starting playback. + * + * @method Phaser.GameObjects.Components.Animation#delay + * @since 3.4.0 + * + * @return {number} The amount of time, in seconds, the Animation will wait before starting playback. + */ + getDelay: function () + { + return this._delay; }, /** @@ -302,7 +308,7 @@ var Animation = new Class({ * @param {string} key - [description] * @param {integer} startFrame - [description] * - * @return {Phaser.GameObjects.GameObject} This Game Object. + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ delayedPlay: function (delay, key, startFrame) { @@ -310,7 +316,7 @@ var Animation = new Class({ this.nextTick += (delay * 1000); - return this; + return this.parent; }, /** @@ -338,7 +344,7 @@ var Animation = new Class({ * @param {string} key - [description] * @param {integer} [startFrame=0] - [description] * - * @return {Phaser.GameObjects.GameObject} This Game Object. + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ load: function (key, startFrame) { @@ -352,7 +358,7 @@ var Animation = new Class({ // Load the new animation in this.animationManager.load(this, key, startFrame); - return this; + return this.parent; }, /** @@ -363,7 +369,7 @@ var Animation = new Class({ * * @param {Phaser.Animations.Animation} [atFrame] - [description] * - * @return {Phaser.GameObjects.GameObject} This Game Object. + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ pause: function (atFrame) { @@ -379,37 +385,49 @@ var Animation = new Class({ this.updateFrame(atFrame); } - return this; + return this.parent; }, /** * [description] * - * @method Phaser.GameObjects.Components.Animation#paused + * @method Phaser.GameObjects.Components.Animation#resume * @since 3.0.0 * - * @param {boolean} [value] - [description] + * @param {Phaser.Animations.AnimationFrame} [fromFrame] - [description] * - * @return {(boolean|Phaser.GameObjects.GameObject)} [description] + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ - paused: function (value) + resume: function (fromFrame) { - if (value !== undefined) + if (this._paused) { - // Setter - if (value) - { - return this.pause(); - } - else - { - return this.resume(); - } + this._paused = false; + this.isPlaying = this._wasPlaying; } - else + + if (fromFrame !== undefined) + { + this.updateFrame(fromFrame); + } + + return this.parent; + }, + + /** + * `true` if the current animation is paused, otherwise `false`. + * + * @name Phaser.GameObjects.Components.Animation#isPaused + * @type {boolean} + * @since 3.4.0 + */ + isPaused: { + + get: function () { return this._paused; } + }, /** @@ -422,7 +440,7 @@ var Animation = new Class({ * @param {boolean} [ignoreIfPlaying=false] - [description] * @param {integer} [startFrame=0] - [description] * - * @return {Phaser.GameObjects.GameObject} This Game Object. + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ play: function (key, ignoreIfPlaying, startFrame) { @@ -431,7 +449,7 @@ var Animation = new Class({ if (ignoreIfPlaying && this.isPlaying && this.currentAnim.key === key) { - return this; + return this.parent; } this.load(key, startFrame); @@ -458,45 +476,33 @@ var Animation = new Class({ anim.onStart.apply(anim.callbackScope, this._callbackArgs.concat(anim.onStartParams)); } - gameObject.setSizeToFrame(); - gameObject.updateDisplayOrigin(); - - return this; + return gameObject; }, /** - * Value between 0 and 1. How far this animation is through, ignoring repeats and yoyos. - * If the animation has a non-zero repeat defined, progress and totalProgress will be different - * because progress doesn't include any repeats or repeatDelays whereas totalProgress does. + * Returns a value between 0 and 1 indicating how far this animation is through, ignoring repeats and yoyos. + * If the animation has a non-zero repeat defined, `getProgress` and `getTotalProgress` will be different + * because `getProgress` doesn't include any repeats or repeat delays, whereas `getTotalProgress` does. * - * @method Phaser.GameObjects.Components.Animation#progress - * @since 3.0.0 + * @method Phaser.GameObjects.Components.Animation#getProgress + * @since 3.4.0 * - * @param {number} [value] - [description] - * - * @return {(number|Phaser.GameObjects.GameObject)} [description] + * @return {float} The progress of the current animation, between 0 and 1. */ - progress: function (value) + getProgress: function () { - if (value === undefined) + var p = this.currentFrame.progress; + + if (!this.forward) { - var p = this.currentFrame.progress; - - if (!this.forward) - { - p = 1 - p; - } - - return p; + p = 1 - p; } - else - { - // TODO: Set progress - return this; - } + return p; }, + // TODO: Set progress + /** * [description] * @@ -518,69 +524,85 @@ var Animation = new Class({ }, /** - * Gets or sets the number of times that the animation should repeat + * Gets the number of times that the animation will repeat + * after its first iteration. For example, if returns 1, the animation will + * play a total of twice (the initial play plus 1 repeat). + * A value of -1 means the animation will repeat indefinitely. + * + * @method Phaser.GameObjects.Components.Animation#getRepeat + * @since 3.4.0 + * + * @return {integer} The number of times that the animation will repeat. + */ + getRepeat: function () + { + return this._repeat; + }, + + /** + * Sets the number of times that the animation should repeat * after its first iteration. For example, if repeat is 1, the animation will * play a total of twice (the initial play plus 1 repeat). * To repeat indefinitely, use -1. repeat should always be an integer. * - * @method Phaser.GameObjects.Components.Animation#repeat - * @since 3.0.0 + * @method Phaser.GameObjects.Components.Animation#setRepeat + * @since 3.4.0 * - * @param {number} value - [description] + * @param {integer} value - [description] * - * @return {(number|Phaser.GameObjects.GameObject)} [description] + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ - repeat: function (value) + setRepeat: function (value) { - if (value === undefined) - { - return this._repeat; - } - else - { - this._repeat = value; - this.repeatCounter = 0; + this._repeat = value; - return this; - } + this.repeatCounter = 0; + + return this.parent; }, /** - * Gets or sets the amount of time in seconds between repeats. - * For example, if repeat is 2 and repeatDelay is 1, the animation will play initially, - * then wait for 1 second before it repeats, then play again, then wait 1 second again + * Gets the amount of delay between repeats, if any. + * + * @method Phaser.GameObjects.Components.Animation#getRepeatDelay + * @since 3.4.0 + * + * @return {number} The delay between repeats. + */ + getRepeatDelay: function () + { + return this._repeatDelay; + }, + + /** + * Sets the amount of time in seconds between repeats. + * For example, if `repeat` is 2 and `repeatDelay` is 10, the animation will play initially, + * then wait for 10 seconds before repeating, then play again, then wait another 10 seconds * before doing its final repeat. * - * @method Phaser.GameObjects.Components.Animation#repeatDelay - * @since 3.0.0 + * @method Phaser.GameObjects.Components.Animation#setRepeatDelay + * @since 3.4.0 * - * @param {number} [value] - [description] + * @param {number} value - The delay to wait between repeats, in seconds. * - * @return {(number|Phaser.GameObjects.GameObject)} [description] + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ - repeatDelay: function (value) + setRepeatDelay: function (value) { - if (value === undefined) - { - return this._repeatDelay; - } - else - { - this._repeatDelay = value; + this._repeatDelay = value; - return this; - } + return this.parent; }, /** - * [description] + * Restarts the current animation from its beginning, optionally including its delay value. * * @method Phaser.GameObjects.Components.Animation#restart * @since 3.0.0 * * @param {boolean} [includeDelay=false] - [description] * - * @return {Phaser.GameObjects.GameObject} This Game Object. + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ restart: function (includeDelay) { @@ -596,44 +618,18 @@ var Animation = new Class({ // Set frame this.updateFrame(this.currentAnim.frames[0]); - return this; + return this.parent; }, /** - * [description] - * - * @method Phaser.GameObjects.Components.Animation#resume - * @since 3.0.0 - * - * @param {Phaser.Animations.AnimationFrame} fromFrame - [description] - * - * @return {Phaser.GameObjects.GameObject} This Game Object. - */ - resume: function (fromFrame) - { - if (this._paused) - { - this._paused = false; - this.isPlaying = this._wasPlaying; - } - - if (fromFrame !== undefined) - { - this.updateFrame(fromFrame); - } - - return this; - }, - - /** - * [description] + * Stops the current animation from playing and optionally dispatches any onComplete callbacks. * * @method Phaser.GameObjects.Components.Animation#stop * @since 3.0.0 * * @param {boolean} [dispatchCallbacks=false] - [description] * - * @return {Phaser.GameObjects.GameObject} This Game Object. + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ stop: function (dispatchCallbacks) { @@ -648,63 +644,57 @@ var Animation = new Class({ anim.onComplete.apply(anim.callbackScope, this._callbackArgs.concat(anim.onCompleteParams)); } - return this; + return this.parent; }, /** - * Scale the time (make it go faster / slower) - * Factor that's used to scale time where 1 = normal speed (the default), 0.5 = half speed, 2 = double speed, etc. + * Sets the Time Scale factor, allowing you to make the animation go go faster or slower than default. + * Where 1 = normal speed (the default), 0.5 = half speed, 2 = double speed, etc. * - * @method Phaser.GameObjects.Components.Animation#timeScale - * @since 3.0.0 + * @method Phaser.GameObjects.Components.Animation#setTimeScale + * @since 3.4.0 * - * @param {number} [value] - [description] + * @param {number} [value=1] - The time scale factor, where 1 is no change, 0.5 is half speed, etc. * - * @return {(number|Phaser.GameObjects.GameObject)} [description] + * @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component. */ - timeScale: function (value) + setTimeScale: function (value) { - if (value === undefined) - { - return this._timeScale; - } - else - { - this._timeScale = value; + if (value === undefined) { value = 1; } - return this; - } + this._timeScale = value; + + return this.parent; }, /** - * [description] + * Gets the Time Scale factor. * - * @method Phaser.GameObjects.Components.Animation#totalFrames - * @since 3.0.0 + * @method Phaser.GameObjects.Components.Animation#getTimeScale + * @since 3.4.0 * - * @return {number} [description] + * @return {number} The Time Scale value. */ - totalFrames: function () + getTimeScale: function () + { + return this._timeScale; + }, + + /** + * Returns the total number of frames in this animation. + * + * @method Phaser.GameObjects.Components.Animation#getTotalFrames + * @since 3.4.0 + * + * @return {integer} The total number of frames in this animation. + */ + getTotalFrames: function () { return this.currentAnim.frames.length; }, - // Value between 0 and 1. How far this animation is through, including things like delays - // repeats, custom frame durations, etc. If the animation is set to repeat -1 it can never - // have a duration, therefore this will return -1. /** - * [description] - * - * @method Phaser.GameObjects.Components.Animation#totalProgres - * @since 3.0.0 - */ - totalProgres: function () - { - // TODO - }, - - /** - * [description] + * The internal update loop for the Animation Component. * * @method Phaser.GameObjects.Components.Animation#update * @since 3.0.0 @@ -762,9 +752,10 @@ var Animation = new Class({ }, /** - * [description] + * Internal frame change handler. * * @method Phaser.GameObjects.Components.Animation#updateFrame + * @private * @since 3.0.0 * * @param {Phaser.Animations.AnimationFrame} animationFrame - [description] @@ -795,27 +786,37 @@ var Animation = new Class({ }, /** - * [description] + * Sets if the current Animation will yoyo when it reaches the end. + * A yoyo'ing animation will play through consecutively, and then reverse-play back to the start again. * - * @method Phaser.GameObjects.Components.Animation#yoyo - * @since 3.0.0 + * @method Phaser.GameObjects.Components.Animation#setYoYo + * @since 3.4.0 * - * @param {boolean} [value] - [description] + * @param {boolean} [value=false] - `true` if the animation should yoyo, `false` to not. * - * @return {(boolean|Phaser.GameObjects.GameObject)} [description] + * @return {Phaser.GameObjects.GameObject} The Game Object this Animation Component belongs to. */ - yoyo: function (value) + setYoYo: function (value) { - if (value === undefined) - { - return this._yoyo; - } - else - { - this._yoyo = value; + if (value === undefined) { value = false; } - return this; - } + this._yoyo = value; + + return this.parent; + }, + + /** + * Gets if the current Animation will yoyo when it reaches the end. + * A yoyo'ing animation will play through consecutively, and then reverse-play back to the start again. + * + * @method Phaser.GameObjects.Components.Animation#getYoYo + * @since 3.4.0 + * + * @return {boolean} `true` if the animation is set to yoyo, `false` if not. + */ + getYoYo: function () + { + return this._yoyo; }, /** @@ -826,7 +827,16 @@ var Animation = new Class({ */ destroy: function () { - // TODO + this.animationManager.off('remove', this.remove, this); + + this.animationManager = null; + this.parent = null; + + this.currentAnim = null; + this.currentFrame = null; + + this._callbackArgs = []; + this._updateParams = []; } });