Misc Utilities

Location

Note

To manipulate the location of Sims, take a look at CommonSimLocationUtils

Location

Terrain

class CommonTerrainUtils

Bases: sims4communitylib.utils.terrain.common_terrain_location_utils.CommonTerrainLocationUtils

An obsolete utility for manipulating terrain location.

Travel

class CommonTravelUtils

Bases: object

Utilities for moving Sims around.

static get_travel_group_id(sim_info)

Retrieve a decimal identifier for the Travel Group of a Sim.

Parameters:sim_info (SimInfo) – An instance of a Sim.
Returns:The decimal identifier of the Travel Group of the Sim or -1 if a problem occurs.
Return type:int
static travel_to_home_lot_of(sim_info)

Travel to the home lot of a Sim.

Parameters:sim_info (SimInfo) – The owner of the home lot to travel to.
static travel_to_home_lot_of_active_sim(sim_info)

Travel with the specified Sim to the home lot of the Active Sim.

Parameters:sim_info (SimInfo) – The Sim to travel with.
static travel_to_lot(sim_info, lot_id)

Travel with the specified Sim to the Lot with the specified identifier.

Parameters:
  • sim_info (SimInfo) – The Sim to travel with.
  • lot_id (int) – The identifier of the lot to travel to.
static travel_to_zone(sim_info, zone_id)

Travel with the specified Sim to a Zone.

Parameters:
  • sim_info (SimInfo) – The Sim to travel with.
  • zone_id (int) – The identifier of the zone to travel to.

Resources

Camera

class CommonCameraUtils

Bases: object

Utilities for controlling the camera.

classmethod start_focus(target, follow=True, client=None)

Focus the player camera on something.

Parameters:
  • target (Union[Sim, GameObject, CommonVector3]) – The Target SimInfo, Game Object, or Position to focus the camera on.
  • follow (bool, optional) – If True, the camera will follow the object after focusing on it. If False, the camera will not follow the object after focusing on it. Default is True.
  • client (Client, optional) – The client to focus on the Sim. If None, the active client will be used. Default is None.
Returns:

True, if the camera was focused on the specified target.

classmethod start_focus_on_object(game_object, follow=True)

Focus the player camera on a game object.

Parameters:
  • game_object (GameObject) – The object to focus on.
  • follow (bool, optional) – If True, the camera will follow the object after focusing on it. If False, the camera will not follow the object after focusing on it. Default is True.
classmethod start_focus_on_position(position, client=None)

Focus the player camera on a position.

Parameters:
  • position (CommonVector3) – The position to focus the camera on.
  • client (Client, optional) – The client to focus on the position. If None, the active client will be used. Default is None.
classmethod start_focus_on_sim(sim_info, follow=True, client=None)

Focus the player camera on a Sim.

Parameters:
  • sim_info (SimInfo) – The SimInfo of the Sim to focus the camera on.
  • follow (bool, optional) – If True, the camera will follow the object after focusing on it. If False, the camera will not follow the object after focusing on it. Default is True.
  • client (Client, optional) – The client to focus on the Sim. If None, the active client will be used. Default is None.
classmethod stop_focus_on_object(game_object)

Stop focusing the player camera on a game object.

Parameters:game_object (GameObject) – The object to stop focusing on.

Career

class CommonCareerUtils

Bases: object

Utilities for manipulating Careers.

static determine_entry_level_into_career_from_user_level(career: <sphinx.ext.autodoc.importer._MockObject object at 0x7f09ecc5a9d0>, desired_user_level: int) → Tuple[Optional[int], Optional[int], Optional[<sphinx.ext.autodoc.importer._MockObject object at 0x7f09ecc5a550>]]

get_career_entry_level_from_user_level(career, desired_user_level)

Pick a career level and career track from a user level.

Parameters:
  • career (Career) – The career to retrieve a career track from.
  • desired_user_level (int) – The user level desired to be given to a Sim.
Returns:

The career level for the career track (or branch career track) used, the level of the user in that career track, and the career track itself.

Return type:

Tuple[int, int, TunableCareerTrack]

classmethod get_all_career_tracks(career)

Retrieve all Career Tracks available for a Career, including all branching Career Tracks.

Parameters:career (Career) – A career.
Returns:A collection of Career Levels available for the specified Career.
Return type:Tuple[CareerLevel]
static get_all_careers_generator(include_career_callback=None)

Retrieve all Careers.

Parameters:include_career_callback (Callable[[Career], bool], optional) – If the result of this callback is True, the Career will be included in the results. If set to None, All Careers will be included. Default is None.
Returns:An iterator of Careers matching include_career_callback
Return type:Iterator[Career]
classmethod get_career_guid(career)

Retrieve the Guid64 identifier of a career.

Parameters:career (Career) – An instance of a Career.
Returns:The Guid64 identifier of the specified Career.
Return type:Union[int, None]
classmethod get_career_id(career)

Retrieve the instance identifier of a Career.

Parameters:career (Career) – An instance of a Career.
Returns:The instance identifier of the specified Career or -1 if a problem occurs.
Return type:int
classmethod get_career_levels(career, include_branches=False)

