TIME ENGINE - Preliminary Overview

A time engine keeps track of all time-related issues, namely the current server and client timestamps, passed time in the simulation, latencies, time conversions etc.

API:

All time functionality is in the Zorn.time module, most things are in the Zorn.time.Engine class.

Engine.__init__(): create a new engine. This initializes all values to default values. It also implicitly calls tick().

Engine.tick(): update the engine's time values. It is important to note that time does not progress between calls to tick(). However, latency information (client-to-server offset) may be changed.

Engine.delta_ms(): returns the time, in milliseconds, between the last tick() and the tick() before that. delta_ms() does not take the current time factor into account. It is to be used in message timestamping.

Engine.delta_s(): returns the time, in seconds, between the last tick() and the tick() before that. delta_s() takes the current time factor (see below) into account. It is to be used in physics and graphics simulations (i.e. object or effect movement).

Engine.getFactor(): return the currently used time factor

Engine.setFactor(f, [when, [f2, when2]]): set the time factor to f. If when is given (an absolute 12-bit timestamp), don't apply the new factor until after when has passed. If f2 and when2 are given, a linear gradient from f to f2 occurs after time when and lasts when2 milliseconds.

Engine.now([offset]): returns the current server-side time stamp as a 16-bit value. If offset is given, offset milliseconds are added to now. offset may be negative. If called on the client, gives a best estimate by using the current client-server offset estimate.

Engine.client([offset]): Like now(), but returns the client-side time stamp, meaning the time offset between the server and the client is ignored.

Engine.pong(<values>): update the client-server offset with this estimate. The exact nature of <values> is not determined yet. This method is usually called after a PING-PONG message exchange.

Engine.difference(timestamp1, timestamp2): calculate the distance, in milliseconds, between timestamp1 and timestamp2. Positive values mean timestamp2 is later, while negative values mean timestamp1 is later.

Engine.since(timestamp): shortcut for difference(timestamp, now()). Positive values mean timestamp is in the past. Negative values mean timestamp is in the future.

Engine.ms_to_s(t): Calculate t in milliseconds to the value in seconds, while respecting the current time factor

Engine.s_to_ms(t): Calculate t in seconds to the value in milliseconds, while respecting the current time factor. If the current time factor is 0.0, +inf or -inf are returned.