Real-time vs. Game time vs. Physics time, various timing issues

There are various issues with timings that may lead to game-breaking bugs, particularly on slow systems. Parts of these problems are due to the fact there is no clear distinction between real-time, game-time and "physics-time" in Phaser.

I have made a small test program to illustrate this:

BasicGame.Game.prototype = {

    preload: function () {
        this.load.image('realTime', 'target.png');
        this.load.image('green', 'green.png');
        this.load.image('timer', 'timer.png');
        this.load.image('physic', 'cursor.png');
    },

    create: function () {

        // Choosing a deltaCap > 1/60 allow to emulate slow systems that are
        // not able to run at 1/deltaCap fps. 
        this.time.deltaCap = 1/120.;

        // The speed of the sprites, in px/s.
        this.speed = 100;

        // The refresh delay of timerSprite.
        this.timerTime = 15;

        // Position of realTimeSprite is computed from Time.totalElapsedSeconds().
        this.realTimeSprite = this.add.sprite(50, this.game.height / 2, 'realTime');
        this.realTimeSprite.anchor.set(.5, .5);

        // Position of accumSprite is updated according to Time.elapsed.
        this.accumSprite = this.add.sprite(50, this.game.height / 2, 'green');
        this.accumSprite.anchor.set(.5, .5);
        this.accum = 0;

        // Position of timerSprite is updated regularily by a timer.
        this.timerSprite = this.add.sprite(50, this.game.height / 2, 'timer');
        this.timerSprite.anchor.set(.5, .5);
        this.time.events.loop(this.timerTime, function() {
            this.timerSprite.x += this.speed * this.timerTime / 1000.;
        }, this);

        // Position of physicSprite is updated by Arcade with a constant speed.
        this.physicSprite = this.add.sprite(50, this.game.height / 2, 'physic');
        this.physicSprite.anchor.set(.5, .5);
        this.game.physics.arcade.enable(this.physicSprite);
        this.physicSprite.body.velocity.x = this.speed;

        console.log("plop");

    },

    update: function () {

        this.realTimeSprite.x = 50 + this.time.totalElapsedSeconds() * this.speed;

        this.accum += this.time.elapsed;
        this.accumSprite.x = 50 + this.accum/1000. * this.speed;

    },

};

You can test it there: http://www.draklia.net/phaser-bug-test/ . In this example, 4 originally overlapping sprites are moving right at a constant speed (here, 100px/s). They differ by the way their position are updated:

realTimeSprite (white) has its position updated in function of the real-time, obtained by Time.totalElapsedSeconds().
accumSprite (green) is like realTimeSprite, but accumulates time from Time.elapsed instead of taking it from Time.totalElapsedSeconds().
timerSprite (blue) is moved by a constant distance every time a timer is triggered.
physicSprite (red) is moved by arcade physics. This is the same than accumulating time from Time.physicsElapsed.

All these methods lead to different results. Let's take a closer look:

realTimeSprite move according to real-time (independently of performances), including during pauses.
accumSprite is like realTimeSprite, but do not move during pauses as time does not accumulate.
timerSprite follows accumSprite closely as long as only one "tick" occurs per frame. If the delay is too low (say 10ms) or a slowdown occurs, then some updates may be dropped. For example, if we use a timer to send bullets of some rapid-firing weapon, we are capped to 1 bullet per frame. So, on slow computers or if the player's system is suddenly busy, the weapon may become less effective.
physicSprite follows accumSprite as long as frames are under deltaCap. On slow computer, this mean that all items controlled by physics will be slower than the rest. For example, I made a game where a bridge over some lava crumbled tile-by-tile. With the crumbling controlled by a timer and the player by the physics, the game is simply unbeatable on slow system: the bridge collapses faster that the player moves. Increasing deltaCap may lead the player to go through wall, so this is not an option.

In the remaining, I assume that not using deltaCap is not an option in most games, because in case of small freezes characters may easily go through walls or encounter some other bugs (0.5/1s freezes do occur in web browser).

