Mirrors/phaser
2
0
Fork 0
mirror of https://github.com/photonstorm/phaser synced 2024-09-20 22:41:54 +00:00
Code Issues Projects Releases Packages Wiki Activity

Extensive Animation API changes to use milliseconds, improve docs and access to properties

Browse source
This commit is contained in:
Richard Davey 2018-04-04 16:13:45 +01:00
parent 552cfe3c5e
commit e734e7ef6b
3 changed files with 94 additions and 66 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
CHANGELOG.md
View file

@ -52,8 +52,9 @@ being passed to the simulation. The default value is 1 to remain consistent with
### 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:
We have refactored the Animation API to make it more consistent with the rest of Phaser 3 and to fix some issues. All of the following changes apply to the Animation Component:
* Animation durations, delays and repeatDelays are all now specified in milliseconds, not seconds like before. This makes them consistent with Tweens, Sounds and other parts of v3. You can still use the `frameRate` property to set the speed of an animation in frames per second.
* `delay` method has been removed.
* `setDelay` allows you to define the delay before playback begins.
* `getDelay` returns the animation playback delay value.
@ -81,13 +82,18 @@ We have refactored a large part of the Animation API to make it more consistent
* `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.
* `getYoyo` returns if the animation will yoyo or not.
* `setYoyo` 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.
* Changing the `yoyo` property on an Animation Component would have no effect as it only ever checked the global property, it now checks the local one properly allowing you to specify a `yoyo` on a per Game Object basis.
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
### Examples, Documentation and TypeScript
My thanks to the following for helping with the Phaser 3 Examples, Docs and TypeScript definitions, either by reporting errors, fixing them or helping author the docs:
@gabegordon @melissaelopez @samid737 @nbs @tgrajewski @pagesrichie @hexus @mbrickn @erd0s @icbat @Matthew-Herman

71
src/animations/Animation.js
View file

@ -15,11 +15,11 @@ var GetValue = require('../utils/object/GetValue');
* @property {string} type - A frame based animation (as opposed to a bone based animation)
* @property {JSONAnimationFrame[]} frames - [description]
* @property {integer} frameRate - The frame rate of playback in frames per second (default 24 if duration is null)
* @property {integer} duration - How long the animation should play for.
* @property {integer} duration - How long the animation should play for in milliseconds. If not given its derived from frameRate.
* @property {boolean} skipMissedFrames - Skip frames if the time lags, or always advanced anyway?
* @property {integer} delay - Delay before starting playback (in seconds)
* @property {integer} delay - Delay before starting playback. Value given in milliseconds.
* @property {integer} repeat - Number of times to repeat the animation (-1 for infinity)
* @property {integer} repeatDelay - Delay before the repeat starts (in seconds)
* @property {integer} repeatDelay - Delay before the animation repeats. Value given in milliseconds.
* @property {boolean} yoyo - Should the animation yoyo? (reverse back down to the start) before repeating?
* @property {boolean} showOnStart - Should sprite.visible = true when the animation starts to play?
* @property {boolean} hideOnComplete - Should sprite.visible = false when the animation finishes?
@ -41,14 +41,15 @@ var GetValue = require('../utils/object/GetValue');
* @property {AnimationFrameConfig[]} [frames] - [description]
* @property {string} [defaultTextureKey=null] - [description]
* @property {integer} [frameRate] - The frame rate of playback in frames per second (default 24 if duration is null)
* @property {integer} [duration] - How long the animation should play for.
* @property {integer} [duration] - How long the animation should play for in milliseconds. If not given its derived from frameRate.
* @property {boolean} [skipMissedFrames=true] - Skip frames if the time lags, or always advanced anyway?
* @property {integer} [delay=0] - Delay before starting playback (in seconds)
* @property {integer} [delay=0] - Delay before starting playback. Value given in milliseconds.
* @property {integer} [repeat=0] - Number of times to repeat the animation (-1 for infinity)
* @property {integer} [repeatDelay=0] - Delay before the repeat starts (in seconds)
* @property {integer} [repeatDelay=0] - Delay before the animation repeats. Value given in milliseconds.
* @property {boolean} [yoyo=false] - Should the animation yoyo? (reverse back down to the start) before repeating?
* @property {boolean} [showOnStart=false] - Should sprite.visible = true when the animation starts to play?
* @property {boolean} [hideOnComplete=false] - Should sprite.visible = false when the animation finishes?
* @property {*} [callbackScope] - [description]
* @property {(false|function)} [onStart=false] - [description]
* @property {Array.<*>} [onStartParams] - [description]
@ -137,8 +138,9 @@ var Animation = new Class({
this.frameRate = GetValue(config, 'frameRate', null);
/**
* How long the animation should play for.
* If frameRate is set it overrides this value otherwise frameRate is derived from duration.
* How long the animation should play for, in milliseconds.
* If the `frameRate` property has been set then it overrides this value,
* otherwise the `frameRate` is derived from `duration`.
*
* @name Phaser.Animations.Animation#duration
* @type {integer}
@ -150,25 +152,25 @@ var Animation = new Class({
{
// No duration or frameRate given, use default frameRate of 24fps
this.frameRate = 24;
this.duration = this.frameRate / this.frames.length;
this.duration = (this.frameRate / this.frames.length) * 1000;
}
else if (this.duration && this.frameRate === null)
{
// Duration given but no frameRate, so set the frameRate based on duration
// I.e. 12 frames in the animation, duration = 4 (4000 ms)
// So frameRate is 12 / 4 = 3 fps
this.frameRate = this.frames.length / this.duration;
// I.e. 12 frames in the animation, duration = 4000 ms
// So frameRate is 12 / (4000 / 1000) = 3 fps
this.frameRate = this.frames.length / (this.duration / 1000);
}
else
{
// frameRate given, derive duration from it (even if duration also specified)
// I.e. 15 frames in the animation, frameRate = 30 fps
// So duration is 15 / 30 = 0.5 (half a second)
this.duration = this.frames.length / this.frameRate;
// So duration is 15 / 30 = 0.5 * 1000 (half a second, or 500ms)
this.duration = (this.frames.length / this.frameRate) * 1000;
}
/**
* ms per frame (without including frame specific modifiers)
* How many ms per frame, not including frame specific modifiers.
*
* @name Phaser.Animations.Animation#msPerFrame
* @type {integer}
@ -187,7 +189,7 @@ var Animation = new Class({
this.skipMissedFrames = GetValue(config, 'skipMissedFrames', true);
/**
* Delay before starting playback (in seconds)
* The delay in ms before the playback will begin.
*
* @name Phaser.Animations.Animation#delay
* @type {integer}
@ -197,7 +199,7 @@ var Animation = new Class({
this.delay = GetValue(config, 'delay', 0);
/**
* Number of times to repeat the animation (-1 for infinity)
* Number of times to repeat the animation. Set to -1 to repeat forever.
*
* @name Phaser.Animations.Animation#repeat
* @type {integer}
@ -207,7 +209,7 @@ var Animation = new Class({
this.repeat = GetValue(config, 'repeat', 0);
/**
* Delay before the repeat starts (in seconds)
* The delay in ms before the a repeat playthrough starts.
*
* @name Phaser.Animations.Animation#repeatDelay
* @type {integer}
@ -329,7 +331,7 @@ var Animation = new Class({
this.onCompleteParams = GetValue(config, 'onCompleteParams', []);
/**
* Global pause, effects all Game Objects using this Animation instance
* Global pause. All Game Objects using this Animation instance are impacted by this property.
*
* @name Phaser.Animations.Animation#paused
* @type {boolean}
@ -342,10 +344,8 @@ var Animation = new Class({
this.manager.on('resumeall', this.resume.bind(this));
},
// Add frames to the end of the animation
/**
* [description]
* Add frames to the end of the animation.
*
* @method Phaser.Animations.Animation#addFrame
* @since 3.0.0
@ -359,10 +359,8 @@ var Animation = new Class({
return this.addFrameAt(this.frames.length, config);
},
// Add frame/s into the animation
/**
* [description]
* Add frame/s into the animation.
*
* @method Phaser.Animations.Animation#addFrameAt
* @since 3.0.0
@ -401,24 +399,25 @@ var Animation = new Class({
},
/**
* [description]
* Check if the given frame index is valid.
*
* @method Phaser.Animations.Animation#checkFrame
* @since 3.0.0
*
* @param {integer} index - [description]
* @param {integer} index - The index to be checked.
*
* @return {boolean} [description]
* @return {boolean} `true` if the index is valid, otherwise `false`.
*/
checkFrame: function (index)
{
return (index < this.frames.length);
return (index >= 0 && index < this.frames.length);
},
/**
* [description]
*
* @method Phaser.Animations.Animation#completeAnimation
* @protected
* @since 3.0.0
*
* @param {Phaser.GameObjects.Components.Animation} component - [description]
@ -437,6 +436,7 @@ var Animation = new Class({
* [description]
*
* @method Phaser.Animations.Animation#getFirstTick
* @protected
* @since 3.0.0
*
* @param {Phaser.GameObjects.Components.Animation} component - [description]
@ -452,7 +452,7 @@ var Animation = new Class({
if (includeDelay)
{
component.nextTick += (component._delay * 1000);
component.nextTick += component._delay;
}
},
@ -460,6 +460,7 @@ var Animation = new Class({
* [description]
*
* @method Phaser.Animations.Animation#getFrameAt
* @protected
* @since 3.0.0
*
* @param {integer} index - [description]
@ -594,9 +595,10 @@ var Animation = new Class({
},
/**
* [description]
* Loads the Animation values into the Animation Component.
*
* @method Phaser.Animations.Animation#load
* @private
* @since 3.0.0
*
* @param {Phaser.GameObjects.Components.Animation} component - [description]
@ -613,11 +615,12 @@ var Animation = new Class({
{
component.currentAnim = this;
component._timeScale = 1;
component.frameRate = this.frameRate;
component.duration = this.duration;
component.msPerFrame = this.msPerFrame;
component.skipMissedFrames = this.skipMissedFrames;
component._timeScale = 1;
component._delay = this.delay;
component._repeat = this.repeat;
component._repeatDelay = this.repeatDelay;
@ -648,7 +651,7 @@ var Animation = new Class({
// We're at the end of the animation
// Yoyo? (happens before repeat)
if (this.yoyo)
if (component.yoyo)
{
component.forward = false;
@ -766,7 +769,7 @@ var Animation = new Class({
{
component.pendingRepeat = true;
component.accumulator -= component.nextTick;
component.nextTick += (component._repeatDelay * 1000);
component.nextTick += component._repeatDelay;
}
else
{

75
src/gameobjects/components/Animation.js
View file

@ -98,9 +98,9 @@ var Animation = new Class({
this.frameRate = 0;
/**
* How long the animation should play for.
* How long the animation should play for, in milliseconds.
* If the `frameRate` property has been set then it overrides this value,
* otherwise frameRate is derived from `duration`.
* otherwise the `frameRate` is derived from `duration`.
*
* @name Phaser.GameObjects.Components.Animation#duration
* @type {number}
@ -130,7 +130,7 @@ var Animation = new Class({
this.skipMissedFrames = true;
/**
* A delay before starting playback, in seconds.
* A delay before starting playback, in milliseconds.
*
* @name Phaser.GameObjects.Components.Animation#_delay
* @type {number}
@ -152,7 +152,7 @@ var Animation = new Class({
this._repeat = 0;
/**
* Delay before the repeat starts, in seconds.
* Delay before the repeat starts, in milliseconds.
*
* @name Phaser.GameObjects.Components.Animation#_repeatDelay
* @type {number}
@ -267,12 +267,12 @@ var Animation = new Class({
},
/**
* Sets the amount of time, in seconds that the animation will be delayed before starting playback.
* Sets the amount of time, in milliseconds, that the animation will be delayed before starting playback.
*
* @method Phaser.GameObjects.Components.Animation#delay
* @since 3.4.0
*
* @param {number} [value=0] - The amount of time, in seconds, to wait before starting playback.
* @param {integer} [value=0] - The amount of time, in milliseconds, to wait before starting playback.
*
* @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
*/
@ -286,12 +286,12 @@ var Animation = new Class({
},
/**
* Gets the amount of time, in seconds that the animation will be delayed before starting playback.
* Gets the amount of time, in milliseconds 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.
* @return {integer} The amount of time, in milliseconds, the Animation will wait before starting playback.
*/
getDelay: function ()
{
@ -299,14 +299,14 @@ var Animation = new Class({
},
/**
* [description]
* Waits for the specified delay, in milliseconds, then starts playback of the requested animation.
*
* @method Phaser.GameObjects.Components.Animation#delayedPlay
* @since 3.0.0
*
* @param {number} delay - [description]
* @param {string} key - [description]
* @param {integer} startFrame - [description]
* @param {integer} delay - The delay, in milliseconds, to wait before starting the animation playing.
* @param {string} key - The key of the animation to play.
* @param {integer} [startFrame=0] - The frame of the animation to start from.
*
* @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
*/
@ -320,12 +320,12 @@ var Animation = new Class({
},
/**
* [description]
* Returns the key of the animation currently loaded into this component.
*
* @method Phaser.GameObjects.Components.Animation#getCurrentKey
* @since 3.0.0
*
* @return {string} [description]
* @return {string} The key of the Animation loaded into this component.
*/
getCurrentKey: function ()
{
@ -336,9 +336,10 @@ var Animation = new Class({
},
/**
* [description]
* Internal method used to load an animation into this component.
*
* @method Phaser.GameObjects.Components.Animation#load
* @protected
* @since 3.0.0
*
* @param {string} key - [description]
@ -362,12 +363,13 @@ var Animation = new Class({
},
/**
* [description]
* Pause the current animation and set the `isPlaying` property to `false`.
* You can optionally pause it at a specific frame.
*
* @method Phaser.GameObjects.Components.Animation#pause
* @since 3.0.0
*
* @param {Phaser.Animations.Animation} [atFrame] - [description]
* @param {Phaser.Animations.AnimationFrame} [atFrame] - An optional frame to set after pausing the animation.
*
* @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
*/
@ -389,12 +391,13 @@ var Animation = new Class({
},
/**
* [description]
* Resumes playback of a paused animation and sets the `isPlaying` property to `true`.
* You can optionally tell it to start playback from a specific frame.
*
* @method Phaser.GameObjects.Components.Animation#resume
* @since 3.0.0
*
* @param {Phaser.Animations.AnimationFrame} [fromFrame] - [description]
* @param {Phaser.Animations.AnimationFrame} [fromFrame] - An optional frame to set before restarting playback.
*
* @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
*/
@ -418,6 +421,7 @@ var Animation = new Class({
* `true` if the current animation is paused, otherwise `false`.
*
* @name Phaser.GameObjects.Components.Animation#isPaused
* @readOnly
* @type {boolean}
* @since 3.4.0
*/
@ -431,14 +435,14 @@ var Animation = new Class({
},
/**
* [description]
* Plays an Animation on the Game Object that owns this Animation Component.
*
* @method Phaser.GameObjects.Components.Animation#play
* @since 3.0.0
*
* @param {string} key - [description]
* @param {boolean} [ignoreIfPlaying=false] - [description]
* @param {integer} [startFrame=0] - [description]
* @param {string} key - The string-based key of the animation to play, as defined previously in the Animation Manager.
* @param {boolean} [ignoreIfPlaying=false] - If an animation is already playing then ignore this call.
* @param {integer} [startFrame=0] - Optionally start the animation playing from this frame index.
*
* @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
*/
@ -501,7 +505,22 @@ var Animation = new Class({
return p;
},
// TODO: Set progress
/**
* Takes a value between 0 and 1 and uses it to set how far this animation is through playback.
* Does not factor in repeats or yoyos.
*
* @method Phaser.GameObjects.Components.Animation#setProgress
* @todo
* @since 3.4.0
*
* @param {float} [value=0] - [description]
*
* @return {Phaser.GameObjects.GameObject} The Game Object that owns this Animation Component.
*/
setProgress: function (value)
{
return this.parent;
},
/**
* [description]
@ -789,14 +808,14 @@ var Animation = new Class({
* 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#setYoYo
* @method Phaser.GameObjects.Components.Animation#setYoyo
* @since 3.4.0
*
* @param {boolean} [value=false] - `true` if the animation should yoyo, `false` to not.
*
* @return {Phaser.GameObjects.GameObject} The Game Object this Animation Component belongs to.
*/
setYoYo: function (value)
setYoyo: function (value)
{
if (value === undefined) { value = false; }
@ -809,12 +828,12 @@ var Animation = new Class({
* 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
* @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 ()
getYoyo: function ()
{
return this._yoyo;
},