Time

Alarm Utils

class CommonAlarmUtils

Bases: HasClassLog

Utilities for manipulating alarms.

classmethod cancel_alarm(alarm_handle)

Cancel an alarm so that it will no longer occur.

Parameters:

alarm_handle (CommonAlarmHandle) – The handle of the alarm to cancel.

Returns:

True, if the alarm was cancelled successfully. False, if not.

Return type:

bool

classmethod get_log_identifier()

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:

The identifier for the log

Return type:

str

classmethod get_mod_identity()

Retrieve the identity of the mod that owns the class.

Warning

Override this function with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:

An instance of CommonModIdentity

Return type:

CommonModIdentity

Raises:

NotImplementedError – Thrown when the function is not implemented.

classmethod schedule_alarm(alarm_owner, time_until_first_occurrence, on_alarm_triggered_callback, should_repeat=False, time_until_repeat=None, accurate_repeat=True, persist_across_zone_loads=False, timeline=None)

Schedule an alarm that will trigger a callback after a set amount of time.

Parameters:

  • alarm_owner (Any) – The owner of the alarm.

  • time_until_first_occurrence (TimeSpan) – The time until the alarm triggers.

  • on_alarm_triggered_callback (Callable[['CommonAlarmHandle'], None]) – When the alarm is triggered at the specified time, this callback will be invoked with the alarm handle.

  • should_repeat (bool, optional) – If True, the alarm will repeat on the specified interval. If False, the alarm will only trigger once. Default is False.

  • time_until_repeat (TimeSpan, optional) – The amount of time that must pass before the alarm will trigger again. This only comes into play after being triggered once. Default is None.

  • accurate_repeat (bool, optional) – Whether or not the initial time should be based on the now time or the future time. Default is the Now time.

  • persist_across_zone_loads (bool, optional) – If True, the alarm will persist when loading a new zone. If False, the alarm will be canceled upon changing zones. Default is False.

  • timeline (Timeline, optional) – The timeline to use when determining the alarm trigger time as well as the initial time of the alarm. Default is Sim Timeline.

Returns:

The created alarm handle or None if the Time service is not currently available or a problem occurs.

Return type:

Union[CommonAlarmHandle, None]

classmethod schedule_daily_alarm(alarm_owner, hour, minute, on_alarm_triggered, persist_across_zone_loads=False)

Schedule an alarm that will repeat once a day, every day.

Parameters:

  • alarm_owner (Any) – The owner of the alarm.

  • hour (int) – The hour of the day to trigger the alarm at.

  • minute (int) – The minute of the hour to trigger the alarm at.

  • on_alarm_triggered (Callable[[CommonAlarmHandle], None]) – A callback invoked when the alarm is triggered.

  • persist_across_zone_loads (bool, optional) – If True, the alarm will persist when loading a new zone. If False, the alarm will be canceled upon changing zones. Default is False.

Returns:

The scheduled alarm or None if a problem occurs.

Return type:

CommonAlarmHandle

Real Date Utils

class CommonRealDateUtils

Bases: object

A utility for managing real life date and time.

Note

This utility is used to handle the Real Time and not the Game Time.

static get_current_date_string()

Retrieve the current date as a pre-formatted string.

Returns:

The string representation of the current real date.

Return type:

str

static get_current_date_time()

Retrieve the current date and time.

Returns:

The current real date and time.

Return type:

datetime

Time Utils

class CommonTimeUtils

Bases: object

Utilities for handling the in-game Time, also known as Sim Time.

static advance_current_time(hours=0, minutes=0, seconds=0)

Advance the current time by the specified amounts.

Parameters:

  • hours (int, optional) – The number of hours to advance.

  • minutes (int, optional) – The number of minutes to advance.

  • seconds (int, optional) – The number of seconds to advance.

static convert_milliseconds_to_seconds(milliseconds)

Convert Milliseconds to Seconds.

Parameters:

milliseconds (float) – The value to convert.

Returns:

The converted value in seconds.