There are 3 problems:

The main problem is that "game-time" is not well-defined in phaser. Is it real-time without the pauses ? Is it the "physics" time that is slower than real-time when a frame takes more time than deltaCap ? I admit I am a bit confused about the difference between Time.elapsed and Time.physicsElapsed. Everything except physics (e.g. timers) seems to follow Time.elapsed, but I hardly see a case where one would expect to have physics going at a different pace than the rest of the game.
Timers can only be triggered once per frame, which may be a problem in case of slowdowns. Yet, users may not expect that a timer trigger several times per frame, so it may be useless or worst, lead to bugs. It may still be useful as an option (disabled by default) to allow a timer to be triggered several time in one frame when required.
I think it is a good thing that we can access both real-time and game-time. However it is not always clear in the documentation which function reference which time. For instance, it is not clear that totalElapsedSeconds measure real-time. (By the way, I wonder about the other 'elapsed...' methods.)

I believe that time methods should fall in two categories: real-time (time goes by at a steady speed, including during pauses) and game-time (can be slower than real-time, "skip" pauses, may be scaled for funny effects like slow-motion). Given the current state of Phaser, it would make sense to me that game-time is the actual "physics-time".

A solution would be to split time-related stuff in two sets of objects, those working in real-time and the others. This way, users could access to game.realtime or game.gametime depending on their needs, and still have game.time for backward compatibility. Practically, gametime and realtime may share the same class but would not be 'fed' the same way, thus reducing code duplication. It would make the whole timing thing more consistent and explicit.

A more long-term goal may be to allow the game loop to use a fixed time step (with interpolation for rendering). It would be anyway useful for advanced physics engines like P2, which typically require a fixed time step for stability. The solution exposed above is a first step in this direction.

I just pushed a suggestion of fix. Feedback welcome.

There are the new things:

class Clock:

Represent some time reference.
Allow to compare times expressed in the same reference.
Has it's own events timer and timer list.
Has a timeScale parameter that allow to slow or accelerate time.

class Time:

Added Time.clock and Time.realTimeClock, two Clock object that represent respectively the main clock (in-game time) and the real-time clock (do not stop on pauses or slow-down).

class Timer:

Timers constructor now takes a third parameter clock and use it as it's time reference. Thus, we can create timers bound to various clocks depending on the need. A timer bound to Time.realTimeClock will follow real-time, where a timer bound to Time.clock will trigger events with respect to in-game time.
Consequence of the previous modification, Timer.update no longer takes the time as an argument. It rather ask the time to its clock object.

And some notes / things to do to clean the interface when backward-compatibility can be broke:

class Clock:

NOTE: We could make Clocks hierarchical. The master (root) clock would represent in-game time, child clocks could represent other time references (with more pauses or some time-scale). Updating a clock would automatically update it's children or the other way around ?

class Time:

TODO: Likely a lot of clean-up to do: there are a lot of variables that reference time or durations (Time.time, Time.now, Time.elapsed, Time.physicsElapsed, ...) which may or may not reference the same time-scale. This is a mess. Ideally, all this should reference only be expressed with respect to the main clock (Time.clock) or be private.
TODO: In the continuation of the previous TODO, Time.events and Time._timers should only be a reference to Time.clock.events and Time.clock._timers. Right now, it is still the old ones that reference a clock that does not slow down (except in case of spike-dislike) and stops during pauses. All related methods (create, removeAll, etc.) should be updated too.
NOTE: This should be the only class that does spike-dislike to compute Time.elapsed. All clocks (except realTimeClock) should be updated according to Time.elapsed thus avoiding spikes.

class Timer:

