Misc Utilities¶

Location¶

Note

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

Location¶

class CommonLocationUtils¶

Bases: object

Utilities for manipulating locations and lots.

To manipulate the location of Sims, see CommonSimLocationUtils. To manipulate the location of Objects, see CommonObjectLocationUtils.

static apply_surface_level_to_position(position, surface_identifier)¶

Get the position of the surface of an Object.

Parameters:

position (CommonVector3) – The position to update.
surface_identifier (CommonSurfaceIdentifier) – The surface identifier to apply.

Returns:

The position with a surface level applied.

Return type:

CommonVector3

static can_location_be_routed_to(location)¶

Determine if a location can be routed to by a Sim.

Parameters:: location (CommonLocation) – The location to check.
Returns:: True, if the location can be routed to by a Sim. False, it not.
Return type:: bool

static can_position_be_routed_to(position, surface_identifier)¶

Determine if a position and surface can be routed to by a Sim.

Parameters:

position (CommonVector3) – The position to check.
surface_identifier (CommonSurfaceIdentifier) – The surface to check.

Returns:

True, if the position can be routed to by a Sim. False, it not.

Return type:

bool

static current_lot_has_all_traits(lot_trait_ids)¶

Determine if the Current Lot has all of the specified Lot Traits.

Parameters:: lot_trait_ids (Tuple[int]) – A collection of traits to look for.
Returns:: True, if the current lot has all of the specified traits. False, if not.
Return type:: bool

static current_lot_has_any_traits(lot_trait_ids)¶

Determine if the Current Lot has any of the specified Lot Traits.

Parameters:: lot_trait_ids (Tuple[int]) – A collection of traits to look for.
Returns:: True, if the current lot has any of the specified traits. False, if not.
Return type:: bool

static current_lot_has_trait(lot_trait_id)¶

Determine if the Current Lot has the specified Lot Trait.

Parameters:: lot_trait_id (int) – The trait to look for.
Returns:: True, if the current lot has the specified trait. False, if not.
Return type:: bool

static current_venue_allows_role_state_routing()¶

Determine if the current venue allows routing for role states.

Returns:: True, if the venue of the current lot allows routing by role state. False, if not.
Return type:: bool

static current_venue_requires_player_greeting()¶

Determine if the current venue requires player greeting.

Returns:: True, if the venue of the current lot requires the player to be greeted. False, if not.
Return type:: bool

static get_all_block_ids(zone_id)¶

Retrieve a collection of all Block ids for a Zone.

Parameters:: zone_id (int) – The id of the Zone to retrieve the block ids of.
Returns:: A collection of block ids.
Return type:: Tuple[int]

static get_all_block_ids_in_current_zone()¶

Retrieve a collection of all Block Identifiers for the current zone.

Note

A Block Id is essentially an identifier for a Room.

Returns:: A collection of block decimal identifiers.
Return type:: Tuple[int]

static get_all_block_polygons(zone_id)¶

Retrieve all block polygons for a Zone.

Note

A Block is essentially just a Room.

Parameters:: zone_id (int) – A decimal identifier of a Zone.
Returns:: A collection of polygons for the specified Zone.
Return type:: Dict[int, Tuple[Tuple[List[CommonVector3]]]]

static get_all_block_polygons_of_current_zone()¶

Retrieve all block polygons for the current Zone.

Returns:: A dictionary of polygons for the current Zone with the Block Ids as the key.
Return type:: Dict[int, Tuple[Tuple[Polygon]]]

static get_block_id(zone_id, position, surface_level)¶

Retrieve the decimal identifier of the block containing the position.

Parameters:

zone_id (int) – The decimal identifier of a Zone.
position (CommonVector3) – An instance of a vector.
surface_level (int) – The surface level of the position.

Returns:

A decimal identifier of the block containing the position.

Return type:

int

static get_block_id_in_current_zone(position, surface_level)¶

Retrieve the id of the block containing the position.

Note

A Block is the same thing as a Room. This information can be used to determine which Room something is located in as well.

Note

The entirety of Outside has a room id of 0.

Parameters:

position (CommonVector3) – An instance of a vector.
surface_level (int) – The surface level of the position.

Returns:

The id of the block containing the position.

Return type:

int

static get_block_id_in_zone(zone_id, position, surface_level)¶

Retrieve the id of the block containing the position within a specified Zone.