Retrieve Career Levels available for a Career.

Parameters:
  • career (Career) – A career.
  • include_branches – If True, all career levels from Career Tracks the starting track branches into will be included in the result. If False, only the career levels available for the starting Track will be included in the result. Default is False.
Return type:

include_branches: bool, optional

Returns:

A collection of Career Levels available for the specified Career.

Return type:

Tuple[CareerLevel]

classmethod get_career_location(career)

Retrieve the workplace location of a career.

Parameters:career (Career) – An instance of a Career.
Returns:The location the Career is set to occur at.
Return type:Union[CareerLocation, None]
classmethod get_career_location_zone_id(career)

Retrieve the zone id of a Career where it is set to occur at.

Parameters:career (Career) – An instance of a Career.
Returns:The instance identifier of the zone the career is set to occur at.
Return type:int
static get_instance_manager()

Retrieve the instance manager for careers.

Returns:The instance manager for careers.
Return type:InteractionInstanceManager
classmethod get_starting_career_track(career)

Retrieve the starting Career Track of a Career.

Parameters:career (Career) – A career.
Returns:The starting Career Track of the Career or None if not found.
Return type:Union[TunableCareerTrack, None]
static get_work_performance(career)

Add an amount to the work performance of a career.

Parameters:career (Career) – The career to modify.
Returns:The amount of work performance acquired in the specified Career.
Return type:float
static load_career_by_guid(career)

Load an instance of a Career by its identifier.

Parameters:career (Union[int, Career]) – The identifier of a Career.
Returns:An instance of a Career matching the decimal identifier or None if not found.
Return type:Union[Career, None]
static modify_work_performance(career, amount)

Modify the work performance acquired in a Career.

Parameters:
  • career (Career) – The career to modify.
  • amount (int) – The amount of work performance to apply to the Career.

Career Tracks

class CommonCareerTrackUtils

Bases: object

Utilities for manipulating Career Tracks.

classmethod determine_entry_level_into_career_track_by_user_level(career_track, desired_user_level)

Pick a Career Track level and Career Track from a user level.

Parameters:
  • career_track (TunableCareerTrack) – The Career Track to locate a Career Level in.
  • desired_user_level (int) – The desired user level within the Career Track.
Returns:

The index of the Career Level for the Career Track (or branch Career Track) used, the level of the user in that Career Track, and the Career Track itself.

Return type:

Tuple[int, int, TunableCareerTrack]

static get_all_career_tracks_generator(include_career_callback=None)

Retrieve all Career Tracks.

Parameters:include_career_track_callback (Callable[[TunableCareerTrack], bool], optional) – If the result of this callback is True, the Career will be included in the results. If set to None, All Careers will be included. Default is None.
Returns:An iterator of Careers matching include_career_track_callback
Return type:Iterator[TunableCareerTrack]
classmethod get_branches(career_track, include_sub_branches=True)

Retrieve a collection of all Career Tracks that branch off of a Career Track and if specified, the branches those branches branch off to.

Parameters:
  • career_track (TunableCareerTrack) – A Career Track.
  • include_sub_branches (bool, optional) – If True, all branches will be checked for their own branches and those branches will be included recursively. If False, only the top level branches will be included. Default is False.
Returns:

A collection of all Career Tracks that branch off from the specified Career Track.

Return type:

Tuple[TunableCareerTrack]

classmethod get_career_level_by_index(career_track, index)

Retrieve a Career Level within a Career Track by its index.

Parameters:
  • career_track (TunableCareerTrack) – A Career Track.
  • index (int) – The index of the career level to retrieve. (Career Levels start at 1 instead of zero!)
Returns:

The career level found at the specified index or None if not found.

Return type:

Union[CareerLevel, None]

classmethod get_career_levels(career_track, include_branches=False)

Retrieve a collection of all career levels under a Career Track.

Parameters:
  • career_track (TunableCareerTrack) – A Career Track.
  • include_branches – If True, all career levels from Career Track branches will be included in the result. If False, only the career levels available for the specified Career Track will be included in the result. Default is False.
Return type:

include_branches: bool, optional

Returns:

A collection of all Career Levels under the Career Track.

Return type:

Tuple[CareerLevel]

classmethod get_career_track_guid(career_track)

Retrieve the Guid64 identifier of a career_track.

Parameters:career_track (TunableCareerTrack) – An instance of a Career Track.
Returns:The Guid64 identifier of the specified Career Track.
Return type:Union[int, None]
static load_career_track_by_guid(career_track_identifier)

Load an instance of a CareerTrack by its identifier.

Parameters:career_track_identifier (Union[int, TunableCareerTrack]) – The identifier of a CareerTrack.
Returns:An instance of a Career Track matching the decimal identifier or None if not found.
Return type:Union[TunableCareerTrack, None]

Career Levels

class CommonCareerLevelUtils

Bases: object

Utilities for manipulating Career Levels.

static load_career_level_by_guid(career_level_identifier)

Load an instance of a CareerLevel by its identifier.

Parameters:career_level_identifier (Union[int, CareerLevel]) – The identifier of a CareerLevel.
Returns:An instance of a CareerLevel matching the decimal identifier or None if not found.
Return type:Union[CareerLevel, None]