NOTE: We should allow stand-alone timers: creating and updating timers can be done directly by the user. This can be useful if the user need to control precisely when the callback is triggered in the event loop (See note far below).
TODO: Remove spike-dislike: this should be handled by the Time object.
TODO: Remove the pause-resume stuff: On pause, the Clock stops moving forward, thus implicitly pausing all timers. If pausing individual timers is required, what should it do:
1. (most likely useful) Stops counting time. E.g. if some event should have been triggered 1s after the moment the timer is paused, it will trigger 1s after the timer is resumed.
2. (least likely useful) Stops triggering events, but continue counting time. E.g. if a one-shot event should have been triggered 1s after the moment the timer is paused and the timer is resumed after more than 1s of pause, the event is never triggered.
Anyway, the way timers pause is implemented right now is a bug nest. If some code does pause -> pause -> resume -> resume, the timer is resumed at the first call to resume, which is likely not what is intended. It seems to be the reason why there is a pause and a _pause function, but the whole thing does not seems too robust (I have seen some bug reports about it recently). A much better solution would be to have a pause counter which is incremented when pause is called and decremented when resume is called. The game would be running when pause === 0.

Other things:

TODO: Ideally, all things that work with time (e.g. animations) should no longer use Game.time but a (customizable) Clock (that defaults to Time.clock).
NOTE: timers created by Clock.create or Time.create are updated far before anything else: before preUpdates and independently of Game._paused. Open question: could this lead to bugs ? I don't know exactly what do preUpdate functions, but can we assume safely that the user will not do something in the event callbacks that should really be done after preUpdates ?

Interesting approach and if it works as advertised would possibly fix a lot of the timing. Do you have a copy of your demo running where the issues are fixed with this new clock solution?

Agreed, I too would like to see some test cases showing the improvements. I did take a look at your fork but I couldn't see anything that would change the way in which the physics delta timer was calculated at all (so surely the issues you outline above would remain in that one respect?), but that may have been one of your TODO items.

There is only one concept of Time in Phaser: real world time (i.e. the time specified by the device) and everything is based on this (Timers, tween durations, sound markers, animation frame rates, etc). The physics delta timer is simply a real-time based delta with optional cap, nothing more.

In order for swapping to Game Time to be an effective change all of these things would need to be modified to allow them to use custom Clocks. This isn't a problem as such, it's just a huge amount of API modifying work. Major point release level changes imho.

