Time

This module contains functions for retrieving time-related information, such as the time since the program started, the time since the last frame, and the Unix time.

To use this module, include the following line in your project file:

require engine.time_core // or require engine.core

Note

All functions for delta time, if called from on_update() return how much real time passed from start of the previous frame to start of the current frame, times the scale for functions that don’t have unscaled in their name. But if these functions are called from during physics simulation (from on_fixed_update() or collision callbacks), they return time between physics steps, which is always fixed delta time, and since time scale does not affect physics time step, both normal and unscaled functions will return unscaled delta time.

Functions

get_clock(): clock
Returns:

  • clock - the value that represents the time in seconds since 00:00 hours, Jan 1, 1970 UTC (i.e., the current unix time)

Usage example:

let unixTime = get_clock() // note that the returned value is not an integer
let seconds = int64(unixTime)
get_current_frame(): uint64
Returns:

  • uint64 - the current frame number since the start of the program

get_delta_time(): float
Returns:

  • float - the time in seconds since the last frame to the current frame. For physics (inside on_fixed_update() or collision callbacks) this is the time between physics steps, which is always unscaled fixed delta time. This applies for all delta time functions.

get_delta_time_msec(): int
Returns:

  • int - the time in milliseconds since the last frame to the current frame

get_delta_time_scale(): float
Returns:

  • float - the time scaling factor

get_delta_time_usec(): int
Returns:

  • int - the time in microseconds since the last on_update call

get_fixed_tick(): int

Number of the current fixed step, the one on_fixed_update runs. The same on the server and every client at the same moment, so it labels per-step data that crosses the network: input, a predicted state, the server’s answer.

Returns:

  • int - the number of the current fixed step.

Usage example:

[export]
def on_fixed_update {
    broadcast_net_command(ShipInput(tick = get_fixed_tick(), thrust = get_action_axis("thrust")))
}
get_sync_time(): float
Returns:

  • float - the time in seconds synced between client & server

get_sync_time_msec(): int

The clock the replication frames are stamped with, in whole milliseconds: in a session the time synced with the server, the clock get_sync_time returns in seconds, otherwise the scaled local time. The value wraps, so compare two stamps through their difference.

Returns:

  • int - the synced time in milliseconds; 0 when no game script owns the context

get_time(): float
Returns:

  • float - the time in seconds since the start of the program to the current frame

get_time(ref: int64): float
Arguments:

  • ref : int64 - the reference time, get it with ref_time_ticks()

Returns:

  • float - the time in seconds since the reference time

Usage example:

let refTime = ref_time_ticks()
// do something
let elapsedTimeSec = get_time(refTime)
get_time_msec(): int64
Returns:

  • int64 - the time in milliseconds since the start of the program to the current frame

get_time_msec(ref: int64): int

retrieves the time in milliseconds since the reference time

Usage example:

let refTime = ref_time_ticks()
// do something
let elapsedTimeMsec = get_time_msec(refTime)
Arguments:

  • ref : int64 - the reference time, get it with ref_time_ticks()

Returns:

  • int - the time in milliseconds since the specified tick

get_time_nsec(ref: int64): int64

Retrieves the time in nanoseconds since the reference time.

Usage example:

let refTime = ref_time_ticks()
// do something
let elapsedTimeNsec = get_time_nsec(refTime)
Arguments:

  • ref : int64 - the reference time, get it with ref_time_ticks()

Returns:

  • int64 - the time in nanoseconds since the specified tick

get_time_usec(): int64
Returns:

  • int64 - the time in microseconds since the start of the program

get_time_usec(ref: int64): int

Retrieves the time in microseconds since the reference time.

Usage example:

let refTime = ref_time_ticks()
// do something
let elapsedTimeUsec = get_time_usec(refTime)
Arguments:

  • ref : int64 - the reference time, get it with ref_time_ticks()

Returns:

  • int - the time in microseconds since the specified tick

get_unscaled_delta_time(): float
Returns:

  • float - the time in seconds since the last frame to the current frame, ignoring time scaling

get_unscaled_delta_time_msec(): int
Returns:

  • int - the time in milliseconds since the last frame to the current frame, ignoring time scaling

get_unscaled_delta_time_usec(): int
Returns:

  • int - the time in microseconds since the last on_update call, ignoring time scaling

get_unscaled_time(): float
Returns:

  • float - the time in seconds since the start of the program to the current frame, ignoring time scaling

get_unscaled_time_msec(): int64
Returns:

  • int64 - the time in milliseconds since the start of the program to the current frame, ignoring time scaling

get_unscaled_time_usec(): int64
Returns:

  • int64 - the time in microseconds since the start of the program, ignoring time scaling

ref_time_ticks(): int64
Returns:

  • int64 - the current reference timer tick value

set_delta_time_scale(scale: float): float

Change the time scaling factor. The value is clamped to the range [0.0, 1000.0] and the new time scaling factor is returned. Physics will also slow down, but time step will not change, so simulation precision will not increase. If you need physics step to also scale, you’ll have to change it separately with set_physics_fps() (but usually it is not necessary and can make physics unstable)

Arguments:

  • scale : float - the factor to scale the time by

Returns:

  • float - the new time scaling factor