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:
-
classmethod
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
-
static
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
-
static