Collections

class CommonCollectionUtils

Bases: object

Utilities for collections.

static add_to_dict_if_not_exist(dictionary_one, dictionary_two)

Combine two dictionaries.

Note

If a key already exists in the first dictionary, the value from the second dictionary is ignored.

Parameters:
  • dictionary_one (Dict[Any, Any]) – The first dictionary.
  • dictionary_two (Dict[Any, Any]) – The second dictionary.
Returns:

A new combined dictionary.

Return type:

Dict[Any, Any]

static create_possible_combinations(items, items_per_combination)

Create a collection of all possible combinations of the specified items.

Note

Example: With items: [1, 2, 3] and combination_length: 2 the result will be: {(1, 2), (1, 3), (2, 3)}

Parameters:
  • items (Union[List[Any], Tuple[Any]]) – A collection of items to create combinations from.
  • items_per_combination (int) – The number of items in each combination.
Returns:

A collection of combinations

Return type:

Set[Tuple[Any]]

static flatten(to_flatten)

Flatten a collection of collections to a single list or itself if already flattened.

Parameters:to_flatten (Any) – A collection of items.
Returns:A single flattened list or to_flatten if already flattened.
Return type:Union[Any, List[Any]]
static intersects(list_one, *list_items)

Determine if a list contains any of the specified items.

Parameters:
  • list_one (List[Any]) – The list being checked.
  • list_items (Any) – An iterator of items being searched for.
Returns:

True, if the list contains any of the specified items. False, if not.

Return type:

bool

static is_collection(obj)

Determine if an object is a collection or not.

Parameters:obj (Any) – An object.
Returns:True, if the object is a collection, False, if not.
Return type:bool
static lists_are_equal(list_one, list_two)

Determine if two collections contain tbe exact same values.

Note

The order of the values in each collection will be asserted.

Parameters:
  • list_one (Union[Tuple[Any], List[Any]]) – The first value. (Can be any collection type)
  • list_two (Union[Tuple[Any], List[Any]]) – The second value. (Can be any collection type)
Returns:

True, if both lists are exactly the same. False, if not.

Return type:

bool

static merge_dict(destination, source, prefer_source_values=True, allow_duplicates_in_collections=True)

Merge a source dictionary into a destination dictionary. The destination will not be modified!

Parameters:
  • destination (Dict[Any, Any]) – The dictionary to use as the destination. Source will be merged into this.
  • source (Dict[Any, Any]) – The dictionary to use as the source. Destination will have this merged into itself.
  • prefer_source_values (bool, optional) – When an entry is found within both the destination and the source, setting it to True will prefer to overwrite the destination value with the source value, setting this to False will prefer to use the destination value. Default is True.
  • allow_duplicates_in_collections (bool, optional) – When a collection is found within both dictionaries, setting this to True will allow duplicate entries, setting it to False will not allow duplicate entries. Default is True.
Returns:

A dictionary containing the source merged into the destination.

Return type:

Dict[Any, Any]

Components

class CommonComponentUtils

Bases: object

Utilities for handling components of component containers.

static add_dynamic_component(component_container, component_type)

Add a dynamic component to a ComponentContainer.

Parameters:
  • component_container (ComponentContainer) – The ComponentContainer to add to.
  • component_type (CommonComponentType) – The type of component being added.
Returns:

The added Component or None

Return type:

Union[Component, None]

static get_component(component_container, component_type, add_dynamic=False, return_type=Component)

Retrieve a component from a ComponentContainer.

Parameters:
  • component_container (ComponentContainer) – The ComponentContainer to retrieve a component from.
  • component_type (CommonComponentType) – The type of component being retrieved.
  • add_dynamic (bool, optional) – If True, the component will be added dynamically. If False, the component will not be added dynamically. Default is False.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Component.
Returns:

An object of type Component, or None if the specified component type is not found.

Return type:

Union[CommonExpectedReturnType, None]

static has_component(component_container, component_type)

Determine if a ComponentContainer has a component of the specified type.

Parameters:
  • component_container (ComponentContainer) – The ComponentContainer to check.
  • component_type (CommonComponentType) – The type of component to locate.
Returns:

True, if the ComponentContainer contains a component of the specified type. False, if not.

Return type:

bool

Fires

class CommonFireUtils

Bases: object

Utilities for manipulating fires.

classmethod despawn_scorch_marks_at_location(location)

Despawn scorch marks at a location.

Parameters:location (CommonLocation) – The location to despawn the scorch marks at.
Returns:True, if scorch marks were despawned successfully. False, if not.
Return type:bool
classmethod get_all_active_fires()

Retrieve an instance of all active Fires.

Returns:A collection of fires currently active.
Return type:Tuple[Fire]
classmethod get_fire_service()

Retrieve the service that manages Fires.

Returns:A service that manages fires or None if not found.
Return type:Union[FireService, None]
classmethod has_active_fires()

Determine if Fires are currently blazing.

Returns:True, if fires are currently blazing somewhere. False, if not.
Return type:bool
classmethod is_fire_allowed_at_location(location, run_placement_tests=True)