Return type:

float

static convert_seconds_to_milliseconds(seconds)

Convert Seconds to Milliseconds.

Parameters:

seconds (float) – The value to convert.

Returns:

The converted value in milliseconds.

Return type:

float

static create_date_and_time(minutes=0, hours=0, days=0)

Create a date and time that takes place a number of Sim minutes, hours, or days in the future.

Parameters:

  • minutes (int, optional) – A number of Sim minutes in the future the date and time will be set at. Default is 0 Sim minutes.

  • hours (int, optional) – A number of Sim hours in the future the date and time will be set at. Default is 0 Sim hours.

  • days (int, optional) – A number of Sim days in the future the date and time will be set at. Default is 0 Sim days.

Returns:

A date and time that will occur a number of Sim minutes, hours, or days in the future.

Return type:

DateAndTime

static create_interval_from_sim_hours(hours)

Create a time span interval that spans from the current Sim time to a number of Sim hours in the future.

Parameters:

hours (int) – A number of Sim hours in the future the time span will indicate.

Returns:

A time span that will occur a number of Sim hours in the future.

Return type:

TimeSpan

static create_interval_from_sim_minutes(minutes)

Create a time span interval that spans from the current Sim time to a number of Sim minutes in the future.

Parameters:

minutes (int) – A number of Sim minutes in the future the time span will indicate.

Returns:

A time span that will occur a number of Sim minutes in the future.

Return type:

TimeSpan

static create_interval_from_sim_seconds(seconds)

Create a time span interval that spans from the current Sim time to a number of Sim seconds in the future.

Parameters:

seconds (int) – A number of Sim seconds in the future the time span will indicate.

Returns:

A time span that will occur a number of Sim seconds in the future.

Return type:

TimeSpan

static create_time_span(minutes=0, hours=0, days=0)

Create a time span that spans from the current Sim time to a number of Sim minutes, hours, or days in the future.

Parameters:

  • minutes (int, optional) – A number of Sim minutes in the future the time span will indicate. Default is 0 Sim minutes.

  • hours (int, optional) – A number of Sim hours in the future the time span will indicate. Default is 0 Sim hours.

  • days (int, optional) – A number of Sim days in the future the time span will indicate. Default is 0 Sim days.

Returns:

A time span that will occur a number of Sim minutes, hours, or days in the future.

Return type:

TimeSpan

static game_is_paused()

Determine if the game is paused.

Returns:

True, if the game is paused. False, if not.

Return type:

bool

static game_is_running_at_speed(clock_speed)

Determine if the game is running at the specified speed.

Parameters:

clock_speed (ClockSpeedMode) – The speed to change the game time to.

Returns:

True, if the game is running at the specified speed. False, if not.

Return type:

bool

static get_clock_speed()

Retrieve the current clock speed.

Returns:

The current speed of the game clock.

Return type:

ClockSpeedMode

static get_clock_speed_scale()

Retrieve the current clock speed multiplier.

Returns:

The current speed multiplier of the game clock.

Return type:

ClockSpeedMultiplierType

static get_current_date_and_time()

Retrieve the current date and time.

Returns:

The current date and time.

Return type:

DateAndTime

static get_current_day(date_and_time=None)

Retrieve the current Sim day of the month.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The current Sim day of the month.

Return type:

int

static get_current_hour(date_and_time=None)

Retrieve the current Sim hour of the day in military time.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The current Sim hour of the day in military time.

Return type:

int

static get_current_minute(date_and_time=None)

Retrieve the current Sim minute of the hour.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The current Sim minute of the hour.

Return type:

int

static get_current_second(date_and_time=None)

Retrieve the current Sim second of the minute.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The current Sim second of the minute.

Return type:

int

static get_current_week(date_and_time=None)

Retrieve the current Sim week of the month.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The current Sim week of the month.

Return type:

int

static get_day_of_week(date_and_time=None)

Retrieve the current day of the week.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The current day of the week. 0-6

Return type:

int