Note

A Block is the same thing as a Room. This information can be used to determine which Room something is located in as well.

Note

The entirety of Outside has a room id of 0.

Parameters:

zone_id (int) – The zone to search.
position (CommonVector3) – An instance of a vector.
surface_level (int) – The surface level of the position.

Returns:

The id of the block containing the position.

Return type:

int

static get_current_lot()¶

Retrieve the current lot.

Returns:: The current Lot.
Return type:: Lot

static get_current_lot_id()¶

Retrieve the decimal identifier of the current Lot.

Returns:: The decimal identifier of the current Lot or -1 if a problem occurs.
Return type:: int

classmethod get_current_region()¶

Retrieve the current region.

Returns:: The current region.
Return type:: Region

classmethod get_current_region_id()¶

Retrieve the id of the current region.

Returns:: The id of the current region.
Return type:: int

classmethod get_current_venue()¶

Retrieve the current venue.

Returns:: The current venue.
Return type:: Venue

classmethod get_current_venue_id()¶

Retrieve the id of the current venue.

Returns:: The id of the current venue.
Return type:: int

classmethod get_current_venue_type()¶

Retrieve the type of the current venue.

Returns:: The VenueType of the current lot.
Return type:: VenueTypes

classmethod get_current_world_id()¶

Retrieve the identifier of the World which the current Zone is in.

Returns:: The identifier of the World which the current Zone is in.
Return type:: int

static get_current_zone()¶

Retrieve the current zone.

Returns:: The current Zone
Return type:: Zone

static get_current_zone_id()¶

Retrieve the current zone id.

Returns:: The identifier of the current Zone.
Return type:: int

static get_current_zone_plex_id()¶

Retrieve the plex id of the current zone.

Note

A plex id is basically a Room location.

Returns:: The ID of the current zone plex or 0 if the current zone does not have a plex id.
Return type:: int

static get_current_zone_world_description_id()¶

Retrieve the world description id of the current Zone.

Returns:: The world description id of the current Zone.
Return type:: int

static get_current_zone_world_id()¶

Retrieve the world id of the current Zone.

Returns:: The world id of the current Zone.
Return type:: int

static get_lot_corners(lot)¶

Retrieve the corners of a Lot.

Returns:: A collection of corners of the specified Lot.
Return type:: Tuple[Any]

static get_lot_corners_of_current_lot()¶

Retrieve the corners of the current Lot.

Returns:: A collection of corners on the current Lot.
Return type:: Tuple[Any]

static get_lot_id(lot)¶

Retrieve the decimal identifier of a Lot.

Parameters:: lot (Lot) – An instance of a Lot.
Returns:: The decimal identifier of the specified lot or -1 if a problem occurs.
Return type:: int

static get_lot_traits(zone_id)¶

Retrieve the Lot Traits of a Lot with the specified identifier.

Parameters:: zone_id (int) – The lot to retrieve the traits of.
Returns:: A collection of Lot Traits for the specified lot.
Return type:: Tuple[ZoneModifier]

static get_lot_traits_of_current_lot()¶

Retrieve the Lot Traits of the Current Lot.

Returns:: A collection of Lot Traits for the current lot.
Return type:: Tuple[ZoneModifier]

static get_plex_id(zone_id)¶

Retrieve the plex id of a Zone.

Returns:: The Plex ID of the specified zone or 0 if it was not found.
Return type:: int

static get_plex_id_for_zone(zone)¶

Retrieve the plex id for a Zone.

Returns:: The Plex ID of the specified zone or -1 if it was not found.
Return type:: int

classmethod get_region_id(region)¶

Retrieve the id of a region.

Returns:: The id of a region.
Return type:: int

classmethod get_street_by_world_id(world_id)¶

Retrieve a Street instance using a World Id.

Parameters:: world_id (int) – The identifier of the World to use.
Returns:: The Street instance of the specified World.
Return type:: Street

classmethod get_street_by_zone_id(zone_id)¶

Retrieve the Street instance for a Zone.

Parameters:: zone_id (int) – The identifier of the Zone to use.
Returns:: The Street instance of the specified zone.
Return type:: Street

classmethod get_street_of_current_zone()¶

get_street_from_current_zone()

Retrieve a Street instance using the current Zone.

Returns:: The Street instance for the current Zone.
Return type:: Street

classmethod get_street_service()¶