Determine if Fires are allowed to be placed at a Location.

Parameters:
  • location (CommonLocation) – The location to check.
  • run_placement_tests (bool, optional) – Set True to run placement tests for the fire. Set False to exclude running placement tests for the fire. Default is True.
Returns:

True, if fire can be spawned as the specified location. False, if not.

Return type:

bool

classmethod spawn_fires_on_object(game_object, number_of_fires=1)

Spawn a number of fires on an object.

Parameters:
  • game_object (GameObject) – An instance of an Object.
  • number_of_fires (int, optional) – The number of fires to spawn on the Object. Must be above zero. Default is 1.
Returns:

True, if fires have been spawned successfully. False, if not.

Return type:

bool

classmethod spawn_scorch_marks_at_location(location)

Spawn scorch marks at a location.

Parameters:location (CommonLocation) – The location to spawn the scorch marks at.
Returns:True, if scorch marks were spawned successfully. False, if not.
Return type:bool

Functions

class CommonFunctionUtils

Bases: object

Utilities for manipulating functions.

static noop(*_, **__)

An empty function that does nothing. Useful when you need something to do nothing.

Note

Use this when you want something to do nothing.

static noop_enqueue(*_, **__)

An empty function that does nothing but return CommonEnqueueResult.NONE(). Useful when you need something to simply return CommonEnqueueResult.NONE.

Note

Use this when you want something to simply return CommonEnqueueResult.NONE.

Returns:Returns CommonEnqueueResult.NONE.
Return type:CommonEnqueueResult
static noop_execution_result(*_, **__)

An empty function that does nothing but return CommonExecutionResult.NONE(). Useful when you need something to simply return CommonExecutionResult.NONE.

Note

Use this when you want something to simply return CommonExecutionResult.NONE.

Returns:Returns CommonExecutionResult.NONE.
Return type:CommonExecutionResult
static noop_false(*_, **__)

An empty function that does nothing but return False. Useful when you need something to simply return False.

Note

Use this when you want something to simply return False.

Returns:Returns False.
Return type:bool
static noop_test_result(*_, **__)

An empty function that does nothing but return CommonTestResult.NONE(). Useful when you need something to simply return CommonTestResult.NONE.

Note

Use this when you want something to simply return CommonTestResult.NONE.

Returns:Returns CommonTestResult.NONE.
Return type:CommonTestResult
static noop_true(*_, **__)

An empty function that does nothing but return True. Useful when you need something to simply return True.

Note

Use this when you want something to simply return True.

Returns:Returns True.
Return type:bool
static print_arguments(log, func_identifier='NO_IDENTIFIER_SPECIFIED')

Create a function that will log the arguments and keyword arguments it receives

Parameters:
  • log (CommonLog) – The log to print the arguments to.
  • func_identifier (str) – An identifier for the function to determine which function was invoked
Returns:

A function that will print the arguments sent to it when the original function is invoked.

Return type:

Callable[.., Any]

static run_predicate_with_reversed_result(predicate_function)

Wrap the specified predicate function and reverse the result of it when the function is invoked.

Parameters:predicate_function (Callable[.., bool]) – The predicate function to reverse the result of.
Returns:A function that will reverse the result of predicate_function upon invocation.
Return type:Callable[.., bool]
static run_predicates_as_one(predicate_functions, all_must_pass=True)

Wrap all predicate functions into a single predicate function. (See returned value for more information).

Note

If all_must_pass is True a wrapped function that will return a value of:

  • True, if all predicates resulted in a True value.
  • False, if any predicates resulted in a False value.

If all_must_pass is False a wrapped function that will return a value of:

  • True, if any predicates resulted in a True value.
  • False, if all predicates resulted in a False value.
Parameters:
  • predicate_functions (Iterator[Callable[.., bool]]) – The predicate functions to run as one.
  • all_must_pass (bool, optional) – If True, all the predicates must return a True value. If False, any of the predicates must return a True value.
Returns:

The result of running all functions.

Return type:

bool

static run_with_arguments(primary_function, *args, **kwargs)

Wrap a function and run it with additional arguments when something invokes it.

Parameters:primary_function (Callable[.., Any]) – The function that will be run.
Returns:A function that will send extra arguments upon invocation.
Return type:Callable[.., Any]
static safe_run(mod_identity, primary_function, fallback_function, *args, **kwargs)

Safely run a function, if the primary function throws an exception, the fallback function will be run instead.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod running a function safely.
  • primary_function (Callable[.., Any]) – The primary function to safely run.
  • fallback_function (Callable[.., Any]) – A function called when the primary function throws an exception.
  • args (Any) – Arguments to pass to both the primary function and fallback function.
  • kwargs (Any) – Keyword Arguments to pass to both the primary function and fallback function.
Returns:

The result of either the primary function or the fallback function if the primary threw an exception.

Return type:

Any

Game Client

class CommonGameClientUtils

Bases: object

Utilities for getting information about the game client.

static get_first_game_client()

Retrieve an instance of the first available Game Client.

