2018-02-12 16:01:20 +00:00
/ * *
* @ author Richard Davey < rich @ photonstorm . com >
2019-01-15 16:20:22 +00:00
* @ copyright 2019 Photon Storm Ltd .
2018-02-12 16:01:20 +00:00
* @ license { @ link https : //github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
* /
2017-06-28 21:19:41 +00:00
var Class = require ( '../utils/Class' ) ;
var GetFastValue = require ( '../utils/object/GetFastValue' ) ;
2018-02-10 02:31:42 +00:00
/ * *
* @ classdesc
2018-10-19 11:32:43 +00:00
* A Timer Event represents a delayed function call . It 's managed by a Scene' s { @ link Clock } and will call its function after a set amount of time has passed . The Timer Event can optionally repeat - i . e . call its function multiple times before finishing , or loop indefinitely .
*
* Because it 's managed by a Clock, a Timer Event is based on game time, will be affected by its Clock' s time scale , and will pause if its Clock pauses .
2018-02-10 02:31:42 +00:00
*
* @ class TimerEvent
2018-10-10 09:49:13 +00:00
* @ memberof Phaser . Time
2018-02-10 02:31:42 +00:00
* @ constructor
* @ since 3.0 . 0
*
2019-02-13 16:06:00 +00:00
* @ param { Phaser . Time . Types . TimerEventConfig } config - The configuration for the Timer Event , including its delay and callback .
2018-02-10 02:31:42 +00:00
* /
2017-06-28 21:19:41 +00:00
var TimerEvent = new Class ( {
initialize :
function TimerEvent ( config )
2017-06-28 16:39:40 +00:00
{
2017-06-28 21:19:41 +00:00
/ * *
2018-02-10 02:31:42 +00:00
* The delay in ms at which this TimerEvent fires .
*
* @ name Phaser . Time . TimerEvent # delay
* @ type { number }
* @ default 0
2018-10-09 12:40:00 +00:00
* @ readonly
2018-02-10 02:31:42 +00:00
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . delay = 0 ;
/ * *
2018-02-10 02:31:42 +00:00
* The total number of times this TimerEvent will repeat before finishing .
*
* @ name Phaser . Time . TimerEvent # repeat
* @ type { number }
* @ default 0
2018-10-09 12:40:00 +00:00
* @ readonly
2018-02-10 02:31:42 +00:00
* @ since 3.0 . 0
* /
2017-06-29 13:05:49 +00:00
this . repeat = 0 ;
/ * *
2018-02-10 02:31:42 +00:00
* If repeating this contains the current repeat count .
*
* @ name Phaser . Time . TimerEvent # repeatCount
* @ type { number }
* @ default 0
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . repeatCount = 0 ;
/ * *
2018-02-10 02:31:42 +00:00
* True if this TimerEvent loops , otherwise false .
*
* @ name Phaser . Time . TimerEvent # loop
* @ type { boolean }
* @ default false
2018-10-09 12:40:00 +00:00
* @ readonly
2018-02-10 02:31:42 +00:00
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . loop = false ;
/ * *
2018-02-10 02:31:42 +00:00
* The callback that will be called when the TimerEvent occurs .
*
* @ name Phaser . Time . TimerEvent # callback
* @ type { function }
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . callback ;
2017-06-28 16:39:40 +00:00
2017-06-28 21:19:41 +00:00
/ * *
2018-02-10 02:31:42 +00:00
* The scope in which the callback will be called .
*
* @ name Phaser . Time . TimerEvent # callbackScope
* @ type { object }
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . callbackScope ;
2017-06-28 16:39:40 +00:00
2017-06-28 21:19:41 +00:00
/ * *
2018-02-10 02:31:42 +00:00
* Additional arguments to be passed to the callback .
*
* @ name Phaser . Time . TimerEvent # args
* @ type { array }
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . args ;
2017-06-28 16:17:54 +00:00
2018-02-10 02:31:42 +00:00
/ * *
* Scale the time causing this TimerEvent to update .
*
* @ name Phaser . Time . TimerEvent # timeScale
* @ type { number }
* @ default 1
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . timeScale = 1 ;
2018-02-10 02:31:42 +00:00
/ * *
* Start this many MS into the elapsed ( useful if you want a long duration with repeat , but for the first loop to fire quickly )
*
* @ name Phaser . Time . TimerEvent # startAt
* @ type { number }
* @ default 0
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . startAt = 0 ;
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* The time in milliseconds which has elapsed since the Timer Event ' s creation .
*
* This value is local for the Timer Event and is relative to its Clock . As such , it 's influenced by the Clock' s time scale and paused state , the Timer Event 's initial {@link #startAt} property, and the Timer Event' s { @ link # timeScale } and { @ link # paused } state .
2018-02-10 02:31:42 +00:00
*
* @ name Phaser . Time . TimerEvent # elapsed
* @ type { number }
* @ default 0
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . elapsed = 0 ;
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Whether or not this timer is paused .
2018-02-10 02:31:42 +00:00
*
* @ name Phaser . Time . TimerEvent # paused
* @ type { boolean }
* @ default false
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . paused = false ;
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Whether the Timer Event ' s function has been called .
*
* When the Timer Event fires , this property will be set to ` true ` before the callback function is invoked and will be reset immediately afterward if the Timer Event should repeat . The value of this property does not directly influence whether the Timer Event will be removed from its Clock , but can prevent it from firing .
2018-02-10 02:31:42 +00:00
*
* @ name Phaser . Time . TimerEvent # hasDispatched
* @ type { boolean }
* @ default false
* @ since 3.0 . 0
* /
2017-06-28 21:19:41 +00:00
this . hasDispatched = false ;
this . reset ( config ) ;
} ,
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Completely reinitializes the Timer Event , regardless of its current state , according to a configuration object .
2018-02-10 02:31:42 +00:00
*
* @ method Phaser . Time . TimerEvent # reset
* @ since 3.0 . 0
*
2019-02-13 16:06:00 +00:00
* @ param { Phaser . Time . Types . TimerEventConfig } config - The new state for the Timer Event .
2018-02-10 02:31:42 +00:00
*
* @ return { Phaser . Time . TimerEvent } This TimerEvent object .
* /
2017-06-28 21:19:41 +00:00
reset : function ( config )
{
this . delay = GetFastValue ( config , 'delay' , 0 ) ;
2017-06-29 13:05:49 +00:00
// Can also be set to -1 for an infinite loop (same as setting loop: true)
this . repeat = GetFastValue ( config , 'repeat' , 0 ) ;
2017-06-28 21:19:41 +00:00
this . loop = GetFastValue ( config , 'loop' , false ) ;
this . callback = GetFastValue ( config , 'callback' , undefined ) ;
this . callbackScope = GetFastValue ( config , 'callbackScope' , this . callback ) ;
this . args = GetFastValue ( config , 'args' , [ ] ) ;
this . timeScale = GetFastValue ( config , 'timeScale' , 1 ) ;
this . startAt = GetFastValue ( config , 'startAt' , 0 ) ;
this . paused = GetFastValue ( config , 'paused' , false ) ;
2018-01-23 15:34:33 +00:00
this . elapsed = this . startAt ;
2017-06-28 21:19:41 +00:00
this . hasDispatched = false ;
2017-06-29 13:05:49 +00:00
this . repeatCount = ( this . repeat === - 1 || this . loop ) ? 999999999999 : this . repeat ;
2017-06-28 21:19:41 +00:00
return this ;
} ,
2017-06-28 16:17:54 +00:00
2018-02-10 02:31:42 +00:00
/ * *
* Gets the progress of the current iteration , not factoring in repeats .
*
* @ method Phaser . Time . TimerEvent # getProgress
* @ since 3.0 . 0
*
2018-10-19 11:32:43 +00:00
* @ return { number } A number between 0 and 1 representing the current progress .
2018-02-10 02:31:42 +00:00
* /
2017-06-28 16:17:54 +00:00
getProgress : function ( )
{
return ( this . elapsed / this . delay ) ;
2017-06-28 16:39:40 +00:00
} ,
2018-02-10 02:31:42 +00:00
/ * *
* Gets the progress of the timer overall , factoring in repeats .
*
* @ method Phaser . Time . TimerEvent # getOverallProgress
* @ since 3.0 . 0
*
2018-10-19 11:32:43 +00:00
* @ return { number } The overall progress of the Timer Event , between 0 and 1.
2018-02-10 02:31:42 +00:00
* /
2017-06-29 13:05:49 +00:00
getOverallProgress : function ( )
{
if ( this . repeat > 0 )
{
var totalDuration = this . delay + ( this . delay * this . repeat ) ;
var totalElapsed = this . elapsed + ( this . delay * ( this . repeat - this . repeatCount ) ) ;
return ( totalElapsed / totalDuration ) ;
}
else
{
return this . getProgress ( ) ;
}
} ,
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Returns the number of times this Timer Event will repeat before finishing .
*
* This should not be confused with the number of times the Timer Event will fire before finishing . A return value of 0 doesn ' t indicate that the Timer Event has finished running - it indicates that it will not repeat after the next time it fires .
2018-02-10 02:31:42 +00:00
*
* @ method Phaser . Time . TimerEvent # getRepeatCount
* @ since 3.0 . 0
*
2018-10-19 11:32:43 +00:00
* @ return { number } How many times the Timer Event will repeat .
2018-02-10 02:31:42 +00:00
* /
2017-06-29 13:05:49 +00:00
getRepeatCount : function ( )
{
return this . repeatCount ;
} ,
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Returns the local elapsed time for the current iteration of the Timer Event .
2018-02-10 02:31:42 +00:00
*
* @ method Phaser . Time . TimerEvent # getElapsed
* @ since 3.0 . 0
*
2018-10-19 11:32:43 +00:00
* @ return { number } The local elapsed time in milliseconds .
2018-02-10 02:31:42 +00:00
* /
2017-06-28 21:19:41 +00:00
getElapsed : function ( )
2017-06-28 16:39:40 +00:00
{
2017-06-28 21:19:41 +00:00
return this . elapsed ;
2017-06-28 16:39:40 +00:00
} ,
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Returns the local elapsed time for the current iteration of the Timer Event in seconds .
2018-02-10 02:31:42 +00:00
*
* @ method Phaser . Time . TimerEvent # getElapsedSeconds
* @ since 3.0 . 0
*
2018-10-19 11:32:43 +00:00
* @ return { number } The local elapsed time in seconds .
2018-02-10 02:31:42 +00:00
* /
2017-06-28 21:19:41 +00:00
getElapsedSeconds : function ( )
2017-06-28 16:39:40 +00:00
{
2017-06-28 21:19:41 +00:00
return this . elapsed * 0.001 ;
2017-06-28 16:39:40 +00:00
} ,
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Forces the Timer Event to immediately expire , thus scheduling its removal in the next frame .
2018-02-10 02:31:42 +00:00
*
* @ method Phaser . Time . TimerEvent # remove
* @ since 3.0 . 0
*
2019-01-25 03:00:40 +00:00
* @ param { boolean } [ dispatchCallback ] - If ` true ` ( by default ` false ` ) , the function of the Timer Event will be called before its removal from its Clock .
2018-02-10 02:31:42 +00:00
* /
2017-06-28 16:39:40 +00:00
remove : function ( dispatchCallback )
{
if ( dispatchCallback === undefined ) { dispatchCallback = false ; }
this . elapsed = this . delay ;
2018-03-09 10:47:45 +00:00
this . hasDispatched = ! dispatchCallback ;
2017-06-28 16:39:40 +00:00
this . repeatCount = 0 ;
} ,
2018-02-10 02:31:42 +00:00
/ * *
2018-10-19 11:32:43 +00:00
* Destroys all object references in the Timer Event , i . e . its callback , scope , and arguments .
*
* Normally , this method is only called by the Clock when it shuts down . As such , it doesn 't stop the Timer Event. If called manually, the Timer Event will still be updated by the Clock, but it won' t do anything when it fires .
2018-02-10 02:31:42 +00:00
*
* @ method Phaser . Time . TimerEvent # destroy
* @ since 3.0 . 0
* /
2017-06-28 16:39:40 +00:00
destroy : function ( )
{
this . callback = undefined ;
this . callbackScope = undefined ;
2017-11-06 04:49:57 +00:00
this . args = [ ] ;
2017-06-28 16:17:54 +00:00
}
2017-06-28 21:19:41 +00:00
} ) ;
2017-06-28 16:17:54 +00:00
module . exports = TimerEvent ;