Retrieve an instance of the street service.

Returns:: An instance of the street service.
Return type:: StreetService

static get_surface_height_at(x, z, routing_surface)¶

Calculate the height of a surface.

Parameters:

x (float) – The x position of the surface.
z (float) – The z position of the surface.
routing_surface (CommonSurfaceIdentifier) – The surface.

Returns:

The height of the surface.

Return type:

float

classmethod get_venue_by_zone_id(zone_id)¶

Retrieve the Venue for a Zone.

Parameters:: zone_id (int) – The identifier of a Zone.
Returns:: The Venue instance for the specified Zone.
Return type:: Venue

classmethod get_venue_id(venue)¶

Retrieve the id of a venue.

Returns:: The id of a venue.
Return type:: int

classmethod get_venue_of_current_lot()¶

Retrieve a Venue for the current lot.

Returns:: The Venue of the current lot.
Return type:: Venue

classmethod get_venue_service(zone)¶

Get the service for Venues for a Zone.

Parameters:: zone (Union[int, Zone]) – The zone to retrieve the service from.
Returns:: The venue service for the specified zone or None if no service found.
Return type:: Union[VenueService, None]

classmethod get_venue_service_for_current_zone()¶

Get the service for Venues for the current Zone.

Returns:: The venue service for the current zone.
Return type:: VenueService

classmethod get_venue_type_by_zone_id(zone_id)¶

Retrieve the Venue type of a Zone.

Returns:: The VenueType of the specified Zone.
Return type:: VenueTypes

classmethod get_world_id_by_zone_id(zone_id)¶

Retrieve the identifier of the World which a Zone is in.

Parameters:: zone_id (int) – The identifier of the zone to use.
Returns:: The identifier of the World which a Zone is in.
Return type:: int

static get_zone(zone, allow_unloaded_zones=False)¶

Retrieve a Zone instance.

Parameters:

zone (Union[int, Zone]) – The identifier of a Zone.
allow_unloaded_zones (bool, optional) – If set to True, Zones that are currently not loaded (or have not been loaded) will be considered. If set to False, Zones that have yet to be loaded will not be considered. Default is False.

Returns:

The Zone with the specified zone id or None if it was not found.

Return type:

Zone

static get_zone_id(zone)¶

Retrieve the identifier of the specified Zone.

Parameters:: zone (Zone) – The Zone to get the identifier of.
Returns:: The identifier of the specified Zone.
Return type:: int

static get_zone_lot(zone)¶

Retrieve the lot of a Zone.

Parameters:: zone (Zone) – An instance of a Zone.
Returns:: The Lot within the specified Zone or None if a problem occurs.
Return type:: Union[Lot, None]

static get_zone_world_description_id(zone_id)¶

Retrieve the world description id of the a Zone.

Parameters:: zone_id (int) – The decimal identifier of a Zone.
Returns:: The world description id of the the specified Zone.
Return type:: int

static get_zone_world_id(zone_id)¶

Retrieve the world id of the a Zone.

Parameters:: zone_id (int) – The decimal identifier of a Zone.
Returns:: The world id of the specified Zone.
Return type:: int

classmethod is_current_region(region)¶

Determine if a region is the current one.

Parameters:: region (Union[int, CommonRegionId, Region]) – The region to check.
Returns:: True, if the specified region is the current one. False, if not.
Return type:: bool

static is_current_venue_residential()¶

Determine if a venue is residential.

Returns:: True, if the venue of the current lot is residential. False, if not.
Return type:: bool

static is_location_outside_current_lot(location)¶

Determine if a location is outside of the current lot or not.

Parameters:: location (CommonLocation) – The Location to check.
Returns:: True, if the location is outside of the current lot. False, if not.
Return type:: bool

static is_location_outside_lot(location, zone_id)¶

Determine if a location is outside of the Lot with the specified identifier.

Parameters:

location (CommonLocation) – The Location to check.
zone_id (int) – The identifier of a Zone to check for the Location to be outside of.

Returns:

True, if location is outside of the Lot with the specified lot_id. False, if not.

Return type:

bool

static is_location_within_range_of_location(location_a, location_b, distance_in_squares)¶

Determine if Location A is within a certain distance of Location B.

Parameters:

location_a (CommonLocation) – The first location.
location_b (CommonLocation) – The second location.
distance_in_squares (float) – A unit measured in squares. 1 square is the size of 1 square in the Build/Buy mode visual grid. For comparison, a dining chair would be 1 square by 1 square. 0.5 would be half a square, or half a dining chair.

Return type:

bool

Returns:

True, if the distance between Location A and Location B is less than or equal to the specified distance in squares. False, if not.

Returns:

bool

static is_position_on_current_lot(position)¶

Determine if a sim is on the current lot.

Parameters:: position (CommonVector3) – The position to check.
Returns:: True, if the specified position is within the bounds of the current lot. False, if not.
Return type:: bool

static is_position_on_lot(position, lot)¶

Determine if a Position is located on a Lot.

Parameters:

position (CommonVector3) – An instance of a CommonVector
lot (Lot) – An instance of a Lot.

Returns:

True, if the Sim is on the specified Lot. False, if not.

Return type:

bool

static is_position_within_range_of_position(position_a, position_b, distance_in_squares)¶

Determine if Position A is within a certain distance of Position B.

Parameters:

position_a (CommonVector3) – The first position.
position_b (CommonVector3) – The second position.
distance_in_squares (float) – A unit measured in squares. 1 square is the size of 1 square in the Build/Buy mode visual grid. For comparison, a dining chair would be 1 square by 1 square. 0.5 would be half a square, or half a dining chair.

Return type:

bool

Returns:

True, if the distance between Position A and Position B is less than or equal to the specified distance in squares. False, if not.

Returns:

bool

classmethod load_region_by_id(region)¶

Load an instance of a Region by its identifier.

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

classmethod load_venue_by_guid(venue)¶

Load an instance of a Region by its identifier.

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

static lot_has_all_traits(zone_id, lot_trait_ids)¶

Determine if a Lot has all of the specified Lot Traits.

Parameters:

zone_id (int) – The identifier of the zone to check.
lot_trait_ids (Tuple[int]) – A collection of traits to look for.

Returns:

True, if the specified lot has all of the specified traits. False, if not.

Return type:

bool

static lot_has_any_traits(zone_id, lot_trait_ids)¶

Determine if a Lot has any of the specified Lot Traits.

Parameters:

zone_id (int) – The identifier of the zone to check.
lot_trait_ids (Tuple[int]) – A collection of traits to look for.

Returns:

True, if the specified lot has any of the specified traits. False, if not.

Return type:

bool

static lot_has_trait(zone_id, lot_trait_id)¶

Determine if a Lot has the specified Lot Trait.

Parameters:

zone_id (int) – The identifier of the zone to check.
lot_trait_id (int) – The trait to look for.

Returns:

True, if the specified lot has the specified trait. False, if not.

Return type:

bool

Terrain¶

class CommonTerrainUtils¶

Bases: CommonTerrainLocationUtils

An obsolete utility for manipulating terrain location. Use CommonTerrainLocationUtils from sims4communitylib.utils.terrain.common_terrain_location_utils instead.

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.

Return type:

bool

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.

Return type:

None

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.

Return type:

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.

Return type:

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, desired_user_level)¶

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 (bool) – 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_track_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=False)¶

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 (bool) – 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=objects.components.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. :rtype: None

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.

classmethod load_arrow_left_icon()¶

Get the Resource Key for the ARROW_LEFT_ICON.

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

classmethod load_arrow_navigate_into_icon()¶

Get the Resource Key for the ARROW_NAVIGATE_INTO_ICON.

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

classmethod load_arrow_right_icon()¶

Get the Resource Key for the ARROW_RIGHT_ICON.

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

classmethod load_blank_square_icon()¶

Get the Resource Key for the BLANK_SQUARE_ICON.

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

classmethod load_checked_circle_icon()¶

Get the Resource Key for the CHECKED_CIRCLE_ICON.

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

classmethod load_checked_square_icon()¶

Get the Resource Key for the CHECKED_SQUARE_ICON.

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

classmethod load_filled_circle_icon()¶

Get the Resource Key for the FILLED_CIRCLE_ICON.

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

classmethod load_icon_by_id(icon)¶

Load an instance of an Icon by its identifier.

Parameters:: icon (Union[int, CommonIconId, CommonInt]) – The identifier of an Icon.
Returns:: An instance of an Icon matching the decimal identifier or None if not found.
Return type:: Union[Any, None]

classmethod load_question_mark_icon()¶

