Page Content
hide
TimeSimmer
When creating simulations, and especially when testing or demoing apps that simulate events over time, you often need to speed up or slow down time. You may even need to slow it up or speed it down multiple times during a session – so just multiplying the elapsed time by some constant isn’t going to work. TimeSimmer runs its own clock that you can set both the tick rate (how often it updates the time), and the rate (how fast it runs compared to real time) on the fly, and still keep track of the current time.
What is timesimmer ?
A sim time simulation that supports
- adjustable rate and tickrate
- events
- cycling within a fixed period
- resetting of rates within a period
Timesimmer will create a continuous timer that runs at any rate x real time. Because it keeps a separate clock going, you can change the rate while it’s running without affecting elapsed time that has gone before.
An example use case might be
- your app runs a simulation at 60 * real time – so 1 hour passes in 1 minute
- it also provides a slider to adjust the rate
- the timer needs to remember how long has passed at every rate, so it’s not just a matter of multiplying the elapsed time ny the new rate.
Installation
If you are using Node, or webpack you can get the code off npm
yarn add timesimmer -- or -- npm install timesimmer
or you can get the source code from github to host yourself – you’ll only need src/timesimmer.js
Usage
const TimeSimmer = require('timesimmer');
You can use the default options or add options on the constructor such as
const s = new TimeSimmer({
// speed up time so 1 second = 10 minutes
rate: 60 * 10,
// tick every second
tickRate: 1000,
// when the timer should start from
startedAt: new Date(2001, 0,1).getTime(),
// restart time every hour
cycle: 60 * 60 * 1000
})
Cycling
Normally time is counted from the startedAt option (or now by default). For some use cases, it’s possible that the time cycles within a given period (for example a weekly schedule), so you can use the cycle option to say at what point to reset the time back to the startedAt value
Options
Most options can be applied when the timer is initialized, or set while the timer is running
| option | default | purpose |
|---|---|---|
| rate | 60 | Factor for how much to speed up time by – so 60 makes a minute pass in a second |
| tickRate | 1000 | How often (ms) to update the simulated time. This also controls how often the tick event is fired | |
| startedAt | now | The time to start the timer from expressed as a time -eg new Date().getTime() |
| immediate | true | whether to start the timer immediately on instanciation |
| cycle | 0 | If non-zero, the timer will be restarted to startedAt on the tick event that detects these number of ms have passed |
| carryForwardOnCycle | false | If cycling is happening, if the cycle time isnt a multiple of the rate, you might have some excess time on a tick. Normally a recycle will reset the timer to 0, but you can carry forward any excess time by setting this value |
Events
Events are checked for triggering at every tick event. Adding events like this adds to existing events – so multiple listeners can be activated by a single event.
s.on("tick", (simPack) => {
console.log(`tick number ${simPack.ticker} was triggered at sim time ${simPack.date.toString()}`)
});
or
s.on("cycle", (simPack) => {
console.log(`recycled to sim time ${simPack.date.toString()}`)
});
To clear all registered events for a given eventName use .off, eg..
s.off("cycle");
Event list
| eventName | triggered on |
|---|---|
| tick | every tickRate ms |
| cycle | there’s been a reset of the timer back to start. A tick event will also be fired just before a recycle |
Simpack
A simPack is a collection of useful stuff about the current state of the sim, as is retured as an event payload when one is triggered. It can also be retrieved as a property
const p = s.simPack;
The contents of a simPack are
| property | content |
|---|---|
| time | the current sim time in ms |
| rate | the current rate |
| ticker | how many times there’s been a tick event. This is reset to 0 on a cycle event |
| startedAt | when the current cycle started |
| cycle | the current cycle option valued |
| kickoff | the original startedAt time. It will be equal to startedAt if cycle is 0 |
| tickRate | how often the time is updated in ms |
| eventName | the event |
| allTime | the sim time passed since instanciation |
| realTimeStartedAt | when it actually started |
| realTimeElapsed | how long its been running for in real time |
| carryFowardOnCycle | whether to carry forward any excess sim time when a recycle happens |
| date | the sim time as a date |
Properties
A simPack (described earlier) is a collection of properties returned in a single object. Most properties can also be set or get individually, for example
s.rate = 20 console.log(s.date)
Methods
| method | content | returns |
|---|---|---|
| stop () | stop (pause) the timer | self |
| start () | (re) start the timer | self |
| on(eventName: string, listener: function) | add a listener to be executed when a given eventName triggers | self |
| off(eventName: string) | remove all listeners for the given eventName | self |
| ms(conversionName: string, [value=1]) | convert to and from ms | number |
Convenience time conversion
Since there might be the need for time conversions in your app, a convenience ms to to other measures are provided as a static method, but also accessible from an instance.
For example to get one day in ms
s.ms ('days')
or 10 hours in ms
s.ms ('hours', 10)
or can also be called as a static method
TimeSimmer.ms('weeks', 3)
To convert back the other way, just stick ‘ms’ in front of the conversion name. For example to convert 200000ms to weeks.
ms('msWeeks', 200000)
It’s not rocket science, but it does help to document when instead of defining a simmer like this
const s = new TimeSimmer({
// speed up time to run at 100 times normal speed
rate: 100,
// tick every second
tickRate: 1000,
// restart time every 2 hours
cycle: 60 * 60 * 1000 * 2
})
You can do this
const ms = {TimeSimmer}
const s = new TimeSimmer({
rate: 100,
tickRate: ms('seconds'),
cycle: ms('hours', 2)
})
and you can interpret results like this
const hours = ms('msHours', s.time)
Here’s the full list of conversions
| conversion name | returns |
|---|---|
| seconds | ms |
| minutes | ms |
| hours | ms |
| days | ms |
| weeks | ms |
| msSeconds | seconds |
| msMinutes | minutes |
| msHours | hours |
| msDays | days |
| msWeeks | weeks |
Examples
See the test.js in the repo for many examples
Simple time speed up
This example makes an hour pass in a second, and you can use the ticker event to update a simulated clock every 500ms, where the start date is now
set up the timer
const s = new TimeSimmer({
rate: 60 * 60,
tickRate: 500
});
add a tick event
s.on("tick", simPack => {
updateYourUiClock(simPack.date)
})
Recycler
This example could be used to re-use a hourly schedule. At each interval of the time specified in the cycle option, the entire timer will reset. Here, a minute will pass in a second, and the timer will reset every hour, and tick every 2 seconds.
set up the timer
const ms = {TimeSimmer}
const s = new TimeSimmer({
rate: 60,
tickRate: ms("seconds", 2)
cycle: ms ("hours"),
startedAt: new Date(2001, 11, 17, 8, 0, 0).getTime()
});
add tick events
s.on("tick", simPack => {
// will fire every 2 secs, and 2 minutes will have passed
reuseYourSchedule(simPack.date)
})
s.on("cycle", ({date})=> {
console.log(`the timer restarted back to ${date.toString()})
})
Examples
Here’s a simple sim time clock on codepen using Vue and Vuex
See the Pen
timesimmer by bruce mcpherson (@brucemcpherson)
on CodePen.
Repos
See also qottle.