#Interface: TimeApi

Plot's synchronized clock for the current game session.

Use now() for gameplay timestamps and deadlines. Its values have the same meaning on every connected client, regardless of each device's local clock setting. Call await Plot.ready() before calling these methods or reading the time properties. Conversion helpers require safe-integer millisecond values and throw TypeError if a conversion would exceed that range. Time is also available inside connected lifecycle and initial snapshot callbacks, after Plot installs the complete ready state and before the readiness promise resolves.

After startup, this clock keeps advancing from its last synchronized anchor during a disconnect and is corrected when Plot recovers. It does not prove that the connection is healthy; use Plot.connection for an optional connection indicator.

#Throws

PlotNotReadyError when a method with valid arguments is called or a time property is read before complete ready state is installed.

#See

Error handling

#Properties

#gameTimeEpochUnixMs

readonly gameTimeEpochUnixMs: number

The fixed Unix timestamp, in milliseconds, corresponding to game time 0.

This epoch belongs to the current game session. It is not the Unix epoch.

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#localClockOffsetMs

readonly localClockOffsetMs: number

The current correction to add to a local Date.now() timestamp.

The correction can change as Plot resynchronizes the clock. Prefer now() for gameplay timestamps, and read this property at the time a local timestamp needs converting.

At the same instant, Date.now() + localClockOffsetMs approximates unixNow().

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when the device clock cannot provide a safe reading.

#Methods

#fromLocalClockMs()

fromLocalClockMs(localTimestampMs): number

Converts a timestamp from the current device's Date.now() clock to game time by applying the latest Plot clock correction.

#Parameters

#localTimestampMs

number

A safe-integer timestamp from this device's local clock.

#Returns

number

#Throws

PlotNotReadyError for a valid argument when the complete ready state has not been installed.

#Throws

PlotOperationError when the device clock cannot provide a safe reading.

#Throws

TypeError when the argument or result is not a safe integer.

#fromUnixMs()

fromUnixMs(unixTimestampMs): number

Converts a Unix timestamp in whole milliseconds to game time.

Use this for timestamps that already share Plot's synchronized Unix clock.

#Parameters

#unixTimestampMs

number

A safe-integer synchronized Unix timestamp.

#Returns

number

#Throws

PlotNotReadyError for a valid argument when the complete ready state has not been installed.

#Throws

TypeError when the argument or result is not a safe integer.

#now()

now(): number

Returns the current whole milliseconds since this game's time epoch.

The value never decreases within this SDK instance, including when Plot corrects its estimate of the synchronized clock.

#Returns

number

#Example

Create a deadline that every client can render consistently.

const endsAtGameTimeMs = Plot.time.now() + 10_000

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when the device clock cannot provide a safe reading.

#toUnixMs()

toUnixMs(gameTimeMs): number

Converts a game-time timestamp to Unix milliseconds.

This is the inverse of fromUnixMs() for values within JavaScript's safe integer range.

#Parameters

#gameTimeMs

number

A safe-integer timestamp from this game session.

#Returns

number

#Throws

PlotNotReadyError for a valid argument when the complete ready state has not been installed.

#Throws

TypeError when the argument or result is not a safe integer.

#unixNow()

unixNow(): number

Returns Plot's current synchronized Unix timestamp in whole milliseconds.

This is comparable to Date.now(), but corrects differences between the local device clock and Plot's shared clock. The value never decreases within this SDK instance.

#Returns

number

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when the device clock cannot provide a safe reading.