Get the Resource Key for the QUESTION_MARK_ICON.

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

classmethod load_six_sided_dice_icon()¶

Get the Resource Key for the SIX_SIDED_DICE_ICON.

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

classmethod load_text_next_icon()¶

Get the Resource Key for the TEXT_NEXT_SQUARE_ICON.

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

classmethod load_text_prev_icon()¶

Get the Resource Key for the TEXT_PREV_SQUARE_ICON.

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

classmethod load_unchecked_square_icon()¶

Get the Resource Key for the UNCHECKED_SQUARE_ICON.

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

classmethod load_unfilled_circle_icon()¶

Get the Resource Key for the UNFILLED_CIRCLE_ICON.

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

classmethod 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

class CommonInteractionUtils¶

Bases: object

Utilities for manipulating Interactions.

static get_instance_manager()¶

Retrieve the instance manager that manages all tunables for interactions.

Returns:: The instance manager that manages all tunables for interactions.
Return type:: InteractionInstanceManager

static get_interaction_display_name(interaction, tokens=())¶

Retrieve the display name of an interaction.

Parameters:

interaction (Interaction) – An instance of an interaction.
tokens (Iterator[Any]) – A collection of tokens to format into the display name.

Returns:

An instance of type LocalizedString or None if a problem occurs.

Return type:

Union[LocalizedString, None]

static get_interaction_id(interaction_identifier)¶

Retrieve the decimal identifier of an Interaction.

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

static get_interaction_short_name(interaction)¶

Retrieve the Short Name of an Interaction.

Parameters:: interaction (Interaction) – An instance of an interaction.
Returns:: The short name of an interaction or None if a problem occurs.
Return type:: Union[str, None]

static get_interaction_short_names(interactions)¶

Retrieve the Short Names of a collection of Interactions.

Parameters:: interactions (Iterator[Interaction]) – A collection of interaction instances.
Returns:: A collection of short names of all interaction instances.
Return type:: Tuple[str]

static get_pick_info_from_interaction_context(interaction_context)¶

Retrieve the pick info of an interaction context.

Parameters:: interaction_context (InteractionContext) – An interaction context.
Returns:: The pick info of the interaction context or None, if not found.
Return type:: PickInfo

static get_picked_position_from_interaction_context(interaction_context)¶

Retrieve the picked position from an interaction context.

Parameters:: interaction_context (InteractionContext) – An interaction context.
Returns:: The picked position from the interaction context or None if a problem occurs.
Return type:: Union[CommonVector3, None]

static get_picked_routing_position_from_interaction_context(interaction_context)¶

Retrieve the picked routing position from an interaction context.

Parameters:: interaction_context (InteractionContext) – An interaction context.
Returns:: The picked routing position with the routing surface applied to it from the interaction context or None if a problem occurs.
Return type:: Union[CommonVector3, None]

static get_picked_routing_surface_from_interaction_context(interaction_context)¶

Retrieve the picked routing surface from an interaction context.

Parameters:: interaction_context (InteractionContext) – An interaction context.
Returns:: The picked routing surface from the interaction context or None if a problem occurs.
Return type:: Union[CommonSurfaceIdentifier, None]

static get_picked_routing_surface_level_from_interaction_context(interaction_context)¶

Retrieve the picked routing surface level from an interaction context.

Parameters:: interaction_context (InteractionContext) – An interaction context.
Returns:: The picked routing surface level from the interaction context or None if a problem occurs.
Return type:: Union[int, None]

static has_all_appropriateness_tags(interaction, appropriateness_tags)¶

Determine if an interaction has Appropriateness Tags

Parameters:

interaction (Interaction) – An instance of an interaction.
appropriateness_tags (Iterator[CommonGameTag]) – A collection of appropriateness tags.

Returns:

True, if the Interaction has all the specified appropriateness tags. False, if not.

Return type:

bool

static has_all_static_commodities(interaction, static_commodity_ids)¶

Determine if an interaction has all the specified static commodities.

Parameters:

interaction (Interaction) – An instance of an interaction.
static_commodity_ids (Iterator[int], optional) – A collection of static commodity ids.

Returns:

True, if the interaction has all the specified static commodities. False, if not.

Return type:

bool

static has_any_appropriateness_tags(interaction, appropriateness_tags)¶

Determine if an interaction has Appropriateness Tags

Parameters:

interaction (Interaction) – An instance of an interaction.
appropriateness_tags (Iterator[CommonGameTag]) – A collection of appropriateness tags.

Returns:

True, if the Interaction has any of the specified appropriateness tags. False, if not.

Return type:

bool

static has_any_static_commodities(interaction, static_commodity_ids)¶

Determine if an interaction has any of the specified static commodities.

Parameters:

interaction (Interaction) – An instance of an interaction.
static_commodity_ids (Iterator[int], optional) – A collection of static commodity ids.

Returns:

True, if the interaction has any of the specified static commodities. False, if not.

Return type:

bool

static is_immediate_super_interaction(interaction)¶

Determine if an interaction is an Immediate Super interaction.

Parameters:: interaction (Interaction) – An instance of an Interaction.
Return type:: bool
Returns:: True, if the interaction is an Immediate Super interaction. False, if not.

static is_mixer_interaction(interaction)¶

Determine if an interaction is a Mixer interaction.

Parameters:: interaction (Interaction) – An instance of an Interaction.
Return type:: bool
Returns:: True, if the interaction is a Mixer interaction. False, if not.

static is_social_mixer_interaction(interaction)¶

Determine if an interaction is a Social Mixer interaction.

Parameters:: interaction (Interaction) – An instance of an Interaction.
Return type:: bool
Returns:: True, if the interaction is a Social Mixer interaction. False, if not.

static is_social_super_interaction(interaction)¶

Determine if an interaction is a Social Super interaction.

Parameters:: interaction (Interaction) – An instance of an Interaction.
Return type:: bool
Returns:: True, if the interaction is a Social Super interaction. False, if not.

static is_super_interaction(interaction)¶

Determine if an interaction is a Super interaction.

Parameters:: interaction (Interaction) – An instance of an Interaction.
Return type:: bool
Returns:: True, if the interaction is a Super interaction. False, if not.

static load_interaction_by_id(interaction_id)¶

Load an instance of an Interaction by its decimal identifier.

Parameters:: interaction_id (Union[int, CommonInteractionId, Interaction]) – The decimal identifier of an Interaction.
Returns:: An instance of an Interaction matching the decimal identifier or None if not found.
Return type:: Union[Interaction, None]

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:

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=typing.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=typing.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=typing.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=typing.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=typing.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=typing.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=typing.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, has_fnv64_identifier=True, has_high_bit_identifier=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_id, 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.

Service NPC¶

class CommonServiceNPCUtils¶

Bases: _HasS4CLClassLog

Utilities for NPC Services.

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:: The identifier for the log
Return type:: str

classmethod get_service_npc_service(zone)¶

Retrieve the Service for Service NPCs tied to a Zone.

Parameters:: zone (Zone) – The zone the service is tied to.
Returns:: The service for Service NPCs tied to the specified zone or None if no service is found.
Return type:: Union[ServiceNpcService, None]

classmethod get_service_npc_service_for_current_zone()¶

Retrieve the Service for Service NPCs tied to the current Zone.

Returns:: The service for Service NPCs tied to the current zone.
Return type:: ServiceNpcService

Statistics¶

Note

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

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_guid)

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(tag, 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, zone_id=None)

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, zone_id=None)

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¶

class CommonTextUtils¶

Bases: object

Utilities for manipulating text.

static capitalize(value)¶

Capitalize the first character of a value.

Parameters:: value (str) – The value to modify.
Returns:: The text, but with the first character capitalized.
Return type:: str

static convert_to_hex32_string(value)¶

Convert a value into a 32 bit hexadecimal string. This function will keep any leading or trailing zeros.

Parameters:: value (int) – The value to convert.
Returns:: The value as a Hexadecimal string.
Return type:: str

static proper_case_hex(hex_value)¶

Modify the casing of a hex value so that everything after the “0x” portion is capitalized.

Parameters:: hex_value (str) – The value to modify.
Returns:: The value, but with everything after the “0x” portion capitalized.
Return type:: str

static to_truncated_decimal(value, num_of_decimal_points=2)¶

Create a string of a float value with a number of decimal points truncated.

Parameters:

value (float) – The value to truncate.
num_of_decimal_points (int, optional) – The number of decimal places to leave in the string. Default is 2.

Returns:

A string representation of the value truncated to the number of decimal places.

Return type:

str

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 (Any) – 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