Returns:An instance of the first available Game Client or None if not found.
Return type:Union[Client, None]
static get_first_game_client_id()

Retrieve the id of the first available Game Client.

Returns:The id of the first available Game Client or None if not found.
Return type:Union[int, None]
static get_game_client_by_account_id(account_id)

Locate a Game Client by an Account Id.

Returns:The Game Client that matches the specified Account Id or None if not found.
Return type:Union[Client, None]
static get_game_client_by_household(household)

Locate a Game Client by a Household.

Returns:The Game Client that matches the specified Household or None if not found.
Return type:Union[Client, None]
static get_game_client_by_household_id(household_id)

Locate a Game Client by a Household Id.

Returns:The Game Client that matches the specified Household Id or None if not found.
Return type:Union[Client, None]
static get_game_client_manager()

Retrieve the manager that manages the Game Clients for the game.

Returns:The manager that manages the Game Clients for the game.
Return type:ClientManager

Icons

class CommonIconUtils

Bases: object

Utilities for loading icons.

static load_arrow_left_icon()

Get the Resource Key for the ARROW_LEFT_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_arrow_navigate_into_icon()

Get the Resource Key for the ARROW_NAVIGATE_INTO_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_arrow_right_icon()

Get the Resource Key for the ARROW_RIGHT_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_blank_square_icon()

Get the Resource Key for the BLANK_SQUARE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_checked_circle_icon()

Get the Resource Key for the CHECKED_CIRCLE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_checked_square_icon()

Get the Resource Key for the CHECKED_SQUARE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_filled_circle_icon()

Get the Resource Key for the FILLED_CIRCLE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_question_mark_icon()

Get the Resource Key for the QUESTION_MARK_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_six_sided_dice_icon()

Get the Resource Key for the SIX_SIDED_DICE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_text_next_icon()

Get the Resource Key for the TEXT_NEXT_SQUARE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_text_prev_icon()

Get the Resource Key for the TEXT_PREV_SQUARE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_unchecked_square_icon()

Get the Resource Key for the UNCHECKED_SQUARE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_unfilled_circle_icon()

Get the Resource Key for the UNFILLED_CIRCLE_ICON.

Returns:An identifier for the icon.
Return type:Any
static load_x_icon()

Get the Resource Key for the X_ICON.

Returns:An identifier for the icon.
Return type:Any

Interactions

Note

To manipulate interactions of Sims, take a look at CommonSimInteractionUtils

Math

class CommonMathUtils

Bases: object

Utilities for math operations.

static calculate_degrees_between_positions(position_one, position_two)

Calculate the degrees between two positions.

Parameters:
Returns:

The degrees between the specified Vectors.

Return type:

float

static calculate_distance(position_one, position_two, flatten_positions=True)

Calculate the distance between two vectors.

Parameters:
  • position_one (CommonVector3) – An instance of a Vector.
  • position_two (CommonVector3) – An instance of a Vector.
  • flatten_positions (bool, optional) – If True, both Vectors will be flattened before calculations will occur. Default is True.
Returns:

The distance between the two specified vectors.

Return type:

float

static calculate_offset_from_degrees(position, degrees, length)

Calculate an offset vector based on the forward axis from a vector.

Parameters:
  • position (CommonVector3) – The original position.
  • degrees (float) – Amount of degrees to offset.
  • length (float) – The length of the offset.
Returns:

The vector offset.

Return type:

CommonVector3

static degrees_to_radian(degrees)

Translate Degrees to Radian.

Parameters:degrees (float) – The value to convert.
Returns:The value as Radian.
Return type:float
static radian_to_degrees(radian)

Translate Radian to Degrees.

Parameters:radian (float) – The value to convert.
Returns:The value as Degrees.
Return type:float

Rabbit Hole

class CommonRabbitHoleUtils

Bases: object

Utilities for manipulating rabbit holes.

classmethod get_rabbit_hole_service()

Retrieve an instance of the Rabbit Hole Service.

Returns:The service that manages rabbit holes.
Return type:RabbitHoleService
classmethod load_rabbit_hole_by_id(rabbit_hole)

Load an instance of a Rabbit Hole by its identifier.

Parameters:rabbit_hole (Union[int, RabbitHole]) – The identifier of a Rabbit Hole.
Returns:An instance of a Rabbit Hole matching the decimal identifier or None if not found.
Return type:Union[RabbitHole, None]

Resources

class CommonResourceUtils

Bases: object

Utilities for retrieving the Tuning files and instances of various resources. (Objects, Snippets, Statistics, etc.).

static convert_str_to_fnv32(text, seed=2166136261, high_bit=True)

Convert a text string into an FNV32 decimal identifier.

Parameters:
  • text (str) – The text to convert.
  • seed (int) – A seed to use when converting. Default value is 2166136261.
  • high_bit (bool) – If True, the high FNV bit will be returned. If False, a low FNV bit will be returned.
Returns:

The text converted to a FNV32 decimal identifier.

Return type:

int

static convert_str_to_fnv64(text, seed=14695981039346656037, high_bit=True)

Convert a text string into an FNV64 decimal identifier.