static get_game_clock()

Get an instance of the GameClock.

Returns:

An instance of the game clock.

Return type:

GameClock

static get_time_service()

Get an instance of the TimeService.

Returns:

An instance of the Time Service.

Return type:

TimeService

static get_total_days(date_and_time=None)

Retrieve the total Sim days since the start of the season.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The total number of Sim days since the start of the season.

Return type:

int

static get_total_hours(date_and_time=None)

Retrieve the total Sim hours since the start of the day in military time.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The total number of Sim hours since the start of the day in military time.

Return type:

int

static get_total_minutes(date_and_time=None)

Retrieve the total Sim minutes since the start of the day.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The total number of Sim minutes since the start of the day.

Return type:

int

static get_total_seconds(date_and_time=None)

Retrieve the total Sim seconds since the start of the day.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The total number of Sim seconds since the start of the day.

Return type:

int

static get_total_ticks(date_and_time=None)

Retrieve the total Sim ticks since the start of the day.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The total number of Sim ticks in milliseconds since the start of the day.

Return type:

int

static get_total_weeks(date_and_time=None)

Retrieve the total Sim weeks since the start of the season.

Parameters:

date_and_time (DateAndTime, optional) – The date and time to retrieve the value from. If not specified, the current date and time will be used. Default is None.

Returns:

The total number of Sim weeks since the start of the season.

Return type:

int

static interval_in_sim_days(days)

Create a time span interval that spans from the current Sim time to a number of Sim days in the future.

Parameters:

days (int) – A number of Sim days in the future the time span will indicate.

Returns:

A time span that will occur a number of Sim days in the future.

Return type:

TimeSpan

static interval_in_sim_weeks(weeks)

Create a time span interval that spans from the current Sim time to a number of Sim weeks in the future.

Parameters:

weeks (int) – A number of Sim weeks in the future the time span will indicate.

Returns:

A time span that will occur a number of Sim weeks in the future.

Return type:

TimeSpan

static is_day_time(date_and_time=None)

Determine if it is currently Day Time.

Parameters:

date_and_time (DateAndTime, optional) – A date and time to check. If not specified, the current time will be used instead. Default is unspecified.

Returns:

True, if it is day time. False, if not.

Return type:

bool

static is_night_time(date_and_time=None)

Determine if it is currently Night Time.

Parameters:

date_and_time (DateAndTime, optional) – A date and time to check. If not specified, the current time will be used instead. Default is unspecified.

Returns:

True, if it is night time. False, if not.

Return type:

bool

static is_sun_out()

Determine if the Sun is currently out.

Returns:

True, if the sun is out. False, if not.

Return type:

bool

static pause_the_game()

Pause the game.

Returns:

True, if successful. False, if not.

Return type:

bool

static set_clock_speed(clock_speed)

Set the clock speed.

Parameters:

clock_speed (ClockSpeedMode) – The speed to set the game clock to.

Returns:

True, if successful. False, if not.

Return type:

bool

static set_current_time(hours, minutes, seconds)

Set the current time.

Parameters:

  • hours (int) – The hour of the day to set the time to.

  • minutes (int) – The minute of the hour to set the time to.

  • seconds (int) – The second of the minute to set the time to.

static set_game_speed_normal()

Change the speed of the game clock to Normal speed.

Returns:

True, if successful. False, if not.

Return type:

bool

static set_game_speed_to_interaction_startup_speed()

Change the speed of the game clock to Interaction Startup Speed.

Returns:

True, if successful. False, if not.

Return type:

bool

static set_game_speed_to_speed_three()

Change the speed of the game clock to Speed Three.

Returns:

True, if successful. False, if not.

Return type:

bool

static set_game_speed_to_speed_two()

Change the speed of the game clock to Speed Two.

Returns:

True, if successful. False, if not.

Return type:

bool

static set_game_speed_to_super_speed_three()

Change the speed of the game clock to Super Speed Three.

Returns:

True, if successful. False, if not.

Return type:

bool