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.
-
static
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.
-
classmethod
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.
-
static
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]
-
classmethod
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]
-
static
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]
-
static
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
-
static
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
-
classmethod
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
-
static
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
-
static
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
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
-
static
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: - position_one (CommonVector3) – An instance of a Vector.
- position_two (CommonVector3) – An instance of a Vector.
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:
-
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
-
static
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]
-
classmethod
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
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.
-
static
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]
-
static
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]
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]
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]
-
static
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()
, andis_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
-
static