Here are some issues that I'd be curious to know how you'd handle (I'm not trying to catch you out or anything, I'd just like to know how you'd deal with them):

Huge time spikes with no prior warning. I.e. the browser RAF has stalled (maybe the window was minimised) but no window event was received. When the game is next updated you've got a huge elapsed value but all the while the game thought it wasn't paused anyway. This could lead to stacks of backlogged Timer events wanting to fire at once, animation frames, etc.
On the roadmap are parallel running States. So being able to start another State while having the current one still running. In order to facilitate this we're looking at each state having its own tween manager, etc. It seems logical it could have its own Clock too?
Smoothing out the physics delta timer. This value could be interpolated rather than derived like it is currently, but it would still need a cap and knowing what to set the cap is tricky and forces you to make assumptions about the target platform.

Unless the physics delta was linked to a Game Clock I can't see how you'd ever avoid your "lava" situation? I think the issue is deeper than this though, I think what you'd need is to have Game Clock level control over the physics step itself, otherwise surely you've got the same penetration issues as with the current set-up? (just in a slightly different time frame). Seeing as Arcade Physics doesn't work on a step basis I reckon you're dealing with a fundamental change to how its values are derived (and/or implementing a step), which may not be worth the effort involved given how primitive it is anyway?

Events and callbacks can happen at /any/ time, and I've seen users do things in callbacks (utterly out of sync with the game loop) that made me question my own sanity. This could happen before the master Clock update or mid-way while running through the list of active Timers (which in itself could adjust that list, add to it, remove from it, pause the game, etc).

I did not change the way physics time is calculated. The purpose of my modifications is to provide a consistent timing system that allow to work easily with various time references. The main clock (game.time.clock) follows the "physic time" computed using 'deltaCap'. Working with it ensure that everything is synchronized on this reference (objects updated with physics, timers and the clock time). As user can make it's own clocks, or we can add state-wise clocks (see below), it effectively adds to phaser different concepts of time.

There is an updated version of the demo of my previous post: http://www.draklia.net/phaser-timing-test/ . The top line is the same as the previous demo, with the same problems (because I tried to keep backward-compatibility). The bottom line is the same, but using the new 'game.time.clock' instead of 'game.time'. As it is a consistent time reference everything stay in sync. The only remaining problem occur if a timer as a delay smaller than 'deltaCap' because event can be triggered only once per frame.

Updating Phaser to use custom clock anywhere time is required would indeed require major API refactoring and I agree this should wait for a major point release. However, the modification I made are (hopefully) backward-compatible and can already be used in games to solve some timing issues, like the lava bridge problem (see demo).

About the points you mention:

Huge time spikes are handled as before, with the spike-dislike trick: if elapsed time is over some threshold (1s by default), we consider it as being 1/60 s. The difference is that spike-dislike is performed only once in Time.update() (line 253) to correct 'elapsed' if required, then 'elapsed' is used to update the clock (and the clock is used to update the timers). This mean the spike-dislike need to be done only once in the class Time and not everywhere time is required (so, the spike-dislike in timer can be removed).
State-wise clock makes perfect sense. In facts, users should probably only uses this kind of clock, unless they have a really good reason to do otherwise. We could easily add an attribute 'clock' to states (likely in StateManager.add, unless we decide to add logic to Phaser.State) and update it just before the call to 'state.update()' in 'Game.update()' (unless preUpdates need an up-to-date time...). A nice side effect is that clock's timers events would be triggered just before the state update, which makes much more sense than "before anything else".

All this would make the use of several states much more practical. An example: suppose we have a game with an inventory and that opening the inventory pause the game. We can have a state for the game and an other for the inventory. When the inventory is open, the clock of the game just stops. As animations, tweens, etc. should be linked in some way to the state clock, so all this stops too. When the player leave the inventory, everything continues as before, just like nothing happened. Moreover, if the game state need to compare time points recorded before and after opening the inventory, this can be done in a consistent way. If later the game designer decide that time should not stop while in the inventory, they just need to have both states running in parallel and everything should work (well, when this will be supported).
It would be a good thing to find a wiser way to deal with problems due to too big elapsed time than just capping it. But I think this requires some deep changes in the main game loop, and it is hardly possible to do without breaking some stuff. E.g. if the physics require step not bigger than 1/30 s to stay stable an we have a frame of 1/10 s, a solution would be to update the game 3 times to keep in sync with real-world time without breaking the physics requirement. This basically means to switch to fixed time steps (see this: http://gafferongames.com/game-physics/fix-your-timestep/). But this is not the problem I try to address here so it is a bit out-of topic, we should discuss this elsewhere.
I disagree on the fact that events and callback can happen at any time. Phaser event's callbacks are called when Timer.update() is called. That is, when Time.update() is called: at very beginning of Game.update(). Unless I am missing something ? As mentioned above, using state clocks may allow to move timer update just before State.update(), which seems more natural. However it do not solve the problems caused by people doing weird stuff with timers, but that is a different topic. It may be worth to document what can or can't be done in timer's callbacks.

To clarify the point about callbacks happening at any time: I meant DOM based events, keyboard, mouse, touch, etc, not Timer events. DOM level events happen out of sync and can impact a running Timer (destroy it, add new ones, etc). It's here that I see the most weird stuff happen.

I love your comprehensive request!

I was wondering if it is also possible to access the Phaser Timer class with physicsElapsed seconds. for example: game.time.events.addAtPhysicsTime() insead of game.time.events.add()

If you are on a slow machine, the Timer class only acepts realTime (milli)seconds and therefore these events can get called before you intend it to get called (similar to you lava crumbling the tiles problem).

Closing this request off as we have now fully implemented a proper physics timer internally and custom game specific fps rates. There is still no concept of a "Game clock" but that isn't going to be part of Phaser 2.

phaserjs / phaser

Real-time vs. Game time vs. Physics time, various timing issues #798