Parameters:
  • text (str) – The text to convert.
  • seed (int) – A seed to use when converting. Default value is 14695981039346656037.
  • high_bit (bool) – If True, a high bit version of the FNV bit will be returned. If False, a low bit version of the FNV bit will be returned.
Returns:

The text converted to an FNV64 decimal identifier.

Return type:

int

static get_enum_by_int_value(value, enum_type, default_value=None)

Retrieve an enum value by its value.

Parameters:
  • value (int) – The integer value of the enum value to retrieve.
  • enum_type (Any) – The type of enum to retrieve.
  • default_value (Any, optional) – The default value to return if an enum value was not found using the specified name. Default is None.
Returns:

The enum value with a value matching the specified value or the default value if not found.

Return type:

Any

static get_enum_by_name(name, enum_type, default_value=None)

Retrieve an enum value by its name.

Parameters:
  • name (str) – The name of the enum value to retrieve.
  • enum_type (Any) – The type of enum to retrieve.
  • default_value (Any, optional) – The default value to return if an enum value was not found using the specified name. Default is None.
Returns:

The enum value with a name matching the specified name.

Return type:

Any

static get_instance_manager(instance_manager_type)

Get an InstanceManager for the specified type.

Parameters:instance_manager_type (Types) – The type of InstanceManager to get.
Returns:An InstanceManager for the specified type, or None if no InstanceManager is found.
Return type:Union[InstanceManager, None]
static get_resource_key(resource_type, resource_key)

Retrieve the resource key of a resource in the format: 00000000(Type):00000000(Group):00000000000000000(Instance Guid)

Note

Possible Usages:

  • Retrieve the identifier of an Icon to display next to an Interaction in the Pie Menu.
  • Retrieve the identifier of an Image for display in Dialogs or Notifications.
Example Usage:
# This will retrieve the key for the image with identifier 1234
icon_resource_key = CommonResourceUtils.get_resource_key(Types.PNG, 1234)
Parameters:
  • resource_type (Types) – The type of resource being loaded.
  • resource_key (Union[int, str]) – The decimal identifier or string resource key of the resource.
Returns:

The resource key of an instance or None if no instance was found.

Return type:

CommonResourceKey

static load_all_instance_types(instance_type, return_type=Any)

Load all instances of the specified type.

Parameters:
  • instance_type (Types) – The type of instances being loaded.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:

A dictionary of resource keys to Instances of the specified type.

Return type:

Dict[str, Any]

static load_all_instance_values(instance_type, return_type=Any)

Load all instance values of the specified type.

Parameters:
  • instance_type (Types) – The type of instances being loaded.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:

All instance values of the specified type.

Return type:

ValuesView[Any]

static load_all_instances(instance_type, return_type=Any)

Load all instances of the specified type.

Parameters:
  • instance_type (Types) – The type of instances being loaded.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:

An items view of all instances of the specified type. (Resource Key, Instance)

Return type:

ItemsView[str, Any]

static load_all_instances_as_guid_to_instance(instance_type, return_type=Any)

Load all instances of the specified type and convert it to a dictionary mapping of GUID to Instance.

Parameters:
  • instance_type (Types) – The type of instances being loaded.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:

A dictionary of instance GUID to instances of the specified type.

Return type:

Dict[int, Any]

static load_instance(instance_type, instance_id, return_type=Any)

Load an instance of the specified type.

Example Usage 1:
 
# This will retrieve an instance for the Confident mood and will be of type statistics.mood.Mood
mood_instance = CommonResourceUtils.load_instance(Types.MOOD, CommonMoodId.CONFIDENT)
Example Usage 2:
 
# This will retrieve an instance for the Walk Style Angry buff and will be of type buffs.buff.Buff
buff_instance = CommonResourceUtils.load_instance(Types.BUFF, CommonBuffId.WALK_STYLE_ANGRY)
Parameters:
  • instance_type (Types) – The type of instance being loaded.
  • instance_id (int) – The decimal identifier of an instance.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:

An instance of the specified type or None if no instance was found.

Return type:

Any

static load_instance_from_manager(instance_manager, instance_id, return_type=Any)

Load an instance from the specified InstanceManager.

Parameters:
  • instance_manager (InstanceManager) – The InstanceManager an instance will be loaded from.
  • instance_id (int) – The decimal identifier of an instance.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:

An instance of the specified type or None if no instance was found.

Return type:

Any

static load_instances_with_any_tags(resource_type, tags, return_type=Any)

Retrieve all resources that contain the specified tag names within their tuning file.

Note

Possible Usages:

  • Load all Snippet files containing properties with any of the specified tags.
Parameters:
  • resource_type (Types) – The type of resource being loaded.
  • tags (Tuple[str]) – A collection of tag names to locate within a tuning file.
  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:

A collection of resources that contain any of the specified tags.

Return type:

Tuple[Any]

static load_resource_bytes(resource_key, silent_fail=True)

Retrieve the bytes of a resource.

Parameters:
  • resource_key (CommonResourceKey) – The key of the resource.
  • silent_fail (bool, optional) – Set to True to ignore errors if they occur. Set to False to throw errors when they occur. Default is True.
Returns:

