EventTimer¶

Overview¶

Abstraction for timed-event series that helps with variable frame-rates. Useful for things that need to happen at a specific rate real-time regardless of the frame-rate.

An EventTimer is created with a specific event "model" that determines when events occur, and a callback that will be triggered for each event (with its time elapsed since it should have occurred). Thus, each callback basically says: - "an event happened <timeElapsed> ago"

To have the EventTimer step forward in time (firing callbacks for every event that would have occurred over that time frame, if any), call step( realTimeElapsed ).

For example, create a timer with a constant rate that will fire events every 1 time units:

var timer = new phet.phetCore.EventTimer( new phetCore.ConstantEventModel( 1 ), function( timeElapsed ) { console.log( 'event with timeElapsed: ' + timeElapsed ); } );

Stepping once for 1.5 time units will fire once (0.5 seconds since the "end" of the step), and will be 0.5 seconds from the next step:

timer.step( 1.5 ); > event with timeElapsed: 0.5

The 0.5 above is because after 1.5 seconds of time, the event will have happened 0.5 seconds ago:

      step 1.5

|------------------------>| | * | * * <- constant time of 1 between each event | <--------| 0.5 seconds past the event now

Stepping for a longer time will result in more events:

timer.step( 6 ); > event with timeElapsed: 5.5 > event with timeElapsed: 4.5 > event with timeElapsed: 3.5 > event with timeElapsed: 2.5 > event with timeElapsed: 1.5 > event with timeElapsed: 0.5

  step 1.5                                  step 6                                 step 0   step 1.5

|---------------->|---------------------------------------------------------------------->|---------------->| | * * * * * * * * * | <-----| <-----------------------------------------------------------------| <-----------| | 0.5 5.5 <-----------------------------------------------------| 1 0 | ^ ^ 4.5 <-----------------------------------------| event at | | | 3.5 <-----------------------------| current | | | 2.5 <-----------------| time | callback( t ) called, etc. 1.5 <-----| |

A step with zero time will trigger no events:

timer.step( 0 );

The timer will fire an event once it reaches the exact point in time:

timer.step( 1.5 ); > event with timeElapsed: 1 > event with timeElapsed: 0

NOTE: If your timer callbacks create model objects that would also get stepped forward, make sure to step forward objects before calling eventTimer.step(), so that objects don't get stepped twice. Usually the callback will have: - var modelElement = new ModelElement(); - modelElement.step( callbackTimeElapsed ); And you don't want to apply step( dt ) to it directly afterwards.

@author Jonathan Olson <jonathan.olson@colorado.edu>

Class EventTimer¶

import { EventTimer } from 'scenerystack/phet-core';

Constructor¶

new EventTimer( eventModel : { getPeriodBeforeNextEvent: () => number }, eventCallback : ( timeElapsed: number ) => void )¶

Instance Methods¶

step( dt : number )¶

Steps the timer forward by a certain amount of time. This may cause 0 or more events to actually occur.

getRatio() : number¶

Returns how far we are to the next event firing (where 0 is an event "just" fired, and 1 is the next event firing).

@returns In the range [0,1). Is inclusive for 0, but exclusive for 1.

Source Code¶

See the source for EventTimer.ts in the phet-core repository.