Time

Alarm Utils

class CommonAlarmUtils

Bases: sims4communitylib.logging.has_class_log.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_next_occurrence, 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(milliseconds)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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