An Input Output Byte reader/writer for the resource.

Return type:

BytesIO

static load_resource_bytes_by_name(resource_type, resource_name, fnv64=True, high_bit=False)

Load the bytes of a resource into a Bytes Reader.

Note

This function will only work if the instance key/decimal identifier of the resource equates to the name of the resource.

Parameters:
  • resource_type (Types) – The type of resource being loaded.
  • resource_name (str) – The tuning name of the resource.
  • has_fnv64_identifier (bool, optional) – Set to True to indicate the resource uses a 64 bit identifier. Set to False to indicate the resource uses a 32 bit identifier. Default is True.
  • has_high_bit_identifier (bool, optional) – Set to True to indicate the resource uses a high bit identifier. Set to False to indicate the resource uses a low bit identifier. Default is False.
Returns:

An Input Output Byte reader/writer for the resource or None if a problem occurs.

Return type:

Union[BytesIO, None]

static register_tuning(mod_identity, class_type, tuning_type, tuning_identifier, tuning_contents)

Dynamically register a tuning instance.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod registering the tuning.
  • class_type (Type) – The type of class being registered.
  • tuning_type (Types) – The type of tuning being registered.
  • tuning_id (int) – The decimal identifier of the tuning being registered.
  • tuning_contents (str) – The xml contents of the tuning.

Statistics

Note

To manipulate statistics/commodities of Sims, take a look at CommonSimStatisticUtils

class CommonStatisticUtils

Bases: object

Utilities for manipulating Statistics.

static get_statistic_id(statistic_identifier)

Retrieve the decimal identifier of a Statistic.

Parameters:statistic_identifier (Union[int, BaseStatistic]) – The identifier or instance of a Statistic.
Returns:The decimal identifier of the Statistic or None if the Statistic does not have an id.
Return type:Union[int, None]
static get_statistic_initial_value(statistic_id)

Retrieve the Initial Value of a Statistic.

Parameters:statistic_id (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the Statistic to use.
Returns:The initial value of the statistic.
Return type:float
static get_statistic_instance_manager()

Retrieve the manager that manages all Statistics.

Returns:The manager that manages all Statistics.
Return type:StatisticInstanceManager
static get_statistic_max_value(statistic_id)

Retrieve the Maximum Value of a Statistic.

Parameters:statistic_id (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the Statistic to use.
Returns:The maximum value of the statistic.
Return type:float
static get_statistic_min_value(statistic_id)

Retrieve the Minimum Value of a Statistic.

Parameters:statistic_id (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the Statistic to use.
Returns:The minimum value of the statistic.
Return type:float
static load_statistic_by_id(statistic_id)

Load an instance of a Statistic by its decimal identifier.

Parameters:statistic_id (Union[int, CommonStatisticId, BaseStatistic]) – The decimal identifier of a Statistic.
Returns:An instance of a Statistic matching the decimal identifier or None if not found.
Return type:Union[BaseStatistic, None]

Situations

Note

To manipulate situations of Sims, take a look at CommonSimSituationUtils

class CommonSituationUtils

Bases: object

Utilities for manipulating Situations.

static get_sim_info_for_all_sims_in_running_situations_by_type(situation_type)

Retrieve a SimInfo object for all Sims in a Situation.

Parameters:situation_type (Type[Situation]) – The type of situation to locate.
Returns:A collection of SimInfo for all Sims in the situations that match the specified type.
Return type:Tuple[SimInfo]
static get_sim_info_for_all_sims_in_situation(situation)

Retrieve a SimInfo object for all Sims in a Situation.

Parameters:situation (Situation) – A situation
Returns:A collection of SimInfo for all Sims in the situation.
Return type:Tuple[SimInfo]
static get_situation_guid(situation_identifier)

Retrieve the GUID of a Situation.

Parameters:situation_identifier (Union[int, Situation]) – The identifier or instance of a Situation.
Returns:The GUID of the specified Situation or -1 if it does not have one.
Return type:int
static get_situation_id(situation_identifier)

Retrieve the decimal identifier of a Situation.

Parameters:situation_identifier (Union[int, Situation]) – The identifier or instance of a Situation.
Returns:The decimal identifier of the Situation or None if the Situation does not have an id.
Return type:Union[int, None]
static get_situation_job_guid(situation_job_identifier)

Retrieve the GUID of a Situation Job.

Parameters:situation_job_identifier (Union[int, SituationJob]) – The identifier or instance of a Situation Job.
Returns:The GUID of the specified Situation or -1 if it does not have one.
Return type:int
static get_situation_manager_for_zone(zone_id=None)

Retrieve the situation manager for a zone.

Parameters:zone_id (int, optional) – The zone to retrieve the situation manager of. Default is None, which is the current zone.
Returns:The situation manager for the specified zone.
Return type:SituationManager
static get_situation_name(situation)

Retrieve the Name of a Situation.

Parameters:situation (Situation) – An instance of a Situation.
Returns:The short name of a Situation or None if a problem occurs.
Return type:Union[str, None]
static get_situation_names(situations)

Retrieve the Names of a collection of Situation.

Parameters:situations (Iterator[Situation]) – A collection of Situation instances.
Returns:A collection of names for all specified Situations.
Return type:Tuple[str]
static load_situation_by_id(situation_id)

Load an instance of a Situation by its decimal identifier (GUID).

Parameters:situation_guid (Union[int, CommonSituationId, Situation]) – The decimal identifier of a Situation. (Not to be confused with the instance id)
Returns:An instance of a Situation matching the decimal identifier or None if not found.
Return type:Union[Situation, None]
static locate_first_running_situation_by_tag(situation_type, zone_id=None)

Locate the first running Situation from a Zone by a tag.

Parameters:
  • tag (CommonGameTag) – A tag to search for the situation with.
  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:

A collection of situations from the specified zone that have the specified tag.

Return type:

Tuple[Situation]

static locate_first_running_situation_by_tags(tags: Iterator[sims4communitylib.enums.tags_enum.CommonGameTag], zone_id: int = None) → Optional[<sphinx.ext.autodoc.importer._MockObject object at 0x7f09edd87350>]

locate_first_running_situation_by_tag(situation_type, zone_id=None)

Locate the first running Situation from a Zone by a collection of tags.

Parameters:
  • tags (Iterator[CommonGameTag]) – A list of tags to search for the situation with.
  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:

A collection of situations from the specified zone that have the specified tag.

Return type:

Tuple[Situation]

static locate_first_running_situation_by_type(situation_type, zone_id=None)

Locate the first running Situation from a Zone by its Type.

Parameters:
  • situation_type (Type[Situation]) – The type of situation to search for.
  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:

A collection of situations from the specified zone that have the specified tag.

Return type:

Tuple[Situation]

static locate_running_situation_by_id(situation_id: Union[int, sims4communitylib.enums.situations_enum.CommonSituationId, <sphinx.ext.autodoc.importer._MockObject object at 0x7f09edd87350>], zone_id: int = None) → Optional[<sphinx.ext.autodoc.importer._MockObject object at 0x7f09edd87350>]

locate_situation_by_id(situation_id, zone_id=None)

Locate a running Situation from a Zone by its id.

Parameters:
  • situation_id (Union[int, CommonSituationId, Situation]) – The decimal identifier of a Situation. (Not to be confused with the instance id)
  • zone_id (int, optional) – The zone to retrieve the situation from. Default is None, which is the current zone.
Returns:

The situation from the specified zone that matches the specified id or None if not found.

Return type:

Union[Situation, None]

static locate_running_situations_by_tag(tag, zone_id=None)

Locate all running Situations in a Zone by a tag.

Parameters:
  • tag (CommonGameTag) – A tag to search for situations with.
  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:

A collection of situations from the specified zone that have the specified tag.

Return type:

Tuple[Situation]

static locate_running_situations_by_tags(tags, zone_id=None)

Locate all running Situations in a Zone by a collection of tags.

Parameters:
  • tags (Iterator[CommonGameTag]) – A list of tags to search for situations with.
  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:

A collection of situations from the specified zone that have any of the specified tags.

Return type:

Tuple[Situation]

static locate_running_situations_by_type(situation_type, zone_id=None)

Locate all running Situations in a Zone by Type.

Parameters:
  • situation_type (Type[Situation]) – The type of situation to search for.
  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:

A collection of situations from the specified zone that have the specified tag.

Return type:

Tuple[Situation]

Text

Types

class CommonTypeUtils

Bases: object

Utilities for determining the type of an object.

static is_door(obj)

Determine if an Object is of type Door

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_game_object(obj)

Determine if an object is of type GameObject

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_land(obj)

Determine if an object is of type Terrain or TerrainPoint.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_location(obj)

Determine if an object is of type Location.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_location_point(obj)

Determine if an object is of type _LocationPoint.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_ocean(obj)

Determine if an object is of type Ocean.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_ocean_point(obj)

Determine if an object is of type OceanPoint.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_pool_point(obj)

Determine if an object is of type PoolPoint.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_pool_seat(obj)

Determine if an Object is a Pool Seat.

Parameters:obj – An instance of an Object.
Type:Any
Returns:True, if the Object is a Pool Seat. False, if not.
Return type:bool
static is_script_object(obj)

Determine if an object is of type ScriptObject

Note

GameObjects, Terrain, and Sims are all ScriptObjects. Try also is_game_object(), is_terrain(), and is_sim_instance()

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_sim_info(obj)

Determine if an object is of type SimInfo

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_sim_info_base_wrapper(obj)

Determine if an object is of type SimInfo

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_sim_instance(obj)

Determine if an object is of type Sim

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_sim_or_sim_info(obj)

Determine if an object is either of type Sim or type SimInfo

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_swimming_pool(obj)

Determine if an object is of type SwimmingPool.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_terrain(obj)

Determine if an object is of type Terrain

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_terrain_point(obj)

Determine if an object is of type TerrainPoint.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool
static is_water(obj)

Determine if an object is of type Ocean, OceanPoint, SwimmingPool, or PoolPoint.

Parameters:obj (Any) – The object to check.
Returns:True, if it is. False, if it is not.
Return type:bool