Sim Utilities¶

Fundamentals¶

Names¶

class CommonSimNameUtils¶

Bases: object

Utilities for manipulating the name of Sims.

static create_random_first_name(gender, species=CommonSpecies.HUMAN, sim_name_type=CommonSimNameType.DEFAULT)¶

Create a random first name.

Parameters:	gender (CommonGender) – A gender. species (CommonSpecies, optional) – A species. Default is HUMAN. sim_name_type (CommonSimNameType, optional) – The Sim Name Type determines from which list of names to randomize the name from. Default is CommonSimNameType.DEFAULT.
Returns:	A random first name.
Return type:	str

static create_random_last_name(gender, species=CommonSpecies.HUMAN, sim_name_type=CommonSimNameType.DEFAULT)¶

Create a random last name.

Parameters:	gender (CommonGender) – A gender. species (CommonSpecies, optional) – A species. Default is HUMAN. sim_name_type (CommonSimNameType, optional) – The Sim Name Type determines from which list of names to randomize the name from. Default is CommonSimNameType.DEFAULT.
Returns:	A random last name.
Return type:	str

static get_first_name(sim_info)¶

Retrieve the First Name of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to retrieve the first name of.
Returns:	The first name of the specified Sim.
Return type:	str

static get_full_name(sim_info)¶

Retrieve the full name of a Sim.

Note

Resulting Full Name: ‘{First} {Last}’

Parameters:	sim_info (SimInfo) – The Sim to retrieve the full name of.
Returns:	The full name of the specified Sim.
Return type:	str

static get_full_names(sim_info_list)¶

Retrieve a collection of full names for the specified Sims.

Note

Resulting Full Names: (‘{First} {Last}’, ‘{First} {Last}’, ‘{First} {Last}’, …)

Parameters:	sim_info_list (Tuple[SimInfo]) – A collection of Sims
Returns:	A collection of full names of the specified Sims.
Return type:	Tuple[str]

static get_last_name(sim_info)¶

Retrieve the Last Name of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to retrieve the last name of.
Returns:	The last name of the specified Sim.
Return type:	str

static has_name(sim_info)¶

Determine if a Sim has a name.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the specified Sim has a name. False, if not.
Return type:	bool

static set_first_name(sim_info, first_name)¶

Retrieve the First Name of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to set the first name of. first_name (str) – The first name you want the Sim to have.

static set_last_name(sim_info, last_name)¶

Retrieve the Last Name of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to set the last name of. last_name (str) – The last name you want the Sim to have.

Age¶

class CommonAgeUtils¶

Bases: object

Utilities for manipulating Ages of Sims.

classmethod are_same_age(sim_info, other_sim_info)¶

Determine if two Sims are the same Age.

Parameters:	sim_info (SimInfo) – The Sim to check. other_sim_info (SimInfo) – The other Sim to compare to.
Returns:	True, if both Sims are the same Age.
Return type:	bool

classmethod convert_to_approximate_age(age)¶

Convert an age to an approximate Age value.

Parameters:	age (Union[CommonAge, Age, int]) – An Age.
Returns:	The specified Age converted into an approximate Age value.
Return type:	Age

classmethod get_age(sim_info, exact_age=False)¶

Retrieve the Age of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to get the Age of. exact_age (bool, optional) – If set to True, the exact age of the Sim will be returned (Age 24 will be returned as 24). If set to False, the age of the Sim rounded to the nearest Age value will be returned. (Age 24 will be returned as Age.YOUNGADULT). Default is False.
Returns:	The Age of the Sim or None if a problem occurs.
Return type:	Union[Age, None]

classmethod get_percentage_total_days_sim_has_been_in_their_current_age(sim_info)¶

Retrieve the percentage total days a Sim has been in their current age.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The percentage total days the specified Sim has been in their current age.
Return type:	float

classmethod get_total_days_sim_has_been_in_their_current_age(sim_info)¶

Retrieve the total number of days a Sim has been in their current Age.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	A total number of days the specified Sim has been in their current Age.
Return type:	float

classmethod get_total_days_to_age_up(sim_info)¶

Retrieve the total number of days required for the next age of a Sim to be required. (Not to be confused with the amount of days they have left)

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The total number of days required for the specified Sim to reach their next age.
Return type:	float

classmethod get_total_days_until_sim_ages_up(sim_info)¶

Retrieve the total number of days a Sim has left until they age up.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The total number of days the specified Sim has left until they age up.
Return type:	int

classmethod has_age(sim_info, age, exact_age=False)¶

Determine if a Sim has a matching Age.

Parameters:	sim_info (SimInfo) – An instance of a Sim. age (Union[CommonAge, Age, int]) – The age to check. exact_age (bool, optional) – If True, the Sims exact age will be used. If False, the Sims approximate age will be used. In most cases, this should be False. Default is False.
Returns:	True, if the age of the specified Sim matches the specified age. False, if not.
Return type:	bool

classmethod has_any_age(sim_info, ages, exact_age=False)¶

Determine if a Sim has an Age matching any of the specified Ages.

Parameters:	sim_info (SimInfo) – An instance of a Sim. ages (Iterator[Union[CommonAge, Age, int]]) – The ages to check. exact_age (bool, optional) – If True, the Sims exact age will be used. If False, the Sims approximate age will be used. In most cases, this should be False. Default is False.
Returns:	True, if the age of the specified Sim matches any of the specified ages. False, if not.
Return type:	bool

classmethod is_adult(sim_info)¶

Determine if a Sim is either a Young Adult or an Adult.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_adult_age(age)¶

Determine if an Age is a Young Adult or an Adult.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_adult_or_elder(sim_info)¶

Determine if a Sim is a Young Adult, an Adult, or an Elder.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_adult_or_elder_age(age)¶

Determine if an age is Young Adult, Adult, or Elder.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_age_available_for_sim(sim_info, age)¶

Determine if an Age is available for a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. age (CommonAge) – The age to check.
Returns:	True, if the specified Age is available for the specified Sim. False, if not.
Return type:	bool

classmethod is_baby(sim_info)¶

Determine if a Sim is a Baby.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_baby_age(age)¶

Determine if an Age is a Baby.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_baby_child_or_toddler(sim_info)¶: Warning

Obsolete: Don’t use this function. Use the :func:’~is_baby_toddler_or_child’ function instead.

classmethod is_baby_infant_or_toddler(sim_info)¶

Determine if a Sim is a Baby, Infant, or a Toddler.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_baby_infant_or_toddler_age(age)¶

Determine if an age is Baby or Toddler.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_baby_infant_toddler_or_child(sim_info)¶

Determine if a Sim is a Baby, Infant, a Toddler, or a Child.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_baby_infant_toddler_or_child_age(age)¶

Determine if an age is Baby, Infant, Toddler, or Child.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_baby_or_toddler(sim_info)¶

Determine if a Sim is a Baby or a Toddler.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_baby_or_toddler_age(age)¶

Determine if an age is Baby or Toddler.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_baby_toddler_or_child(sim_info)¶

Determine if a Sim is a Baby, a Toddler, or a Child.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_baby_toddler_or_child_age(age)¶

Determine if an age is Baby, Toddler, or Child.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_child(sim_info)¶

Determine if a Sim is a Child.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_child_age(age)¶

Determine if an Age is a Child.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_child_or_teen(sim_info)¶

Determine if a Sim is a Child or a Teen.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_child_or_teen_age(age)¶

Determine if an age is Child or Teen.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_elder(sim_info)¶

Determine if a Sim is an Elder.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_elder_age(age)¶

Determine if an Age is an Elder.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_infant(sim_info)¶

Determine if a Sim is an Infant.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_infant_age(age)¶

Determine if an Age is an Infant.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_mature_adult(sim_info)¶

Determine if a Sim is an Adult.

Note

This function does not determine whether they are a Young Adult or not. Use ‘is_adult’ to check for both.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_mature_adult_age(age)¶

Determine if an Age is an Adult.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_mature_adult_or_elder(sim_info)¶

Determine if a Sim is an Adult or an Elder.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_mature_adult_or_elder_age(age)¶

Determine if an age is Adult or Elder.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_older_than(sim_info, age, or_equal=False)¶

Determine if a Sim is older than the specified Age.

Parameters:	sim_info (SimInfo) – The Sim to check. age (Union[CommonAge, Age, int]) – The age to check with. or_equal (bool) – If True, the age check will be older than or equal to. If False, the Age check will be older than.
Returns:	True, if the Sim is older than the specified Age or equal to the specified Age if or_equal is True. False, if not.
Return type:	bool

classmethod is_teen(sim_info)¶

Determine if a Sim is a Teen.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_teen_adult_or_elder(sim_info)¶

Determine if a Sim is a Teen, a Young Adult, an Adult, or an Elder.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_teen_adult_or_elder_age(age)¶

Determine if an age is Teen, Young Adult, Adult, or Elder.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_teen_age(age)¶

Determine if an Age is a Teen.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_teen_or_adult(sim_info)¶

Determine if a Sim is a Teen, a Young Adult, or an Adult.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_teen_or_adult_age(age)¶

Determine if an age is Teen, Young Adult, or Adult.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_teen_or_young_adult(sim_info)¶

Determine if a Sim is a Teen or a Young Adult.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_teen_or_young_adult_age(age)¶

Determine if an age is Teen or Young Adult.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_toddler(sim_info)¶

Determine if a Sim is a Toddler.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_toddler_age(age)¶

Determine if an Age is a Toddler.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_toddler_or_child(sim_info)¶

Determine if a Sim is a Toddler or a Child.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_toddler_or_child_age(age)¶

Determine if an age is Toddler or Child.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_young_adult(sim_info)¶

Determine if a Sim is a Young Adult.

Note

This function does not determine whether they are an Adult or not. Use “is_adult” to check for both.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is. False, if the Sim is not.
Return type:	bool

classmethod is_young_adult_age(age)¶

Determine if an Age is a Young Adult.

Parameters:	age (Union[CommonAge, Age, int]) – The age to check.
Returns:	True, if it is. False, if it is not.
Return type:	bool

classmethod is_younger_than(sim_info, age, or_equal=False)¶

Determine if a Sim is younger than the specified Age.

Parameters:	sim_info (SimInfo) – The Sim to check. age (Union[CommonAge, Age, int]) – The age to check with. or_equal (bool) – If True, the age check will be younger than or equal to. If False, the age check will be younger than.
Returns:	True, if the Sim is younger than the specified Age or equal to the specified age if or_equal is True. False, if not.
Return type:	bool

classmethod set_age(sim_info, age)¶

Set the Age of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to set the Age of. age (Union[CommonAge, Age, int]) – The Age to set the Sim to.
Returns:	True, if the Age was set successfully. False, if not.
Return type:	bool

classmethod set_percentage_total_days_sim_has_been_in_their_current_age(sim_info, percentage_progress)¶

Set the percentage total days a Sim has been in their current age.

Parameters:	sim_info (SimInfo) – An instance of a Sim. percentage_progress (int) – A percentage total days a Sim has been in their current age.

classmethod set_total_days_sim_has_been_in_their_current_age(sim_info, days)¶

Set the total number of days of progress made towards the next age of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. days (float) – The total number of days the Sim has been in their current age.

Species¶

class CommonSpeciesUtils¶

Bases: object

Utilities for manipulating and checking the Species of Sims.

static are_same_species(sim_info, other_sim_info)¶

Determine if two sims are of the same species.

Note

Extended Species are also compared (Large Dog, Small Dog, etc.)

Parameters:	sim_info (SimInfo) – The Sim to check. other_sim_info (SimInfo) – The Sim to compare to.
Returns:	True, if both Sims are the same species. False, if not.
Return type:	bool

static get_species(sim_info)¶

Retrieve the Species of a sim.

Parameters:	sim_info (SimInfo) – The Sim to get the Species of.
Returns:	The Species of the Sim or None if the Sim does not have a Species.
Return type:	Union[Species, None]

static is_animal(sim_info)¶

Determine if a Sim is an Animal.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Animal (Large Dog, Small Dog, Cat, Fox). False, if not.
Return type:	bool

static is_animal_species(species)¶

Determine if a Species is an Animal.

Parameters:	species (Union[Species, int]) – The Species to check.
Returns:	True, if the Species is a Animal Species (Large Dog, Small Dog, Cat, or Fox). False, if not.
Return type:	bool

static is_cat(sim_info)¶

Determine if a Sim is a Cat.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Cat. False, if not.
Return type:	bool

static is_cat_species(species)¶

Determine if a Species is a Cat.

Parameters:	species (Union[Species, int]) – The Species to check.
Returns:	True, if the Species is a Cat Species. False, if not.
Return type:	bool

static is_dog(sim_info)¶

Determine if a Sim is a Dog.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Dog (Large Dog, Small Dog). False, if not.
Return type:	bool

static is_dog_species(species)¶

Determine if a Species is a Dog.

Parameters:	species (Union[Species, int]) – The Species to check.
Returns:	True, if the Species is a Dog Species (Large Dog, Small Dog). False, if not.
Return type:	bool

static is_fox(sim_info)¶

Determine if a Sim is a Fox.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Fox. False, if not.
Return type:	bool

static is_fox_species(species)¶

Determine if a Species is a Fox.

Parameters:	species (Union[Species, int]) – The Species to check.
Returns:	True, if the Species is a Fox Species. False, if not.
Return type:	bool

static is_horse(sim_info)¶

Determine if a Sim is a Horse.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Horse. False, if not.
Return type:	bool

static is_horse_species(species)¶

Determine if a Species is a Horse.

Parameters:	species (Union[Species, int]) – The Species to check.
Returns:	True, if the Species is a Horse Species. False, if not.
Return type:	bool

static is_human(sim_info)¶

Determine if a Sim is a Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Human. False, if not.
Return type:	bool

static is_human_species(species)¶

Determine if a Species is a Human.

Parameters:	species (Union[Species, int]) – The Species to check.
Returns:	True, if the Species is Human. False, if not.
Return type:	bool

static is_large_dog(sim_info)¶

Determine if a Sim is a Large Dog.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Large Dog. False, if not.
Return type:	bool

static is_pet(sim_info)¶

Determine if a Sim is a Pet.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Pet (Large Dog, Small Dog, Cat). False, if not.
Return type:	bool

static is_pet_species(species)¶

Determine if a Species is a Pet.

Parameters:	species (Union[Species, int]) – The Species to check.
Returns:	True, if the Species is a Pet Species (Large Dog, Small Dog, Cat). False, if not.
Return type:	bool

static is_small_dog(sim_info)¶

Determine if a Sim is a Small Dog.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Small Dog. False, if not.
Return type:	bool

static set_species(sim_info, species)¶

Set the Species of a sim.

Parameters:	sim_info (SimInfo) – The Sim to set the Species of. species (Union[Species, int]) – The Species to set the Sim to.
Returns:	True, if successful. False, if not.
Return type:	bool

Age and Species¶

class CommonAgeSpeciesUtils¶

Bases: object

Utilities for checking the Age and Species of Sims.

static are_same_age_and_species(sim_info, other_sim_info)¶

Determine if two Sims are the same Age and the same Species.

Parameters:	sim_info (SimInfo) – The Sim to check. other_sim_info (SimInfo) – The other Sim to compare to.
Returns:	True, if both Sims are the same Age and Species. False, if they are not.
Return type:	bool

static is_adult_animal(sim_info)¶

Determine if a sim is an Adult Animal (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Adult Pet (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_adult_human(sim_info)¶

Determine if a sim is a Young Adult or Adult Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Young Adult or Adult Human. False, if the Sim is not.
Return type:	bool

static is_adult_human_or_animal(sim_info)¶

Determine if a sim is a Young Adult, Adult, or Elder Human or an Adult Animal (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Young Adult, Adult, or Elder Human or an Adult Animal (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_adult_human_or_pet(sim_info)¶

Determine if a sim is a Young Adult, Adult, or Elder Human or an Adult Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Young Adult, Adult, or Elder Human or an Adult Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

static is_adult_pet(sim_info)¶

Determine if a sim is an Adult Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Adult Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

static is_baby_human(sim_info)¶

Determine if a sim is a Baby Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Baby Human. False, if the Sim is not.
Return type:	bool

static is_baby_or_toddler_human(sim_info)¶

Determine if a sim is a Baby or Toddler Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Baby or Toddler Human. False, if the Sim is not.
Return type:	bool

static is_baby_toddler_or_child_human(sim_info)¶

Determine if a sim is a Baby, Toddler, or Child Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Baby, Toddler, or Child Human. False, if the Sim is not.
Return type:	bool

static is_child_animal(sim_info)¶

Determine if a sim is a Child Animal (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Child Animal (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_child_human(sim_info)¶

Determine if a sim is a Child Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Child Human. False, if the Sim is not.
Return type:	bool

static is_child_or_teen_human(sim_info)¶

Determine if a sim is a Child or Teen Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Child or Teen Human. False, if the Sim is not.
Return type:	bool

static is_child_pet(sim_info)¶

Determine if a sim is a Child Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Child Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

static is_elder_animal(sim_info)¶

Determine if a sim is an Elder Pet (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Elder Pet (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_elder_human(sim_info)¶

Determine if a sim is an Elder Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Elder Human. False, if the Sim is not.
Return type:	bool

static is_elder_human_or_animal(sim_info)¶

Determine if a sim is an Elder Human or Animal (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Elder Human or Animal (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_elder_human_or_pet(sim_info)¶

Determine if a sim is an Elder Human or Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Elder Human or Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

static is_elder_pet(sim_info)¶

Determine if a sim is an Elder Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Elder Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

static is_mature_adult_human(sim_info)¶

Determine if a sim is an Adult Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Adult Human. False, if the Sim is not.
Return type:	bool

static is_mature_adult_or_elder_human(sim_info)¶

Determine if a sim is a Adult or Elder Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Adult or Elder Human. False, if the Sim is not.
Return type:	bool

static is_old_animal(sim_info)¶

Determine if a Sim is an Adult or Elder Animal (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Adult or Elder Animal (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_old_human_or_animal(sim_info)¶

Determine if a sim is a Teen, Young Adult, Adult, or Elder Human or an Adult or Elder Animal (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Teen, Young Adult, Adult, or Elder Human or an Adult or Elder Animal (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_old_human_or_pet(sim_info)¶

Determine if a sim is a Teen, Young Adult, Adult, or Elder Human or an Adult or Elder Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Teen, Young Adult, Adult, or Elder Human or an Adult or Elder Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

static is_old_pet(sim_info)¶

Determine if a sim is an Adult or Elder Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is an Adult or Elder Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

static is_teen_adult_or_elder_human(sim_info)¶

Determine if a sim is a Teen, Young Adult, Adult, or Elder Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Teen, Young Adult, Adult, or Elder Human. False, if the Sim is not.
Return type:	bool

static is_teen_human(sim_info)¶

Determine if a sim is a Teen Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Teen Human. False, if the Sim is not.
Return type:	bool

static is_teen_or_adult_human(sim_info)¶

Determine if a sim is a Teen, Young Adult, or Adult Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Teen, Young Adult, or Adult Human. False, if the Sim is not.
Return type:	bool

static is_teen_or_young_adult_human(sim_info)¶

Determine if a sim is a Teen or Young Adult Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Teen or Young Adult Human. False, if the Sim is not.
Return type:	bool

static is_toddler_human(sim_info)¶

Determine if a sim is a Toddler Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Toddler Human. False, if the Sim is not.
Return type:	bool

static is_toddler_or_child_human(sim_info)¶

Determine if a sim is a Toddler or Child Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Toddler or Child Human. False, if the Sim is not.
Return type:	bool

static is_young_adult_human(sim_info)¶

Determine if a sim is a Young Adult Human.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Young Adult Human. False, if the Sim is not.
Return type:	bool

static is_young_human_or_animal(sim_info)¶

Determine if a sim is a Baby, Toddler, or Child Human or a Child Animal (Cat, Small Dog, Large Dog, Fox).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Baby, Toddler, or Child Human or a Child Animal (Cat, Small Dog, Large Dog, Fox). False, if the Sim is not.
Return type:	bool

static is_young_human_or_pet(sim_info)¶

Determine if a sim is a Baby, Toddler, or Child Human or a Child Pet (Cat, Small Dog, Large Dog).

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is a Baby, Toddler, or Child Human or a Child Pet (Cat, Small Dog, Large Dog). False, if the Sim is not.
Return type:	bool

Demographic Types¶

Gender¶

Occults¶

Body¶

class CommonSimBodyUtils¶

Bases: object

Utilities for manipulating the body of Sims.

static get_ocean_wading_size(sim_info)¶

Retrieve the size of a Sim if they were to wade in an Ocean of water.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	A tuple indicating the x and y Ocean wading size of a Sim from their origin point.
Return type:	Tuple[int, int]

static get_pond_wading_size(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd189fbf10>) → Tuple[int, int]¶

get_wading_size(sim_info)

Retrieve the size of a Sim if they were to wade in a pond of water.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	A tuple indicating the x and y Pond wading size of a Sim from their origin point.
Return type:	Tuple[int, int]

static get_wading_size(sim_info)¶

Retrieve the size of a Sim if they were to wade in an Ocean of water.

Note

This function is obsolete. Please use get_ocean_wading_size() instead.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	A tuple indicating the x and y wading size of a Sim from their origin point.
Return type:	Tuple[int, int]

Genealogy¶

class CommonSimGenealogyUtils¶

Bases: object

Utilities for managing and manipulating the Genealogy of Sims.

static get_father_sim_info(sim_info)¶

Retrieve the Father of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The father of the Sim or None if the Sim does not have a father.
Return type:	Union[SimInfo, None]

static get_fathers_father_sim_info(sim_info)¶

Retrieve the Grandfather of a Sim on their fathers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The grandfather of the Sim on their fathers side or None if the Sim does not have a father or their father does not have a mother.
Return type:	Union[SimInfo, None]

static get_fathers_mother_sim_info(sim_info)¶

Retrieve the Grandmother of a Sim on their fathers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The grandmother of the Sim on their fathers side or None if the Sim does not have a father or their father does not have a mother.
Return type:	Union[SimInfo, None]

static get_genealogy_tracker(sim_info)¶

Retrieve the Genealogy Tracker for a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The genealogy tracker of the Sim or None if not found.
Return type:	Union[GenealogyTracker, None]

static get_mother_sim_info(sim_info)¶

Retrieve the Mother of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The mother of the Sim or None if the Sim does not have a mother.
Return type:	Union[SimInfo, None]

static get_mothers_father_sim_info(sim_info)¶

Retrieve the Grandfather of a Sim on their mothers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The grandfather of the Sim on their mothers side or None if the Sim does not have a mother or their mother does not have a father.
Return type:	Union[SimInfo, None]

static get_mothers_mother_sim_info(sim_info)¶

Retrieve the Grandmother of a Sim on their mothers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The grandmother of the Sim on their mothers side or None if the Sim does not have a mother or their mother does not have a mother.
Return type:	Union[SimInfo, None]

static has_father(sim_info)¶

Determine if a Sim has a father.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has a father. False, if not.
Return type:	bool

static has_grandfather_on_fathers_side(sim_info)¶

Determine if a Sim has a grandfather on the fathers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has a grandfather on the fathers side. False, if not.
Return type:	bool

static has_grandfather_on_mothers_side(sim_info)¶

Determine if a Sim has a grandfather on the mothers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has a grandfather on the mothers side. False, if not.
Return type:	bool

static has_grandmother_on_fathers_side(sim_info)¶

Determine if a Sim has a grandmother on the fathers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has a grandmother on the fathers side. False, if not.
Return type:	bool

static has_grandmother_on_mothers_side(sim_info)¶

Determine if a Sim has a grandmother on the mothers side.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has a grandmother on the mothers side. False, if not.
Return type:	bool

static has_mother(sim_info)¶

Determine if Sim A is the mother of Sim B.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has a mother. False, if not.
Return type:	bool

static is_father_of(sim_info_a, sim_info_b)¶

Determine if Sim A is the father of Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is the father of Sim B. False, if not.
Return type:	bool

static is_fathers_father_of(sim_info_a, sim_info_b)¶

Determine if Sim A is the grandfather of Sim B on the fathers side of Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is the grandfather of Sim B on their fathers side. False, if not.
Return type:	bool

static is_fathers_mother_of(sim_info_a, sim_info_b)¶

Determine if Sim A is the grandmother of Sim B on the fathers side of Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is the grandmother of Sim B on their fathers side. False, if not.
Return type:	bool

static is_mother_of(sim_info_a, sim_info_b)¶

Determine if Sim A is the mother of Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is the mother of Sim B. False, if not.
Return type:	bool

static is_mothers_father_of(sim_info_a, sim_info_b)¶

Determine if Sim A is the grandfather of Sim B on the mothers side of Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is the grandfather of Sim B on their mothers side. False, if not.
Return type:	bool

static is_mothers_mother_of(sim_info_a, sim_info_b)¶

Determine if Sim A is the grandmother of Sim B on the mothers side of Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is the grandmother of Sim B on their mothers side. False, if not.
Return type:	bool

static remove_family_relations_with(sim_info_a, sim_info_b, remove_from_family_tree=True)¶

Remove the family relations Sim A has with Sim B and the family relations Sim B has with Sim A.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – The Sim to remove from the family of Sim A. remove_from_family_tree (bool, optional) – If True, Sim A will remove Sim B from their family tree as well. If False, the family tree of Sim A will not be modified. Default is True.
Returns:	True, if the family relations between the Sims was removed successfully. False, if not.
Return type:	bool

static remove_father_relation(sim_info)¶

Remove the Father of a Sim from their Family Tree.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the father of the Sim has been removed. False, if not.
Return type:	bool

static remove_fathers_father_relation(sim_info)¶

Remove the relation of a Sim to their Grandfather on their fathers side from their Family Tree.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the grandfather of the Sim has been removed. False, if not.
Return type:	bool

static remove_fathers_mother_relation(sim_info)¶

Remove the relation of a Sim to their Grandmother on their fathers side from their Family Tree.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the grandmother of the Sim has been removed. False, if not.
Return type:	bool

static remove_mother_relation(sim_info)¶

Remove the Mother of a Sim from their Family Tree.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the mother of the Sim has been removed. False, if not.
Return type:	bool

static remove_mothers_father_relation(sim_info)¶

Remove the Father of the Mother of a Sim from their Family Tree.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the father of the mother of the Sim has been removed. False, if not.
Return type:	bool

static remove_mothers_mother_relation(sim_info)¶

Remove the relation of a Sim to their Grandmother on their mothers side from their Family Tree.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the grandmother of the Sim has been removed. False, if not.
Return type:	bool

static set_as_father_of(sim_info, new_child_sim_info, propagate=False)¶

Set a Sim to be the Father of another Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. new_child_sim_info (SimInfo) – The new child of Sim A. propagate (bool, optional) – If set to True, the grandparent relations will also be updated. Default is False.
Returns:	True, if the relation was set successfully. False, if not.
Return type:	bool

static set_as_fathers_father_of(sim_info, new_fathers_father_sim_info)¶

Set a Sim to be the Fathers Father of another Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. new_grandchild_sim_info (SimInfo) – The new grandchild of Sim A.
Returns:	True, if the relation was set successfully. False, if not.
Return type:	bool

static set_as_fathers_mother_of(sim_info, new_grandchild_sim_info)¶

Retrieve the Father of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. new_grandchild_sim_info (SimInfo) – The new grandchild of Sim A.
Returns:	True, if the relation was set successfully. False, if not.
Return type:	bool

static set_as_mother_of(sim_info, new_child_sim_info, propagate=False)¶

Set a Sim to be the Mother of another Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. new_child_sim_info (SimInfo) – The new child of Sim A. propagate (bool, optional) – If set to True, the grandparent relations will also be updated. Default is False.
Returns:	True, if the relation was set successfully. False, if not.
Return type:	bool

static set_as_mothers_father_of(sim_info, new_grandchild_sim_info)¶

Retrieve the Father of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. new_grandchild_sim_info (SimInfo) – The new grandchild of Sim A.
Returns:	True, if the relation was set successfully. False, if not.
Return type:	bool

static set_as_mothers_mother_of(sim_info, new_grandchild_sim_info)¶

Retrieve the Father of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. new_grandchild_sim_info (SimInfo) – The new grandchild of Sim A.
Returns:	True, if the relation was set successfully. False, if not.
Return type:	bool

Voice¶

Walkstyles¶

class CommonSimWalkstyleUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for manipulating the Walkstyle of Sims.

classmethod get_current_walkstyle(sim_info)¶

Retrieve the current walkstyle of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The current walkstyle of the Sim or None when not found.
Return type:	Union[Walkstyle, None]

classmethod get_default_walkstyle(sim_info)¶

Retrieve the default walkstyle of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The default walkstyle of a Sim or None if the Sim is not available or has no default walk style.
Return type:	Union[Walkstyle, None]

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

Outfits¶

Appearance Modifiers¶

class CommonSimAppearanceModifierUtils¶

Bases: object

Utilities for manipulating the appearance modifiers of Sims.

static add_appearance_modifier(sim_info, modifier, modifier_guid, priority=CommonAppearanceModifierPriority.TRANSFORMED, apply_to_all_outfits=True, additional_flags=OutfitOverrideOptionFlags.DEFAULT, source=None)¶

Determine if a Sim has any appearance modifiers applied to them of a specified type.

Parameters:

sim_info (SimInfo) – An instance of a Sim.
modifier (AppearanceModifier.BaseAppearanceModification) – The Appearance Modifier to apply.
modifier_guid (int) – The GUID of the appearance modifier being applied.
priority (CommonAppearanceModifierPriority, optional) – The priority of the appearance modifier. This determines which types of appearance modifiers can override this modifier and which ones this modifier overrides. Default is CommonAppearanceModifierPriority.TRANSFORMED.
apply_to_all_outfits (bool, optional) – If True, the appearance modifier will apply to all outfits. If False, the appearance modifier will only apply the current outfit of the Sim. Default is True.
additional_flags (OutfitOverrideOptionFlags, optional) – Additional flags for overriding outfit parts. Default is OutfitOverrideOptionFlags.DEFAULT.
source (Any, optional) – The source of the appearance modifier. Default is None.

static evaluate_appearance_modifiers(sim_info)¶

Force evaluate the appearance modifiers of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.

static get_appearance_modifiers_by_guid_gen(sim_info, modifier_guid)¶

Retrieve the appearance modifiers applied to a Sim that have the specified GUID.

Parameters:	sim_info (SimInfo) – An instance of a Sim. modifier_guid (int) – The GUID of the modifiers to search for.
Returns:	An iterator of Appearance Modifiers that have the specified GUID.
Return type:	Iterator[ModifierInfo]

static get_appearance_modifiers_by_type_gen(sim_info, modifier_type)¶

Retrieve the appearance modifiers applied to a Sim that match a specified type.

Parameters:	sim_info (SimInfo) – An instance of a Sim. modifier_type (Type[AppearanceModifier.BaseAppearanceModification]) – The type of the modifiers to search for.
Returns:	An iterator of Appearance Modifiers that match the specified type.
Return type:	Iterator[ModifierInfo]

static get_appearance_modifiers_gen(sim_info, include_appearance_modifier=None)¶

Retrieve the appearance modifiers applied to a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. include_appearance_modifier (Callable[[CommonAppearanceModifierType, ModifierInfo], bool], optional) – If the result of this callback is True, the Appearance Modifier will be included in the results. If set to None, All Appearance Modifiers will be included. Default is None.
Returns:	An iterator of all Appearance Modifiers applied to the Sim that match the include_appearance_modifier filter.
Return type:	Iterator[ModifierInfo]

static get_appearance_tracker(sim_info)¶

Retrieve the appearance tracker of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The appearance tracker for the Sim or None if not found.
Return type:	Union[AppearanceTracker, None]

static has_any_appearance_modifiers(sim_info)¶

Determine if a Sim has any appearance modifiers applied to them.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has any appearance modifiers applied to them. False, if not.
Return type:	bool

static has_any_appearance_modifiers_of_type(sim_info, modifier_type)¶

Determine if a Sim has any appearance modifiers applied to them of a specified type.

Parameters:	sim_info (SimInfo) – An instance of a Sim. modifier_type (Type[AppearanceModifier.BaseAppearanceModification]) – The type of modifier to search for.
Returns:	True, if the Sim has any appearance modifiers applied to them of the specified type. False, if not.
Return type:	bool

static has_any_appearance_modifiers_with_guid(sim_info, modifier_guid)¶

Determine if a Sim has any appearance modifiers applied to them with a specified GUID.

Parameters:	sim_info (SimInfo) – An instance of a Sim. modifier_guid (int) – The GUID of the modifier to search for.
Returns:	True, if the Sim has any appearance modifiers applied to them with the specified GUID. False, if not.
Return type:	bool

static remove_appearance_modifiers_by_guid(sim_info, modifier_guid, source='S4CL Removal')¶

Remove appearance modifiers from a Sim by their GUID.

Parameters:	sim_info (SimInfo) – An instance of a Sim. modifier_guid (int) – The GUID of the modifiers to remove. source (str, optional) – The source of the removal. Default is “S4CL Removal”.

CAS¶

Outfit¶

Stats¶

Bucks¶

class CommonSimBucksUtils¶

Bases: object

Utilities for bucks.

classmethod add_all_perks(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd18d8dc90>, bucks_type: Union[sims4communitylib.enums.common_bucks_types.CommonBucksType, <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1908fa90>], no_cost: bool = True, **__) → sims4communitylib.classes.testing.common_execution_result.CommonExecutionResult¶

remove_all_perks(sim_info, bucks_type, refund_cost=True, **__)

Add all Perks of a specified Bucks type to a Sim.

Note

A Sim needs to be spawned before their perks can be added.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perks being added. no_cost (bool, optional) – Set True to unlock the perk without spending perk points. Set False to spend perk points to unlock the perk.. Default is False
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod can_afford_perk(sim_info, perk)¶

Determine if a Sim can afford to purchase a perk.

Parameters:	sim_info (SimInfo) – An instance of a Sim. perk (Union[BucksPerk, int]) – The perk to check.
Returns:	The result of the test. True, if the perk can be afforded by the Sim. False, if not.
Return type:	CommonTestResult

classmethod get_available_perks_gen(sim_info, bucks_type)¶

Retrieve all available Perks for the specified Bucks Type and Sim.

Note

A Sim needs to be spawned before perks can be checked.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perks being returned.
Returns:	An iterator of Bucks Perks available to a Sim, regardless of locked status.
Return type:	Iterator[BucksPerk]

classmethod get_bucks_amount(sim_info, bucks_type)¶

Retrieve the number of available bucks to a Sim.

Note

A Sim needs to be spawned before bucks can be checked.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the amount to return.
Returns:	The number of available bucks to a Sim for the specified Bucks Type or 0 if the Sim is not spawned, the bucks type does not exist, or a bucks tracker is not found.
Return type:	int

classmethod get_bucks_tracker(sim_info, bucks_type, add_if_none=False)¶

Retrieve the tracker on a Sim for a specified bucks type.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The type of tracker to retrieve. add_if_none (bool, optional) – Set True, to add the tracker to the Sim when it does not exist. Set False to only return the tracker if it exists. Default is False.
Returns:	The tracker on the Sim associated with the specified Bucks Type or None when not found.
Return type:	Union[BucksTrackerBase, None]

classmethod get_locked_perks_gen(sim_info, bucks_type)¶

Retrieve all Perks for the specified Bucks Type a Sim has locked.

Note

A Sim needs to be spawned before perks can be checked.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perks being returned.
Returns:	An iterator of Bucks Perks that are locked for a Sim.
Return type:	Iterator[BucksPerk]

classmethod get_perk_bucks_type(sim_info, perk)¶

Retrieve the Bucks Type associated with a Perk.

Parameters:	perk (Union[BucksPerk, int]) – The identifier or instance of a Perk.
Returns:	The type of bucks the perk is associated to.
Return type:	CommonBucksType

classmethod get_perk_unlock_cost(sim_info, perk)¶

Retrieve the amount of points a perk costs to unlock.

Parameters:	perk (Union[BucksPerk, int]) – The identifier or instance of a Perk.
Returns:	The amount of points the perk costs to unlock.
Return type:	int

classmethod get_unlocked_perks_gen(sim_info, bucks_type)¶

Retrieve all Perks for the specified Bucks Type a Sim has unlocked.

Note

A Sim needs to be spawned before perks can be checked.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perks being returned.
Returns:	An iterator of Bucks Perks that are unlocked for a Sim.
Return type:	Iterator[BucksPerk]

classmethod has_perk_locked(sim_info, perk)¶

Determine if a Sim has a perk locked.

Note

The Sim being checked needs to be spawned.

Parameters:	sim_info (SimInfo) – An instance of a Sim. perk (Union[BucksPerk, int]) – The perk to check.
Returns:	The result of the test. True, if the test passed. False, if the test failed.
Return type:	CommonTestResult

classmethod has_perk_unlocked(sim_info, perk)¶

Determine if a Sim has a perk unlocked.

Note

A Sim needs to be spawned to check this.

Parameters:	sim_info (SimInfo) – An instance of a Sim. perk (Union[BucksPerk, int]) – The perk to lock.
Returns:	The result of the test. True, if the test passed. False, if the test failed.
Return type:	CommonTestResult

classmethod load_perk_by_guid(perk)¶

Load an instance of a Bucks Perk by its GUID.

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

classmethod lock_all_perks(sim_info, bucks_type, refund_cost=True)¶

Lock all perks of a specific Bucks type for a Sim.

Note

A Sim needs to be spawned before their perks can be locked.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perks being locked. refund_cost (bool, optional) – Set True to refund the cost of all unlocked perks. Set False to give no perk points back. Default is True
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod lock_perk(sim_info, perk, refund_cost=True)¶

Lock a perk for a Sim.

Note

A Sim needs to be spawned before their perks can be locked.

Parameters:	sim_info (SimInfo) – An instance of a Sim. perk (Union[BucksPerk, int]) – The perk to lock. refund_cost (bool, optional) – Set True to refund the cost of the perk. Set False to give no perk points back. Default is True
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod modify_bucks(sim_info, bucks_type, amount, reason=None, **__)¶

Modify the number of points available for a specific Bucks Type.

Note

A Sim needs to be spawned before their Bucks can be modified.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perk points. amount (int) – The amount of points that will be added/removed from the Sim. reason (str, optional) – The reason the perk points are being modified. Default is None.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod remove_all_perks(sim_info, bucks_type, refund_cost=True, reason=None, remove_perk_points=False, **__)¶

Remove all Perks of a specified Bucks type from a Sim.

Note

A Sim needs to be spawned before their perks can be removed.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perks being removed. refund_cost (bool, optional) – Set True to refund the cost of all unlocked perks. Set False to give no perk points back. Default is True reason (str, optional) – The reason the perks are being removed. Default is None. remove_perk_points (bool, optional) – Set True to remove all perk points in addition to all the perks. Set False to remove only the perks. If this is True, refund_cost will be ignored. Default is False.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod set_bucks(sim_info, bucks_type, amount, reason=None, **__)¶

Set the amount of Bucks available to a Sim.

Note

A Sim needs to be spawned before their Bucks can be modified.

Parameters:	sim_info (SimInfo) – An instance of a Sim. bucks_type (Union[CommonBucksType, BucksType]) – The Bucks associated with the perk points. amount (int) – The amount of points that will be available to the Sim. The value should be at or above zero. reason (str, optional) – The reason the perk points are being modified. Default is None.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod unlock_perk(sim_info, perk, no_cost=True)¶

Unlock a perk.

Note

A Sim needs to be spawned before their perks can be unlocked.

Parameters:	sim_info (SimInfo) – An instance of a Sim. perk (Union[BucksPerk, int]) – The perk to lock. no_cost (bool, optional) – Set True to unlock the perk without spending perk points. Set False to spend perk points to unlock the perk.. Default is False
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

Buffs¶

class CommonBuffUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for manipulating Buffs on Sims.

classmethod add_buff(sim_info, buff, buff_reason=None)¶

Add a Buff to a Sim.

Parameters:	sim_info (SimInfo) – The Sim to add the buff to. buff (Union[int, CommonBuffId, Buff]) – The buff being added. buff_reason (Union[int, str, LocalizedString, CommonStringId], optional) – The text that will display when the player hovers over the buffs. What caused the buffs to be added.
Returns:	The result of adding the buffs. True, if the specified buff was successfully added. False, if not.
Return type:	CommonExecutionResult

classmethod add_buffs(sim_info, buffs, buff_reason=None)¶

Add Buffs to a Sim.

Parameters:	sim_info (SimInfo) – The Sim to add the specified buffs to. buffs (Iterator[Union[int, CommonBuffId, Buff]]) – An iterator of identifiers of buffs being added. buff_reason (Union[int, str, LocalizedString, CommonStringId], optional) – The text that will display when the player hovers over the buffs. What caused the buffs to be added.
Returns:	The result of adding the buffs. True, if all of the specified buffs were successfully added. False, if not.
Return type:	CommonExecutionResult

classmethod get_buff_component(sim_info)¶

Retrieve the buff component of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The buff component of the Sim or None if not found.
Return type:	Union[BuffComponent, None]

classmethod get_buff_id(buff_identifier)¶

Retrieve the GUID (Decimal Identifier) of a Buff.

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

classmethod get_buff_ids(sim_info)¶

Retrieve decimal identifiers for all Buffs of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to checked.
Returns:	A collection of Buff identifiers on a Sim.
Return type:	List[int]

classmethod get_buff_name(buff)¶

Retrieve the Name of a Buff.

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

classmethod get_buff_names(buffs)¶

Retrieve the Names of a collection of Buffs.

Parameters:	buffs (Iterator[Buff]) – A collection of Buff instances.
Returns:	A collection of names for all specified Buffs.
Return type:	Tuple[str]

classmethod get_buffs(sim_info)¶

Retrieve all buffs currently active on a Sim.

Parameters:	sim_info (SimInfo) – The Sim to retrieve the buffs of.
Returns:	A collection of currently active buffs on the Sim.
Return type:	Tuple[Buff]

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 has_all_buffs(sim_info, buffs)¶

Determine if the Sim has all of the specified buffs.

Parameters:	sim_info (SimInfo) – The Sim being checked. buffs (Iterator[Union[int, CommonBuffId, Buff]]) – An iterator of buffs to check for.
Returns:	The result of testing. True, if the Sim has all of the specified buffs. False, if not.
Return type:	CommonTestResult

classmethod has_any_buffs(sim_info, buffs)¶

Determine if the Sim has any of the specified buffs.

Parameters:	sim_info (SimInfo) – The Sim being checked. buffs (Iterator[Union[int, CommonBuffId, Buff]]) – An iterator of buffs to check for.
Returns:	The result of testing. True, if the Sim has any of the specified buffs. False, if not.
Return type:	CommonTestResult

classmethod has_buff(sim_info, buff)¶

Determine if the Sim has a Buff.

Parameters:	sim_info (SimInfo) – The Sim being checked. buff (Union[int, CommonBuffId, Buff]) – The buff to check for.
Returns:	The result of testing. True, if the Sim has the specified buff. False, if not.
Return type:	CommonTestResult

classmethod has_fertility_boosting_buff(sim_info)¶

Determine if any fertility boosting buffs are currently active on a Sim.

Note

Fertility Boosting Buffs:

Fertility Potion
Fertility Potion Masterwork
Fertility Potion Normal
Fertility Potion Outstanding
Massage Table Fertility Boost
Massage Table Fertility Boost Incense

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if they have any fertility boosting buffs. False, if not.
Return type:	CommonTestResult

classmethod has_morning_person_buff(sim_info)¶

Determine if any Morning Person Trait buffs are currently active on a Sim.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if they have any morning person buffs. False, if not.
Return type:	CommonTestResult

classmethod has_night_owl_buff(sim_info)¶

Determine if any Night Owl Trait buffs are currently active on a Sim.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if they have any night owl buffs. False, if not.
Return type:	CommonTestResult

classmethod is_buff_available(buff)¶

Determine if a Buff is available for use.

Note

If the Buff is part of a package that is not installed, it will be considered as not available.

Parameters:	buff (Union[int, CommonBuffId, Buff]) – The buff to check for.
Returns:	True, if the Buff is available for use. False, if not.
Return type:	bool

classmethod load_buff_by_id(buff)¶

Load an instance of a Buff by its identifier.

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

classmethod remove_buff(sim_info, buff)¶

Remove a Buff from a Sim.

Parameters:	sim_info (SimInfo) – The Sim to remove the buff from. buff (Union[int, CommonBuffId, Buff]) – The buff being removed.
Returns:	The result of removing the buff. True, if the buff was successfully removed. False, if not.
Return type:	CommonExecutionResult

classmethod remove_buffs(sim_info, buffs)¶

Remove Buffs from a Sim.

Parameters:	sim_info (SimInfo) – The Sim to remove the specified buffs from. buffs (Iterator[Union[int, CommonBuffId, Buff]]) – An iterator of identifiers of buffs being removed.
Returns:	The result of removing the buffs. True, if all of the specified buffs were successfully removed. False, if not.
Return type:	CommonExecutionResult

Currency¶

class CommonSimCurrencyUtils¶

Bases: object

Utilities for modifying various currency types of Sims.

classmethod add_simoleons_to_household(sim_info, amount, reason, **kwargs)¶

Add an amount of simoleons to the Household of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. amount (int) – The amount of simoleons to add. reason (CommonCurrencyModifyReason) – The reason the simoleons are being added.
Returns:	True, if simoleons were added successfully. False, if not.
Return type:	bool

classmethod can_afford_simoleons(sim_info, amount)¶

Determine if a Sim can afford an amount of simoleons.

Parameters:	sim_info (SimInfo) – An instance of a Sim. amount (int) – The amount of simoleons to check.
Returns:	True, if the household of the Sim can afford the simoleon amount. False, if not.
Return type:	bool

classmethod get_household_funds(sim_info)¶

Retrieve the Funds object that manages the Household Simoleons for the Household of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The FamilyFunds object of the Household of the specified Sim or None if the Sim did not have a Household.
Return type:	Union[FamilyFunds, None]

classmethod remove_simoleons_from_household(sim_info, amount, reason, require_full_amount=True, **kwargs)¶

Remove an amount of simoleons from the Household of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. amount (int) – The amount of simoleons to add. reason (CommonCurrencyModifyReason) – The reason the simoleons are being removed. require_full_amount (bool, optional) – If True, then the Sim must have the full amount for the removal to be successful. If False, the Sim does not require the full amount. Default is True.
Returns:	The amount of simoleons removed from the household of the specified Sim. This amount may be lower than the specified amount, if the Sim did not have enough simoleons for removal.
Return type:	float

Mood¶

class CommonMoodUtils¶

Bases: object

Utilities for manipulating Sim moods.

static get_current_mood(sim_info)¶

Retrieve the current mood for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to retrieve the mood of.
Returns:	The current Mood of the Sim.
Return type:	Mood

static get_current_mood_id(sim_info)¶

Retrieve an identifier of the current mood for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to retrieve the mood identifier of.
Returns:	The identifier of the current Mood of the Sim.
Return type:	int

static has_mood(sim_info, mood_id)¶

Determine if a Sim has the specified mood.

Parameters:	sim_info (SimInfo) – The Sim to check. mood_id (CommonMoodId) – The identifier of the Mood to check for.
Returns:	True, if the Sim has the specified Mood. False, if the Sim does not.
Return type:	bool

static is_angry(sim_info)¶

Determine if a Sim is angry.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_bored(sim_info)¶

Determine if a Sim is bored.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_confident(sim_info)¶

Determine if a Sim is confident.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_dazed(sim_info)¶

Determine if a Sim is dazed.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_embarrassed(sim_info)¶

Determine if a Sim is embarrassed.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_energized(sim_info)¶

Determine if a Sim is energized.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_fine(sim_info)¶

Determine if a Sim is fine.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_flirty(sim_info)¶

Determine if a Sim is flirty.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_focused(sim_info)¶

Determine if a Sim is focused.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_happy(sim_info)¶

Determine if a Sim is happy.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_inspired(sim_info)¶

Determine if a Sim is inspired.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_playful(sim_info)¶

Determine if a Sim is playful.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_possessed(sim_info)¶

Determine if a Sim is possessed.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_sad(sim_info)¶

Determine if a Sim is sad.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_sleeping(sim_info)¶

Determine if a Sim is sleeping.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_stressed(sim_info)¶

Determine if a Sim is stressed.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

static is_uncomfortable(sim_info)¶

Determine if a Sim is uncomfortable.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is the Mood. False, if the Sim is not.
Return type:	bool

Motives¶

Skills¶

class CommonSimSkillUtils¶

Bases: object

Utilities for manipulating the Skills of Sims.

static change_progress_toward_max_skill_level(sim_info, skill, value, add=True)¶

Modify the amount of progress a Sim has made toward the max level of a Skill.

Parameters:	sim_info (SimInfo) – The Sim to modify. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to modify. value (Union[int, CommonSkillId, Skill]) – The level to add or subtract to/from the skill. add (bool, optional) – If True, the skill will be added to the Sim before it is modified.
Returns:	True, if successful. False, if not.
Return type:	bool

static change_progress_toward_next_skill_level(sim_info, skill, value, add=True)¶

Modify the amount of progress a Sim has made toward the next level of a Skill.

Parameters:	sim_info (SimInfo) – The Sim to modify. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to modify. value (Union[int, CommonSkillId, Skill]) – The level to add or subtract to/from the skill. add (bool, optional) – If True, the skill will be added to the Sim before it is modified.
Returns:	True, if successful. False, if not.
Return type:	bool

static get_all_skills_available_for_sim_gen(sim_info)¶

Retrieve all Skills available to a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	An iterator of Skills that are available for the specified Sim.
Return type:	Iterator[Skill]

static get_current_skill_level(sim_info, skill, use_effective_skill_level=True)¶

Retrieve the current skill level of a Sim for a Skill.

Parameters:	sim_info (SimInfo) – An instance of a Sim. skill (Union[int, CommonSkillId, Skill]) – The decimal identifier of a Skill. use_effective_skill_level (bool, optional) – If True, any skill modifiers will be taken into account, such as buffs, traits, etc. If False, the skill level without modifiers will be returned. True only works if the Sim is instanced. Default is True.
Returns:	The current level the Sim is at for the specified Skill or 0.0 if the Skill is either not available or the Sim does not have it.
Return type:	float

static get_progress_toward_max_skill_level(sim_info, skill, add=True)¶

Retrieve the amount of progress a Sim has made toward the max level of a Skill.

Parameters:	sim_info (SimInfo) – The Sim to modify. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to modify. add (bool, optional) – If True, the skill will be added to the Sim before it is modified.
Returns:	True, if successful. False, if not.
Return type:	bool

static get_progress_toward_next_skill_level(sim_info, skill, add=False)¶

Retrieve the amount of progress a Sim has made toward the next level of a Skill.

Parameters:	sim_info (SimInfo) – The Sim to check. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to use. add (bool, optional) – If True, the skill will be added to the Sim before it is checked.
Returns:	The progress to the next level of the specified Skill or -1.0 if a problem occurs.
Return type:	float

static get_skill(sim_info, skill, add=True)¶

Retrieve a Skill for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to check. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to use. add (bool, optional) – If True, the skill will be added to the Sim before it is checked.
Returns:	An instance of a Skill of the Sim or None if the Skill does not exist.
Return type:	Union[Skill, None]

static has_skill(sim_info, skill)¶

Determine if a Sim has a Skill.

Parameters:	sim_info (SimInfo) – The Sim to check. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to check.
Returns:	True, if the Sim has the skill. False, if the Sim does not.
Return type:	bool

static is_at_max_skill_level(sim_info, skill, use_effective_skill_level=True)¶

Determine if a Sim has reached the Maximum Level of a Skill.

Note

Max level depends on the skill itself. Each skill can have a different max level.

Parameters:	sim_info (SimInfo) – The Sim to check. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to check. use_effective_skill_level (bool, optional) – If True, any skill modifiers will be taken into account, such as buffs, traits, etc. If False, the skill level without modifiers will be returned. True only works if the Sim is instanced. Default is True.
Returns:	True, if the Sim has the skill at the maximum level. False, if the Sim does not.
Return type:	bool

static remove_skill(sim_info, skill)¶

Remove a Skill from the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to remove.
Returns:	True, if the skill was removed successfully. False, if not.
Return type:	bool

static set_current_skill_level(sim_info, skill, level, add=True)¶

Set the current skill level of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. skill (Union[int, CommonSkillId, Skill]) – The decimal identifier of a Skill. level – The level to set the skill to. add (bool, optional) – OBSOLETE AND IGNORED ARGUMENT! When setting the skill level for a Sim, the Skill will always be added first.
Returns:	True, if successful. False, if not successful, the skill does not exist, or the skill is not valid for the Sim.
Return type:	bool

static set_current_skill_level_to_max(sim_info, skill, add=True)¶

Set the current skill level of a Sim to its maximum value.

Parameters:	sim_info (SimInfo) – An instance of a Sim. skill (Union[int, CommonSkillId, Skill]) – The decimal identifier of a Skill.
Returns:	True, if successful. False, if not successful, the skill does not exist, or the skill is not valid for the Sim.
Return type:	bool

static set_progress_toward_max_skill_level(sim_info, skill, value, add=True)¶

Set the amount of progress a Sim has made toward the max level of a Skill.

Parameters:	sim_info (SimInfo) – The Sim to modify. skill (Union[int, CommonSkillId, Skill]) – The identifier of the Skill to set. value (Union[int, CommonSkillId, Skill]) – The amount to add. add (bool, optional) – If True, the skill will be added to the Sim before it is modified.
Returns:	True, if successful. False, if not.
Return type:	bool

static translate_skill_progress(sim_info, skill_from, skill_to, add=True)¶

Translate the total progress of one Skill to the total progress of another Skill for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. skill_from (Union[int, CommonSkillId, Skill]) – The identifier of the Skill being changed. skill_to (Union[int, CommonSkillId, Skill]) – The identifier of the Skill being translated to. add (bool, optional) – If True, the skill will be added to the Sim before it is modified.
Returns:	True, if successful. False, if not.
Return type:	bool

Spells¶

class CommonSimSpellUtils¶

Bases: object

Utilities for unlocking and locking things, usually learned things such as Spells.

classmethod add_all_spells(sim_info)¶

Make a Sim learn all Spells.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod add_spell(sim_info, spell, mark_as_new=True)¶

Make a Sim learn a Spell.

Parameters:	sim_info (SimInfo) – An instance of a Sim. spell (Union[int, Spell]) – The spell to add. mark_as_new (bool, optional) – Set True to mark the Spell as being new. Set False to refrain from marking the spell as new. Default is True.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod add_spells(sim_info, spells, mark_as_new=True)¶

Make a Sim learn Spells.

Parameters:	sim_info (SimInfo) – An instance of a Sim. spells (Tuple[Union[int, Spell]]) – A collection of spells to add. mark_as_new (bool, optional) – Set True to mark the Spells as being new. Set False to refrain from marking the spells as new. Default is True.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod load_spell_by_id(spell)¶

Load an instance of a Spell by its decimal identifier.

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

classmethod remove_all_spells(sim_info)¶

Make a Sim unlearn all Spells.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod remove_spell(sim_info, spell)¶

Make a Sim unlearn a Spell.

Parameters:	sim_info (SimInfo) – An instance of a Sim. spell (Union[int, Spell]) – The spell to remove.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

classmethod remove_spells(sim_info, spells)¶

Make a Sim unlearn Spells.

Parameters:	sim_info (SimInfo) – An instance of a Sim. spells (Tuple[Union[int, Spell]]) – A collection of spells to remove.
Returns:	The result of executing the function. True, if successful. False, if not.
Return type:	CommonExecutionResult

Traits¶

class CommonTraitUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for manipulating Traits on Sims.

classmethod add_trait(sim_info, trait)¶

Add a Trait to a Sim.

Parameters:	sim_info (SimInfo) – The Sim to add the specified traits to. trait (Union[int, CommonTraitId, Trait]) – The trait being added.
Returns:	The result of adding the trait. True, if the trait was successfully added to the Sim. False, if not.
Return type:	CommonExecutionResult

classmethod add_trait_to_all_sims(trait_id, include_sim_callback=None)¶

Add a trait to all Sims that match the specified include filter.

Parameters:	trait_id (Union[int, CommonTraitId, Trait]) – The identifier of the Trait to add to all Sims. include_sim_callback (Callback[[SimInfo], bool], optional) – Only Sims that match this filter will have the Trait added.

classmethod add_traits(sim_info, traits)¶

Add Traits to a Sim.

Parameters:	sim_info (SimInfo) – The Sim to add the specified traits to. traits (Iterator[Union[int, CommonTraitId, Trait]]) – An iterator of identifiers of traits being added.
Returns:	The result of adding the traits. True, if all specified traits were successfully added to the Sim. False, if not.
Return type:	CommonExecutionResult

classmethod can_be_impregnated(sim_info)¶

Determine if a Sim Can Be Impregnated.

Note

Use can_reproduce() for Pet Sims.

Note

Will return False if the Sim has the GENDER_OPTIONS_PREGNANCY_CAN_NOT_BE_IMPREGNATED trait.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim can be impregnated. False, if not.
Return type:	CommonTestResult

classmethod can_create_pregnancy(sim_info)¶

Determine if a Sim can either impregnate, be impregnated, or can reproduce.

Note

Will return False if the Sim can both impregnate and not impregnate, if the Sim can both be impregnated and not be impregnated or if the Sim can both reproduce and not reproduce.

Note

A Sim can impregnate when they can either impregnate other Sims, can be impregnated by other Sims, or if they are a Pet, can reproduce.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim can create pregnancies. False, if not.
Return type:	CommonTestResult

classmethod can_impregnate(sim_info)¶

Determine if a Sim Can Impregnate.

Note

Use can_reproduce() for Pet Sims.

Note

This will check for a Sim to not also have the GENDER_OPTIONS_PREGNANCY_CAN_NOT_IMPREGNATE trait.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim can impregnate other Sims. False, if not.
Return type:	CommonTestResult

classmethod can_not_be_impregnated(sim_info)¶

Determine if a Sim Can Not Be Impregnated.

Note

Use can_not_reproduce() for Pet Sims.

Note

Will return False if the Sim has the GENDER_OPTIONS_PREGNANCY_CAN_BE_IMPREGNATED trait.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim can not be impregnated. False, if not.
Return type:	CommonTestResult

classmethod can_not_impregnate(sim_info)¶

Determine if a Sim Can Not Impregnate.

Note

Use can_not_reproduce() for Pet Sims.

Note

This will check for a Sim to not also have the GENDER_OPTIONS_PREGNANCY_CAN_IMPREGNATE trait.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim can not impregnate other Sims. False, if not.
Return type:	CommonTestResult

classmethod can_not_reproduce(sim_info)¶

Determine if a pet Sim can reproduce.

..note:: Use can_not_impregnate() and can_not_be_impregnated() for Human Sims. .. note:: Will return False if the pet Sim has the PREGNANCY_OPTIONS_PET_CAN_REPRODUCE trait.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim can not reproduce. False, if not.
Return type:	CommonTestResult

classmethod can_reproduce(sim_info)¶

Determine if a pet Sim can reproduce.

Note

Use can_impregnate() and can_be_impregnated() for Human Sims.

Note

Will return False if the pet Sim has the PREGNANCY_OPTIONS_PET_CAN_NOT_REPRODUCE trait.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim can reproduce. False, if not.
Return type:	CommonTestResult

classmethod get_equipped_traits(sim_info)¶

Retrieve Sims currently equipped traits.

Note

The main use of this function is to check Occult Types.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	A collection of equipped Traits on a Sim.
Return type:	List[int]

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_trait_id(trait_identifier)¶

Retrieve the decimal identifier of a Trait.

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

classmethod get_trait_ids(sim_info)¶

Retrieve decimal identifiers for all Traits of a Sim.

Parameters:	sim_info (Union[SimInfo, SimInfoBaseWrapper, PregnancyOffspringData]) – The Sim to check.
Returns:	A collection of Trait identifiers on a Sim.
Return type:	List[int]

classmethod get_trait_name(trait)¶

Retrieve the Name of a Trait.

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

classmethod get_trait_names(traits)¶

Retrieve the Names of a collection of Trait.

Parameters:	traits (Iterator[Trait]) – A collection of Trait instances.
Returns:	A collection of names for all specified Traits.
Return type:	Tuple[str]

classmethod get_traits(sim_info)¶

Retrieve all Traits of a Sim.

Parameters:	sim_info (Union[SimInfo, SimInfoBaseWrapper, PregnancyOffspringData]) – The Sim to check.
Returns:	A collection of Traits on a Sim.
Return type:	List[int]

classmethod has_all_traits(sim_info, trait_ids)¶

Determine if a Sim has any of the specified traits.

Parameters:	sim_info (SimInfo) – The Sim to check. traits (Iterator[Union[int, CommonTraitId, Trait]]) – An iterator of identifiers of Traits.
Returns:	The result of testing. True, if the Sim has any of the specified traits. False, if not.
Return type:	CommonTestResult

classmethod has_animal_attraction(sim_info)¶

Determine if a Sim has an Animal Attraction.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if not.
Return type:	CommonTestResult

classmethod has_animal_whisperer(sim_info)¶

Determine if a Sim is an Animal Whisperer.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if not.
Return type:	CommonTestResult

classmethod has_any_traits(sim_info, trait_ids)¶

Determine if a Sim has any of the specified traits.

Parameters:	sim_info (SimInfo) – The Sim to check. traits (Iterator[Union[int, CommonTraitId, Trait]]) – An iterator of identifiers of Traits.
Returns:	The result of testing. True, if the Sim has any of the specified traits. False, if not.
Return type:	CommonTestResult

classmethod has_challenge_kindness_ambassador(sim_info)¶

Determine if a Sim has Challenged the Kindness Ambassador.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has challenged the kindness ambassador. False, if not.
Return type:	CommonTestResult

classmethod has_commitment_issues(sim_info)¶

Determine if a Sim has Commitment Issues.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if not.
Return type:	CommonTestResult

classmethod has_feminine_frame(sim_info)¶

Determine if a Sim has a Feminine Body Frame.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has a feminine frame. False, if not.
Return type:	CommonTestResult

classmethod has_masculine_frame(sim_info)¶

Determine if a Sim has a Masculine Body Frame.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has a masculine frame. False, if not.
Return type:	CommonTestResult

classmethod has_trait(sim_info, trait)¶

Determine if a Sim has a Trait.

Parameters:	sim_info (SimInfo) – The Sim to check. trait (Union[int, CommonTraitId, Trait]) – The trait to check for.
Returns:	The result of testing. True, if the Sim has the specified trait. False, if not.
Return type:	CommonTestResult

classmethod hates_children(sim_info)¶

Determine if a Sim Hates Children.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Hates Children trait. False, if not.
Return type:	CommonTestResult

classmethod is_active(sim_info)¶

Determine if a Sim is active.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_aggressive_pet(sim_info)¶

Determine if a pet Sim is Aggressive.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_alluring(sim_info)¶

Determine if a Sim is Alluring.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_antiseptic(sim_info)¶

Determine if a Sim is Antiseptic.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_bro(sim_info)¶

Determine if a Sim is a Bro.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_carefree(sim_info)¶

Determine if a Sim is Care Free.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_cat_lover(sim_info)¶

Determine if a Sim is a Cat Lover.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_clumsy(sim_info)¶

Determine if a Sim is Clumsy.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_conflicting_trait(sim_info, trait_id)¶

Determine if a Trait conflicts with any of the Sims current Traits.

Parameters:	sim_info (SimInfo) – An instance of a Sim. trait_id (int) – The identifier of the trait to check.
Returns:	The result of testing. True, if the specified Trait conflicts with any Traits the Sim currently has. False, if not.
Return type:	CommonTestResult

classmethod is_criminal(sim_info)¶

Determine if a Sim is a Criminal.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_dastardly(sim_info)¶

Determine if a Sim is Dastardly.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_dog_lover(sim_info)¶

Determine if a Sim is a Dog Lover.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_evil(sim_info)¶

Determine if a Sim is Evil.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_fertile(sim_info)¶

Determine if a Sim is Fertile.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_friendly_pet(sim_info)¶

Determine if a pet Sim is Friendly.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_geek(sim_info)¶

Determine if a Sim is a geek.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_genius(sim_info)¶

Determine if a Sim is a Genius.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_ghost_trait(trait_identifier)¶

Determine if a trait is a Ghost trait.

Parameters:	trait_identifier (Union[int, CommonTraitId, Trait]) – An identifier of a trait.
Returns:	True, if the specified trait is a ghost trait. False, if not.

classmethod is_glutton(sim_info)¶

Determine if a Sim is a Glutton.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_glutton_human(sim_info)¶

Determine if a non pet Sim is a Glutton

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_glutton_pet(sim_info)¶

Determine if a pet Sim is a Glutton.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_good(sim_info)¶

Determine if a Sim is Good.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_gregarious(sim_info)¶

Determine if a Sim is Gregarious.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_hot_headed(sim_info)¶

Determine if a Sim is Hot Headed.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_hunter_pet(sim_info)¶

Determine if a pet Sim is a Hunter.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_incredibly_friendly(sim_info)¶

Determine if a Sim is Incredibly Friendly.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_insane(sim_info)¶

Determine if a Sim is Insane.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_insider(sim_info)¶

Determine if a Sim is an Insider.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_lazy(sim_info)¶

Determine if a Sim is Lazy.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_loner(sim_info)¶

Determine if a Sim is a Loner.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_love_guru(sim_info)¶

Determine if a Sim is a Love Guru.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_loyal_pet(sim_info)¶

Determine if a pet Sim is Loyal.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_mean(sim_info)¶

Determine if a Sim is Mean.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_mentor(sim_info)¶

Determine if a Sim is a Mentor.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_morning_person(sim_info)¶

Determine if a Sim is a Morning Person.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_naughty_pet(sim_info)¶

Determine if a pet Sim is Naughty.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_neat(sim_info)¶

Determine if a Sim is neat.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_night_owl(sim_info)¶

Determine if a Sim is a Night Owl.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_player(sim_info)¶

Determine if a Sim has the Player trait.

Note

This does not indicate whether the Sim is one of the Players Sims, it simply indicates if they have the trait that makes other Sims less jealous.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_self_absorbed(sim_info)¶

Determine if a Sim is Self Absorbed.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_self_assured(sim_info)¶

Determine if a Sim is Self Assured.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_service_sim(sim_info)¶

Determine if a Sim is a service Sim.

..warning:: Obsolete: Use is_service_sim() in CommonSimTypeUtils instead.

classmethod is_shameless(sim_info)¶

Determine if a Sim is Shameless.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_sincere(sim_info)¶

Determine if a Sim is Sincere.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_skittish_pet(sim_info)¶

Determine if a pet Sim is Skittish.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_slob(sim_info)¶

Determine if a Sim is a Slob.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_snob(sim_info)¶

Determine if a Sim is a Snob.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_special_npc(sim_info)¶

Determine if a Sim is a Special NPC.

Note

Special NPCs:

Hidden Event NPC
Grim Reaper
Scarecrow
Flower Bunny

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim is a special NPC. False, if the Sim is not a Special NPC.
Return type:	CommonTestResult

classmethod is_squeamish(sim_info)¶

Determine if a Sim is Squeamish.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_survivalist(sim_info)¶

Determine if a Sim is a Survivalist.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod is_trait_available(trait)¶

Determine if a Trait is available for use.

Note

If the Trait is part of a package that is not installed, it will be considered as not available.

Parameters:	trait (Union[int, CommonTraitId, Trait]) – The trait to check for.
Returns:	True, if the Trait is available for use. False, if not.
Return type:	bool

classmethod is_unflirty(sim_info)¶

Determine if a Sim is Unflirty.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim has the Trait. False, if the Sim does not have the Trait.
Return type:	CommonTestResult

classmethod load_trait_by_id(trait)¶

Load an instance of a Trait by its identifier.

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

classmethod prefers_menswear(sim_info)¶

Determine if a Sim prefers Mens Clothing.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim prefers menswear. False, if not.
Return type:	CommonTestResult

classmethod prefers_womenswear(sim_info)¶

Determine if a Sim prefers Womens Clothing.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim prefers womenswear. False, if not.
Return type:	CommonTestResult

classmethod remove_trait(sim_info, trait)¶

Remove a Trait from a Sim.

Parameters:	sim_info (SimInfo) – The Sim to remove the specified traits from. trait (Union[int, CommonTraitId, Trait]) – The trait being removed.
Returns:	The result of removing the trait. True, if the trait was successfully removed from the Sim. False, if not.
Return type:	CommonExecutionResult

classmethod remove_trait_from_all_sims(trait_id, include_sim_callback=None)¶

Remove a trait from all Sims that match the specified include filter.

Parameters:	trait_id (Union[int, CommonTraitId, Trait]) – The identifier of the Trait to remove from all Sims. include_sim_callback (Callback[[SimInfo], bool], optional) – Only Sims that match this filter will have the Trait removed.

classmethod remove_traits(sim_info, traits)¶

Remove Traits from a Sim.

Parameters:	sim_info (SimInfo) – The Sim to remove the specified traits from. traits (Iterator[Union[int, CommonTraitId, Trait]]) – An iterator of Trait identifiers of traits being removed.
Returns:	The result of removing the traits. True, if all specified traits were successfully removed from the Sim. False, if not.
Return type:	CommonExecutionResult

classmethod swap_traits(sim_info, trait_id_one, trait_id_two)¶

Remove one trait and add another to a Sim.

Note

If trait_id_one exists on the Sim, it will be removed and trait_id_two will be added.

Note

If trait_id_two exists on the Sim, it will be removed and trait_id_one will be added.

Parameters:	sim_info (SimInfo) – The Sim to remove the specified traits from. trait_id_one (Union[int, CommonTraitId, Trait]) – The first trait to remove/add trait_id_two (Union[int, CommonTraitId, Trait]) – The second trait to remove/add
Returns:	The result of swapping traits. True, if the Traits were swapped successfully. False, if neither Trait exists on a Sim or the traits were not swapped successfully.
Return type:	CommonExecutionResult

classmethod uses_toilet_sitting(sim_info)¶

Determine if a Sim uses the toilet while sitting.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim uses toilets while sitting. False, if not.
Return type:	CommonTestResult

classmethod uses_toilet_standing(sim_info)¶

Determine if a Sim uses the toilet while standing.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim uses toilets while standing. False, if not.
Return type:	CommonTestResult

Statistics¶

class CommonSimStatisticUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for manipulating the Statistics of Sims.

classmethod add_statistic_modifier(sim_info, statistic, value, add_dynamic=True, add=True)¶

Add a Modifier to the specified Statistic for the specified Sim.

Parameters:

sim_info (SimInfo) – The Sim to modify.
statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic containing the modifier.
value (float) – The modifier to add.
add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored.
add (bool, optional) – Whether or not to add the statistic to the Sim.

classmethod add_statistic_value(sim_info, statistic, value, add_dynamic=True, add=True)¶

Change the Value of a Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to add a value to. value (float) – The amount to add. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	The result of setting the statistic value. True, if successful. False, if not.
Return type:	CommonExecutionResult

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_statistic(sim_info, statistic, statistic, add_dynamic=False, add=False)¶

Retrieve a Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to check. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to retrieve of. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	An instance of the statistic or None if a problem occurs.
Return type:	Union[BaseStatistic, None]

classmethod get_statistic_level(sim_info, statistic)¶

Retrieve the User Value of a Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to check. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to retrieve the user value of.
Returns:	The value of the statistic, -1.0 if the statistic is not found.
Return type:	float

classmethod get_statistic_value(sim_info, statistic, add_dynamic=False, add=False)¶

Retrieve the Value of a Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to check. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to retrieve the value of. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim. This argument is no longer used and will be ignored.
Returns:	The value of the statistic, -1.0 if the statistic is not found.
Return type:	float

classmethod has_statistic(sim_info, statistic)¶

Determine if a Sim has any of the specified Statistics.

Parameters:	sim_info (SimInfo) – The Sim to check. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to check.
Returns:	True, if the Sim has any of the statistics. False, if not.
Return type:	bool

classmethod has_statistics(sim_info, statistics)¶

Determine if a Sim has any of the specified Statistics.

Parameters:	sim_info (SimInfo) – The Sim to check. statistics (Iterator[Union[int, CommonStatisticId, BaseStatistic]]) – An iterator of identifiers for statistics to check.
Returns:	True, if the Sim has any of the specified statistics. False, if not.
Return type:	bool

classmethod is_statistic_locked(sim_info, statistic, add_dynamic=False, add=False)¶

Determine if a statistic is locked for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to check. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to check. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	The result of checking if the statistic is locked or not. True, if the statistic is locked. False, if not.
Return type:	CommonExecutionResult

classmethod remove_all_statistic_modifiers_for_statistic(sim_info, statistic, add_dynamic=True, add=True)¶

Remove all Modifiers from the specified Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to remove modifiers from. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	True, if successful. False, if not successful.
Return type:	bool

classmethod remove_statistic(sim_info, statistic)¶

Remove a Statistic from the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to remove.
Returns:	True, if successful. False, if not successful.
Return type:	bool

classmethod remove_statistic_modifier(sim_info, statistic, value, add_dynamic=True, add=True)¶

Remove a Modifier from a Sim by value.

Parameters:	sim_info (SimInfo) – The Sim to modify. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to remove the modifier from. value (float) – The modifier to remove. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	True, if successful. False, if not successful.
Return type:	bool

classmethod remove_statistic_modifier_by_handle_id(sim_info, modifier_handle_id)¶

Remove a Statistic Modifier from a Sim by a handle id.

Parameters:	sim_info (SimInfo) – The Sim to modify. modifier_handle_id (int) – The handle id for the statistic modifier being removed.
Returns:	True, if the modifier was removed successfully. False, if not.
Return type:	bool

classmethod set_statistic_level(sim_info, statistic, value, add_dynamic=True, add=True)¶

Set the Level of a Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to add a user value to. value (float) – The level to set the statistic to. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	The result of setting the statistic level. True, if successful. False, if not successful.
Return type:	CommonExecutionResult

classmethod set_statistic_user_value(sim_info, statistic, value, add_dynamic=True, add=True)¶

Set the User Value of a Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to add a user value to. value (float) – The user value to set the statistic to. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	True, if successful. False, if not successful.
Return type:	bool

classmethod set_statistic_value(sim_info, statistic, value, add_dynamic=True, add=True)¶

Set the Value of a Statistic for the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to modify. statistic (Union[int, CommonStatisticId, BaseStatistic]) – The identifier of the statistic to add a value to. value (float) – The amount to add. add_dynamic (bool, optional) – OBSOLETE: Add the statistic component to the Sim. This argument is no longer used and will be ignored. add (bool, optional) – Whether or not to add the statistic to the Sim.
Returns:	The result of setting the statistic value. True, if successful. False, if not.
Return type:	CommonExecutionResult

Whims¶

class CommonWhimUtils¶

Bases: object

Utilities for manipulating the Whims of Sims.

static get_current_whims(sim_info)¶

Retrieve the current Whims of the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to get the Whim Sets of.
Returns:	A collection of Whims Sets for the specified Sim.
Return type:	Tuple[WhimSetBaseMixin]

Unlocks¶

class CommonSimUnlockUtils¶

Bases: object

Utilities for unlocks.

classmethod get_unlock_tracker(sim_info)¶

Retrieve tracker for unlocks for a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The tracker for unlocks for the Sim or None if not found.
Return type:	Union[UnlockTracker, None]

Locational¶

Location¶

Household¶

class CommonHouseholdUtils¶

Bases: sims4communitylib.logging.has_class_log.HasClassLog

Utilities for manipulating households.

classmethod add_sim_to_active_household(sim_info, destroy_if_empty_household=True)¶

Add a Sim to the Active Sims household.

Parameters:	sim_info (SimInfo) – The Sim to add. destroy_if_empty_household (bool, optional) – If True, if the Sim comes from a household containing only them, then it will be destroyed after they are moved.
Returns:	True, if the Sim was added to the active household successfully. False, if not.
Return type:	bool

classmethod add_sim_to_target_household(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd18197e50>, target_sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd18197e50>, destroy_if_empty_household: bool = True) → bool¶

add_sim_to_active_household(sim_info, destroy_if_empty_household=True)

Add a Sim to the Household of the Target Sim.

Parameters:	sim_info (SimInfo) – The Sim to add. target_sim_info (SimInfo) – This Sim will receive the Sim to their Household. destroy_if_empty_household (bool, optional) – If True, if the Sim comes from a household containing only them, then it will be destroyed after they are moved.
Returns:	True, if the Sim was added to the household of the target successfully. False, if not.
Return type:	bool

classmethod create_empty_household(starting_funds=0, as_hidden_household=False)¶

Create an empty household.

Parameters:	starting_funds (int, optional) – The funds the Household will start with. as_hidden_household (bool, optional) – If True, the created household will be hidden.
Returns:	The created Household
Return type:	Household

classmethod delete_household(household)¶

Delete the specified household from the game.

Parameters:	household (Household) – The Household to delete
Returns:	True, if the Household was deleted successfully. False, if not.
Return type:	bool

classmethod delete_households_with_name(name, allow_partial_match=False)¶

Delete all households with the specified name.

Parameters:	name (str) – The name of the households to delete. allow_partial_match (bool) – If True, households only need to contain the name to match.
Returns:	True, if Households were deleted successfully. False, if not.
Return type:	bool

classmethod get_active_household()¶

Retrieve the Household of the Active Sim.

Returns:	The Household of the Active Sim or None if no household is found.
Return type:	Union[Household, None]

classmethod get_active_household_id()¶

Retrieve an identifier for the Household of the Active Sim.

Returns:	The identifier of the Household of the Active Sim.
Return type:	int

classmethod get_all_households_generator()¶

Retrieve a collection of all households.

Returns:	An iterator of all Households.
Return type:	Iterator[Household]

classmethod get_free_household_slots(sim_info)¶

Retrieve the number of free household slots in the Household of the specified Sim.

Note

Max household slots in vanilla Sims 4 is 8 sims.

Parameters:	sim_info (SimInfo) – The Sim whose household will be checked.
Returns:	The number of free household slots or -1 if no Household is found for the specified Sim.
Return type:	int

classmethod get_household(sim_info)¶

Retrieve the household of a Sim.

Parameters:	sim_info (SimInfo) – The Sim whose household will be retrieved.
Returns:	The Household of the specified Sim or None if no household is found.
Return type:	Union[Household, None]

classmethod get_household_home_lot_id(household)¶

Retrieve the decimal identifier of the home Lot for a Household.

Parameters:	household (Household) – An instance of a Household.
Returns:	The home zone identifier of the specified Household or -1 if a problem occurs.
Return type:	int

classmethod get_household_home_zone_id(household)¶

Retrieve the home zone identifier for a Household.

Parameters:	household (Household) – An instance of a Household.
Returns:	The home zone identifier of the specified Household or -1 if a problem occurs.
Return type:	int

classmethod get_household_id(sim_info)¶

Retrieve an identifier for the Household a Sim is a part of.

Parameters:	sim_info (SimInfo) – The Sim whose household will be retrieved.
Returns:	The identifier of the Household of the specified Sim or 0 if no household is found.
Return type:	int

classmethod get_household_id_owning_current_lot()¶

Retrieve the decimal identifier of the Household that owns the current Lot.

Returns:	A decimal identifier of the Household that owns the current Lot or -1 if a problem occurs.
Return type:	int

classmethod get_household_id_owning_lot(lot)¶

Retrieve the decimal identifier of the Household that owns a Lot.

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

classmethod get_household_lot_id(sim_info)¶

Retrieve an identifier for the home Lot of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to retrieve the household Lot id of.
Returns:	The identifier of the Household Lot for the Sim.
Return type:	int

classmethod get_household_members_from_household_gen(sim_info)¶

Retrieve the Sims within a Household.

Parameters:	household (Household) – An instance of a Household
Returns:	An iterator of Sims within the specified household.
Return type:	Iterator[SimInfo]

classmethod get_household_members_gen(sim_info)¶

Retrieve the Sims within the household of a Sim.

Note

The result will include the specified Sim as well.

Parameters:	sim_info (SimInfo) – The info of a Sim.
Returns:	An iterator of Sims within the household of the specified Sim.
Return type:	Iterator[SimInfo]

classmethod get_household_owning_current_lot()¶

Retrieve the Household that owns the current Lot.

Returns:	A decimal identifier of the Household that owns the current Lot or None if no Household owns the current Lot.
Return type:	Union[Household, None]

classmethod get_household_owning_lot(lot)¶

Retrieve the Household that owns a Lot.

Parameters:	lot (Lot) – An instance of a Lot.
Returns:	A decimal identifier of the Household that owns the specified Lot or None if no Household owns the specified Lot.
Return type:	Union[Household, None]

classmethod get_household_zone_id(sim_info)¶

Retrieve an zone identifier for the home Lot of the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim to retrieve the household Lot id of.
Returns:	The zone identifier of the Household the Sim belongs to.
Return type:	int

classmethod get_id(household)¶

Retrieve the decimal identifier of a Household.

Parameters:	household – An instance of a Household.
Type:	Household
Returns:	The identifier of the Household or 0 if an error occurs.
Return type:	int

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:	The identifier for the log
Return type:	str

classmethod get_mod_identity()¶

Retrieve the identity of the mod that owns the class.

Warning

Override this function with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:	An instance of CommonModIdentity
Return type:	CommonModIdentity
Raises:	NotImplementedError – Thrown when the function is not implemented.

classmethod get_number_of_sims_in_household(household)¶

Determine the number of Sims in the specified Household.

Parameters:	household (Household) – An instance of a Household.
Returns:	The number of Sims in the specified Household.
Return type:	int

classmethod get_number_of_sims_in_household_of_sim(sim_info)¶

Determine the number of Sims in the household of the specified Sim.

Parameters:	sim_info – An instance of a Sim.
Type:	sim_info: SimInfo
Returns:	The number of Sims in the household of the specified Sim.
Return type:	int

classmethod get_sim_info_of_all_sims_in_active_household_generator()¶

Retrieve a collection of Sims that are a part of the active household.

Returns:	An iterator of Sims in the active household.
Return type:	Iterator[SimInfo]

classmethod get_sim_info_of_all_sims_in_household_generator(household)¶

Retrieve a collection of Sims that are a part of the active household.

Parameters:	household (Household) – The Household to retrieve Sims from.
Returns:	An iterator of Sims in the specified Household.
Return type:	Iterator[SimInfo]

classmethod has_free_household_slots(sim_info)¶

Determine if the Household of the specified Sim has any free Sim slots.

Note

Max household slots in vanilla Sims 4 is 8 sims.

Parameters:	sim_info (SimInfo) – The Sim whose household will be checked.
Returns:	True, if there are free slots for new Sims in the Household of the specified Sim. False, if not.
Return type:	bool

classmethod has_household(sim_info)¶

Determine if the Sim is part of a Household.

Parameters:	sim_info (SimInfo) – The Sim whose household will be checked.
Returns:	True, if the Sim is part of a Household. False, if not.
Return type:	bool

classmethod is_alone_on_home_lot(sim_info)¶

Determine if a Sim is alone on their home lot.

Parameters:	sim_info – An instance of a Sim.
Type:	sim_info: SimInfo
Returns:	True, if the Sim is on their home lot and alone. False, if not.
Return type:	bool

classmethod is_in_same_household(sim_info, target_sim_info)¶

Determine if two Sims are in the same household.

Parameters:	sim_info (SimInfo) – The Sim whose household will be checked. target_sim_info (SimInfo) – The Target whose household will be checked.
Returns:	True, if the Sim is part of same Household as the Target Sim. False, if not.
Return type:	bool

classmethod is_part_of_a_single_sim_household(sim_info)¶

Determine if a Sim is the only Sim in their Household (Single Sim Household).

Parameters:	sim_info – An instance of a Sim.
Type:	sim_info: SimInfo
Returns:	True, if specified Sim is the only Sim in their Household (Single Sim Household). False, if not.
Return type:	bool

classmethod is_part_of_active_household(sim_info)¶

Determine if a Sim is part of the active household.

Returns:	True, if the Sim is part of the Active Household. False, if not.
Return type:	bool

classmethod locate_household_by_id(household_id)¶

Locate a household with the specified id.

Parameters:	household_id (int) – The decimal identifier of a Household.
Returns:	The Household with an identifier matching the specified identifier or None if no Household was found.
Return type:	Union[Household, None]

classmethod locate_household_by_name(name, allow_partial_match=False, create_on_missing=False, starting_funds=0, as_hidden_household=False)¶

Locate a household with the specified name.

Parameters:	name (str) – The name of a household to locate. allow_partial_match (bool, optional) – If True, households only need to contain the name to match. create_on_missing (bool, optional) – If True, a household will be created if one isn’t found with the specified name. starting_funds (int, optional) – If a household is created, this will be the starting funds of that household. as_hidden_household (bool, optional) – If True, the created household will be hidden.
Returns:	A Household with the specified name or None if no household is found.
Return type:	Union[Household, None]

classmethod locate_households_by_name_generator(name, allow_partial_match=False)¶

Locate all households with the specified name.

Parameters:	name (str) – The name of the households to locate. allow_partial_match (bool, optional) – If True, households only need to contain the name to match.
Returns:	An iterator of Households with the specified name.
Return type:	Iterator[Household]

classmethod move_sim_to_household(sim_info, household_id=None, destroy_if_empty_household=True)¶

Move a Sim to the specified household or a new household if no Household is specified.

Parameters:	sim_info (SimInfo) – The Sim to add. household_id (int) – The identifier of the Household to add the Sim to. destroy_if_empty_household (bool, optional) – If True, if the Sim comes from a household containing only them, then it will be destroyed after they are moved.
Returns:	True, if the Sim was added to the Household successfully. False, if not.
Return type:	bool

Creation¶

Spawn, Despawn, Destroy¶

Crafting¶

class CommonSimCraftingUtils¶

Bases: object

Utilities for crafting various things.

static create_from_recipe(crafting_sim_info, recipe_id, inventory_target=None, set_target_as_owner=True, owning_household_id_override=None, post_add=None, seeded_random=None)¶

Craft an item made by a Sim using a recipe and placing it in the inventory of an object or a Sim.

Note

inventory_target must have an inventory_component attribute.

Parameters:	crafting_sim_info (SimInfo) – The name of this Sim will appear on the crafted object as being the crafter. recipe_id (int) – The decimal identifier of a recipe for the object being created. inventory_target (Union[GameObject, Sim]) – If set, the crafted object will be placed in the inventory of this object. If not set, the crafted object will be placed in the inventory of the Sim that crafted it. Default is None. set_target_as_owner (bool, optional) – If True, the inventory where the crafted item will be placed will become the owner of the crafted item. If False, the crafted item will be owned by the one who created it. Default is True. owning_household_id_override (int, optional) – An override for which household to set as the owner of the crafted object. If not specified, then the crafting Sim will be the owner. If set_target_as_owner is True, then the target will be the owner regardless of what this argument is set to. Default is None. post_add (Callable[[GameObject], None], optional) – A callback invoked when the object is created. Default is None. seeded_random (Random, optional) – An instance of Random that will be used in various aspects of the created object. Default is None. quality (CommonObjectQuality, optional) – The quality of the output object. Default is None.
Returns:	The crafted item, created from the specified recipe by the specified Sim, or None if an error occurs.
Return type:	Union[GameObject, None]

Misc¶

Sim¶

class CommonSimUtils¶

Bases: object

Utilities for retrieving Sims in different ways.

Note

Available commands:

s4clib_testing.display_name_of_currently_active_sim
s4clib_testing.display_names_of_all_sims

classmethod get_active_sim()¶

Retrieve a Sim object of the Currently Active Sim.

Note

The Active Sim is the Sim with the Plumbob above their head.

Returns:	An instance of the Active Sim or None if not found.
Return type:	Union[Sim, None]

classmethod get_active_sim_id()¶

Retrieve the decimal identifier for the Currently Active Sim.

Note

The Active Sim is the Sim with the Plumbob above their head.

Returns:	The decimal identifier of the active Sim or -1 if the active Sim does not have an id or if no active Sim was found.
Return type:	int

classmethod get_active_sim_info()¶

Retrieve a SimInfo object of the Currently Active Sim.

Returns:	The SimInfo of the Active Sim or None if not found.
Return type:	Union[SimInfo, None]

classmethod get_all_sims_generator(include_sim_callback=None, allow_hidden_flags=ALL_HIDDEN_REASONS)¶

Retrieve a Sim object for each and every Sim (including hidden Sims).

Parameters:	include_sim_callback (Callable[[SimInfo], bool], optional) – If the result of this callback is True, the Sim will be included in the results. If set to None, All Sims will be included. allow_hidden_flags (HiddenReasonFlag, optional) – Flags to indicate the types of hidden Sims to consider as being instanced. Default is ALL_HIDDEN_REASONS
Returns:	An iterator of all Sims matching the include_sim_callback filter.
Return type:	Iterator[Sim]

classmethod get_instanced_sim_info_for_all_sims_generator(include_sim_callback=None, allow_hidden_flags=HiddenReasonFlag.NONE)¶

Retrieve a SimInfo object for each and every Sim.

Note

Only SimInfo with a Sim instance (get_sim_instance()) will be returned.

Parameters:	include_sim_callback (Callable[[SimInfo], bool], optional) – If the result of this callback is True, the Sim will be included in the results. If set to None, All Sims will be included. allow_hidden_flags (HiddenReasonFlag, optional) – Flags to indicate the types of hidden Sims to consider as being instanced. Default is ALL_HIDDEN_REASONS
Returns:	An iterator of all Sims matching the include_sim_callback filter.
Return type:	Iterator[SimInfo]

classmethod get_sim_id(sim_identifier)¶

Retrieve a SimId (int) from a Sim identifier.

Parameters:	sim_identifier (Union[int, Sim, SimInfo, SimInfoBaseWrapper]) – The identifier or instance of a Sim.
Returns:	The decimal identifier for the Sim instance or 0 if a problem occurs.
Return type:	int

classmethod get_sim_info(sim_identifier)¶

Retrieve a SimInfo instance from a Sim identifier.

Parameters:	sim_identifier (Union[int, Sim, SimInfo, SimInfoBaseWrapper]) – The identifier or instance of a Sim to use.
Returns:	The SimInfo of the specified Sim instance or None if SimInfo is not found.
Return type:	Union[SimInfo, SimInfoBaseWrapper, None]

classmethod get_sim_info_for_all_sims_generator(include_sim_callback=None)¶

Retrieve a SimInfo object for each and every Sim.

Parameters:	include_sim_callback (Callable[[SimInfo], bool], optional) – If the result of this callback is True, the Sim will be included in the results. If set to None, All Sims will be included.
Returns:	An iterator of all Sims matching the include_sim_callback filter.
Return type:	Iterator[SimInfo]

classmethod get_sim_info_for_all_sims_with_first_name_generator(first_name)¶

Retrieve a SimInfo object for each and every Sim with the specified First Name.

Parameters:	first_name (str) – A first name to look for.
Returns:	An iterator of Sims found with the specified first name.
Return type:	Iterator[SimInfo]

classmethod get_sim_info_for_all_sims_with_last_name_generator(last_name)¶

Retrieve a SimInfo object for each and every Sim with the specified Last Name.

Parameters:	last_name (str) – A last name to look for.
Returns:	An iterator of Sims found with the specified last name.
Return type:	Iterator[SimInfo]

classmethod get_sim_info_for_all_sims_with_name_generator(first_name, last_name)¶

Retrieve a SimInfo object for each and every Sim with the specified First and Last Name.

Parameters:	first_name (str) – A first name to look for. last_name (str) – A last name to look for.
Returns:	An iterator of Sims found with the specified first and last name.
Return type:	Iterator[SimInfo]

classmethod get_sim_info_manager()¶

Retrieve the manager that manages the Sim Info of all Sims in a game world.

Returns:	The manager that manages the Sim Info of all Sims in a game world.
Return type:	SimInfoManager

classmethod get_sim_info_of_sim_with_name(first_name, last_name)¶

Retrieve a SimInfo object for the first Sim with the specified First and Last Name.

Parameters:	first_name (str) – A first name to look for. last_name (str) – A last name to look for.
Returns:	The first Sim found with the specified first and last name or None if no Sim is found.
Return type:	Union[SimInfo, None]

classmethod get_sim_instance(sim_identifier, allow_hidden_flags=HiddenReasonFlag.NONE)¶

Retrieve a Sim instance from a Sim identifier.

Parameters:	sim_identifier (Union[int, Sim, SimInfo]) – The identifier or instance of a Sim to use. allow_hidden_flags (HiddenReasonFlag, optional) – Flags to indicate the types of hidden Sims to consider as being instanced. Default is ALL_HIDDEN_REASONS
Returns:	The instance of the specified Sim or None if no instance was found.
Return type:	Union[Sim, None]

classmethod is_active_sim(sim_info)¶

Determine if a Sim is the active Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the specified Sim is the active Sim. False, if not.
Return type:	bool

Autonomy¶

class CommonSimAutonomyUtils¶

Bases: object

Utilities for manipulating the autonomy of Sims.

static get_autonomy_state(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a28e490>) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a28e2d0>¶

get_autonomy_state_setting(sim_info)

Retrieve the current autonomy state of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.

static has_autonomy_state(sim_info, autonomy_state)¶

Determine if the autonomy state of a Sim matches an autonomy state.

Parameters:	sim_info (SimInfo) – An instance of a Sim. autonomy_state (AutonomyState) – An autonomy state.
Returns:	True, if the autonomy state of the Sim matches the specified autonomy state. False, if not.
Return type:	bool

static has_disabled_autonomy(sim_info)¶

Determine if the autonomy state of a Sim is set to Disabled.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the autonomy state of the Sim is set to Disabled. False, if not.
Return type:	bool

static has_full_autonomy(sim_info)¶

Determine if the autonomy state of a Sim is set to Full.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the autonomy state of the Sim is set to Full. False, if not.
Return type:	bool

static has_limited_autonomy(sim_info)¶

Determine if the autonomy state of a Sim is set to Limited Only.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the autonomy state of the Sim is set to Limited Only. False, if not.
Return type:	bool

static has_medium_autonomy(sim_info)¶

Determine if the autonomy state of a Sim is set to Medium.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the autonomy state of the Sim is set to Medium. False, if not.
Return type:	bool

static has_scoring_preference_for_object(sim_info, preference_tag, game_object)¶

Determine if a Sim will have a scoring preference for an Object when searching for Objects to use with a Tag.

Parameters:	sim_info (SimInfo) – An instance of a Sim. preference_tag (CommonObjectPreferenceTag) – The tag to look for preference with. game_object (GameObject) – An instance of an Object.
Returns:	True, if the Sim will have a scoring preference to use the specified Object when searching for Objects to use with the specified Tag. False, if not.
Return type:	bool

static has_use_preference_for_object(sim_info, preference_tag, game_object)¶

Determine if a Sim will have a preference for an Object when searching for Objects to use with a Tag.

Parameters:	sim_info (SimInfo) – An instance of a Sim. preference_tag (CommonObjectPreferenceTag) – The tag to look for preference with. game_object (GameObject) – An instance of an Object.
Returns:	True, if the Sim will prefer to use the specified Object when searching for Objects to use with the specified Tag. False, if not.
Return type:	bool

Career¶

Club¶

class CommonSimClubUtils¶

Bases: object

Utilities for manipulating the Clubs of Sims.

static are_part_of_same_club_gathering(sim_info_a, sim_info_b)¶

Determine if two Sims are at the same Club Gathering

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is taking part in the same Club Gathering as Sim B. False, if not.
Return type:	bool

static get_clubs_currently_gathering_gen(include_club_callback=CommonFunctionUtils.noop_true)¶

Retrieve all Clubs the Sim is in that are currently hosting a gathering.

Parameters:	sim_info (SimInfo) – An instance of a Sim. include_club_callback (Callable[[Club], bool], optional) – If the result of this callback is True, the Club will be included in the results. The default callback will allow all.
Returns:	An iterator of all Clubs the Sim is in that are currently gathering and that pass the include_club_callback filter.
Return type:	Iterator[Club]

static get_clubs_gen(sim_info, include_club_callback=CommonFunctionUtils.noop_true)¶

Retrieve all Clubs a Sim is a part of.

Parameters:	sim_info (SimInfo) – An instance of a Sim. include_club_callback (Callable[[Club], bool], optional) – If the result of this callback is True, the Club will be included in the results. The default callback will allow all.
Returns:	An iterator of all Clubs the specified Sim is a part of and that pass the include callback filter.
Return type:	Iterator[Club]

static get_current_club_gathering(sim_info)¶

Retrieve the Club Gathering a Sim is currently taking part in.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The Club Gathering the specified Sim is a part of or None if the Sim is not a part of any Club Gathering.
Return type:	Union[ClubGatheringSituation, None]

static is_engaged_in_club_gathering(sim_info)¶

Determine if a Sim is engaged in a Club Gathering.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim is engaged in a Club Gathering. False, if not.
Return type:	bool

Gender Options¶

Gender Preferences¶

class CommonSimGenderPreferenceUtils¶

Bases: object

Utilities for Sim gender preferences.

HIGH_PREFERENCE_THRESHOLD = 80¶

LOW_PREFERENCE_THRESHOLD = 20¶

classmethod determine_preferred_genders(sim_info, like_threshold=None, love_threshold=None, preference_type=GenderPreferenceType.ROMANTIC)¶

Determine which genders a Sim prefers.

Note

The math is as follows (The first match will return):

Default Gender Preferences = MALE_PREF < like_threshold and FEMALE_PREF < like_threshold
Prefers both Genders = absolute(MALE_PREF - FEMALE_PREF) <= love_threshold
Prefers Male = MALE_PREF > FEMALE_PREF
Prefers Female = FEMALE_PREF > MALE_PREF

Parameters:	sim_info (SimInfo) – An instance of a Sim. like_threshold (int, optional) – A value indicating a low amount of preference. Default is cls.LOW_PREFERENCE_THRESHOLD. (This argument is obsolete, do not use) love_threshold (int, optional) – A value indicating a high amount of preference. Default is cls.HIGH_PREFERENCE_THRESHOLD. (This argument is obsolete, do not use) preference_type (GenderPreferenceType, optional) – The type of preference to use. Default is GenderPreferenceType.ROMANTIC.
Returns:	A collection of CommonGenders the specified Sim prefers.
Return type:	Tuple[CommonGender]

static get_default_preferred_genders(sim_info)¶

Retrieve a collection of default gender preferences.

Note

By default Male Sims prefer Female Sims and Female Sims prefer Male Sims.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	A collection of the default preferred genders.
Return type:	Tuple[CommonGender]

static get_gender_preference_amount(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a0fba90>, gender: sims4communitylib.enums.common_gender.CommonGender, preference_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd19024490> = <sphinx.ext.autodoc.importer._MockObject object>) → int¶

get_gender_preference_value(sim_info, gender, preference_type=GenderPreferenceType.ROMANTIC)

Retrieve the amount a Sim prefers the specified gender.

Parameters:	sim_info (SimInfo) – An instance of a Sim. gender (CommonGender) – An instance of a gender. preference_type (GenderPreferenceType, optional) – The type of preference to use. Default is GenderPreferenceType.ROMANTIC.
Returns:	The amount the Sim prefers the specified gender.
Return type:	int

static has_preference_for(sim_info, target_sim_info, like_threshold=None, love_threshold=None, preference_type=GenderPreferenceType.ROMANTIC)¶

Determine if a Sim has a preference for another Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. target_sim_info (SimInfo) – An instance of a Sim. like_threshold (int, optional) – A value indicating a low amount of preference. Default is CommonSimGenderPreferenceUtils.LOW_PREFERENCE_THRESHOLD. (This argument is obsolete, do not use) love_threshold (int, optional) – A value indicating a high amount of preference. Default is CommonSimGenderPreferenceUtils.HIGH_PREFERENCE_THRESHOLD. (This argument is obsolete, do not use) preference_type (GenderPreferenceType, optional) – The type of preference to use. Default is GenderPreferenceType.ROMANTIC.
Returns:	True, if the Source Sim has a preference for the Target Sim. False, if not.
Return type:	bool

static has_preference_for_gender(sim_info, gender, like_threshold=None, love_threshold=None, preference_type=GenderPreferenceType.ROMANTIC)¶

Determine if a Sim has a preference for the specified gender.

Parameters:	sim_info (SimInfo) – An instance of a Sim. gender (CommonGender) – An instance of a CommonGender. like_threshold (int, optional) – A value indicating a low amount of preference. Default is CommonSimGenderPreferenceUtils.LOW_PREFERENCE_THRESHOLD. (This argument is obsolete, do not use) love_threshold (int, optional) – A value indicating a high amount of preference. Default is CommonSimGenderPreferenceUtils.HIGH_PREFERENCE_THRESHOLD. (This argument is obsolete, do not use) preference_type (GenderPreferenceType, optional) – The type of preference to use. Default is GenderPreferenceType.ROMANTIC.
Returns:	True, if the Sim has a preference for the specified gender. False, if not.
Return type:	bool

static set_gender_preference_amount(sim_info, gender, amount, preference_type=GenderPreferenceType.ROMANTIC)¶

Set the amount a Sim prefers the specified gender.

Parameters:	sim_info (SimInfo) – An instance of a Sim. gender (CommonGender) – An instance of a gender. amount (int) – The amount the Sim prefers the specified gender. preference_type (GenderPreferenceType, optional) – The type of preference to use. Default is GenderPreferenceType.ROMANTIC.
Returns:	True, if successfully set. False, it not.
Return type:	bool

static set_preference_for_gender(sim_info, gender, is_attracted_to_gender, preference_type=GenderPreferenceType.ROMANTIC)¶

Set the preference a Sim has for a gender.

Parameters:	sim_info (SimInfo) – An instance of a Sim. gender (CommonGender) – An instance of a gender. is_attracted_to_gender (Union[bool, None]) – True, if you want the Sim to be attracted to the gender. False, if you want the Sim to NOT be attracted to the gender. None, if you want the Sim to have no preferences. preference_type (GenderPreferenceType, optional) – The type of preference to use. Default is GenderPreferenceType.ROMANTIC.
Returns:	True, if successfully set. False, it not.
Return type:	CommonExecutionResult

classmethod set_to_default_gender_preferences(sim_info)¶

Set a Sim to the default gender preferences.

Parameters:	sim_info (SimInfo) – An instance of a Sim.

Interactions¶

Inventory¶

class CommonSimInventoryUtils¶

Bases: object

Utilities for manipulating the inventory of Sims.

classmethod add_to_inventory(sim_info, object_definition_id, count=1, on_added=CommonFunctionUtils.noop)¶

Add a number of Newly Created Objects to the Inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. object_id (int) – The decimal identifier of an Object. count (int, optional) – The number of the specified Object to add. Default is 1. on_added (Callable[[GameObject], None]) – A callback invoked when the object is added to the inventory.
Returns:	True, if the count of the specified Object were added successfully. False, it not.
Return type:	bool

classmethod get_all_objects_in_inventory_gen(sim_info, include_object_callback=None)¶

Retrieve all Objects in the inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. include_object_callback (Callable[[int], bool], optional) – If the result of this callback is True, the object will be included in the results. If set to None, All objects in the inventory will be included.
Returns:	An iterator containing the decimal identifiers for the objects in the inventory of a Sim.
Return type:	Iterator[GameObject]

classmethod get_count_of_object_in_inventory(sim_info, object_id)¶

Count the number of an Object in the inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. object_id (int) – The decimal identifier of an object.
Returns:	The number of the specified Object in the inventory of the specified Sim.
Type:	int

classmethod get_inventory(sim_info)¶

Retrieve the inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The inventory component of the Sim or None if not found.
Return type:	Union[SimInventoryComponent, None]

classmethod has_inventory(sim_info)¶

Determine if a Sim has an inventory.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim has an inventory. False, if not.
Return type:	bool

classmethod make_inventory_hidden(sim_info)¶

Change the flags of the inventory of a Sim so that it becomes hidden to the player.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the inventory of the specified Sim was made hidden. False, if not.
Return type:	bool

classmethod make_inventory_visible(sim_info)¶

Change the flags of the inventory of a Sim so that it becomes visible to the player.

Note

A Sim needs to be Instances in order to have an inventory to make visible.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the inventory of the specified Sim was made visible. False, if not.
Return type:	bool

classmethod move_object_to_inventory(sim_info, game_object)¶

Move an Object to the inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. game_object (GameObject) – An instance of an Object.
Returns:	True, if the object was successfully moved to the inventory of the specified Sim. False, if not.
Return type:	bool

classmethod move_objects_to_inventory(sim_info, game_objects)¶

Move Objects to the inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. game_objects (GameObject) – A collection of Object instances.
Returns:	True, if all objects were successfully moved to the inventory of the specified Sim. False, if not.
Return type:	bool

classmethod open_inventory(sim_info)¶

Open the inventory of a Sim.

Parameters:	sim_info (SimInfo) – The Sim to open the inventory of.

classmethod remove_from_inventory(sim_info, object_id, count=1)¶

Remove a number of Objects from the inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. object_id (int) – The decimal identifier of an Object. count (int, optional) – The amount of the Object to remove. Default is 1.
Returns:	True, if the count of the specified Object were removed successfully. False, if not.

classmethod remove_from_inventory_by_definition(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272d9b90>, object_definition: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd29abbe50>, count: int = 1) → bool¶

remove_from_inventory(sim_info, object_id, count=1)

Remove a number of Objects from the inventory of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. object_definition (ObjectDefinition) – The definition of an Object. count (int, optional) – The amount of the Object to remove. Default is 1.
Returns:	True, if the count of the specified Object were removed successfully. False, if not.

classmethod set_ownership_of_all_items_in_sim_inventory_to_sim(sim_info_a, sim_info_b)¶

Change the ownership status of all items in the inventory of Sim A to be owned by the household of Sim B

Parameters:	sim_info_a (SimInfo) – The objects in the inventory of this Sim will become owned by the household of Sim B sim_info_b (SimInfo) – The household of this Sim will be the new owner for all items in the inventory of Sim A.
Returns:	True, if ownership was transferred successfully. False, if not.
Return type:	bool

Loot Actions¶

class CommonSimLootActionUtils¶

Bases: object

Utilities for manipulating Loot Actions for Sims.

static apply_loot_actions_by_id_to_duo_sims(loot_actions_id, sim_info_actor, sim_info_target)¶

Apply loot actions by decimal identifier to two Sims at once.

Parameters:	loot_actions_id (int) – The decimal identifier of a loot actions instance to apply. sim_info_actor (SimInfo) – The Actor Sim to apply the loot actions to. sim_info_target (SimInfo) – The Target Sim to apply the loot actions to.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

static apply_loot_actions_by_id_to_sim(loot_actions_id, sim_info)¶

Apply loot actions to a Sim.

Parameters:	loot_actions_id (int) – The decimal identifier of a loot actions instance to apply. sim_info (SimInfo) – The Sim to apply the loot actions to.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

static apply_loot_actions_by_ids_to_duo_sims(loot_actions_ids: Tuple[int], sim_info_actor: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a363710>, sim_info_target: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a363710>) → bool¶

apply_loot_actions_by_id_to_duo_sims(loot_actions_ids, sim_info_actor, sim_info_target)

Apply loot actions by decimal identifiers to two Sims at once.

Parameters:	loot_actions_ids (Tuple[int]) – The decimal identifiers of the loot actions to apply. sim_info_actor (SimInfo) – The Actor Sim to apply the loot actions to. sim_info_target (SimInfo) – The Target Sim to apply the loot actions to.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

static apply_loot_actions_by_ids_to_sim(loot_actions_ids, sim_info)¶

Apply loot actions to a Sim.

Parameters:	loot_actions_ids (Tuple[int]) – The decimal identifiers of the loot actions to apply. sim_info (SimInfo) – The Sim to apply the loot actions to.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

static apply_loot_actions_to_duo_sims(loot_actions, sim_info_actor, sim_info_target)¶

Apply loot actions to two Sims at once.

Parameters:	loot_actions (LootActions) – The loot actions to apply. sim_info_actor (SimInfo) – The Actor Sim to apply the loot actions to. sim_info_target (SimInfo) – The Target Sim to apply the loot actions to.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

static apply_loot_actions_to_sim(loot_actions, sim_info)¶

Apply loot actions to a Sim.

Parameters:	loot_actions (LootActions) – The loot actions to apply. sim_info (SimInfo) – The Sim to apply the loot actions to.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

Relationships¶

class CommonRelationshipUtils¶

Bases: object

Utilities for manipulating relationship bits, tracks, etc.

classmethod add_relationship_bit(sim_info, target_sim_info, relationship_bit_id)¶

Add a relationship bit between two sims.

Note

If the relationship bit is UNIDIRECTIONAL, it will only be added to sim_info in the direction of the Target. i.e. Sim will have relationship bit towards Target, but Target will not have relationship bit towards Sim.

One example is the Caregiver relationship:

Sim is caregiver of Target.
Target is being cared for by Sim.

Parameters:	sim_info (SimInfo) – The source Sim of the Relationship Bit. target_sim_info (SimInfo) – The target Sim of the Relationship Bit. relationship_bit_id (Union[int, CommonRelationshipBitId]) – The identifier of the Relationship Bit to add.
Returns:	True, if the relationship bit was added successfully. False, if not.
Return type:	CommonExecutionResult

classmethod are_blood_relatives(sim_info_a, sim_info_b)¶

Determine if two Sims are blood relatives.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	True, if Sim A is blood relative of Sim B. False, if not.
Return type:	bool

classmethod calculate_average_relationship_level(sim_info, target_sim_info)¶

Calculate an average level for Friendship and Romance between two Sims.

Note

Math: (Friendship Level + Romance Level)/2

Note

Example Levels:: Friendship Level: 10 Romance Level: 20 Average: 15

Parameters:	sim_info (SimInfo) – The Sim to use. target_sim_info (SimInfo) – The Target Sim to use.
Returns:	The average level of friendship and romance between two Sims.
Return type:	float

classmethod change_relationship_level_of_sims(sim_info, target_sim_info, relationship_track_id, level)¶

Change the level of a relationship track between two Sims.

Parameters:	sim_info (SimInfo) – The sim that owns the relationship track. target_sim_info (SimInfo) – The target of the relationship track. relationship_track_id (: Union[int, CommonRelationshipTrackId]) – The identifier of the Relationship Track to change. level (float) – The amount to add to the relationship track (Can be positive or negative).
Returns:	True, if the relationship track was changed successfully. False, if not.
Return type:	bool

classmethod get_friendship_level(sim_info, target_sim_info)¶

Retrieve the level of Friendship between two Sims.

Note

The return will be “0.0” if a friendship relationship track is not found.

Parameters:	sim_info (SimInfo) – The Sim to use. target_sim_info (SimInfo) – The Target Sim to use.
Returns:	The current level of friendship between two Sims.
Return type:	float

classmethod get_friendship_relationship_track(sim_info_a, sim_info_b)¶

Get an appropriate Friendship Relationship track between Sim A and Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	The decimal identifier of the Friendship Relationship Track appropriate for Sim A to have with Sim B or None if not found.
Return type:	Union[CommonRelationshipTrackId, None]

classmethod get_relationship_level_of_sims(sim_info, target_sim_info, relationship_track_id)¶

Retrieve the level of a relationship track between two sims.

Parameters:	sim_info (SimInfo) – The Sim to check. target_sim_info (SimInfo) – The Target Sim of the relationship track. relationship_track_id (Union[int, CommonRelationshipTrackId]) – An identifier for a Relationship Track to retrieve.
Returns:	The current level between two Sims for the specified Relationship Track.
Return type:	float

classmethod get_relationships_gen(sim_info)¶

Retrieve all relationships a Sim has with other Sims.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	An iterator of Relationships a Sim has with other Sims.
Return type:	Iterator[Relationship]

classmethod get_romance_level(sim_info, target_sim_info)¶

Retrieve the level of Romance between two Sims.

Note

The return will be “0.0” if a romance relationship track is not found.

Parameters:	sim_info (SimInfo) – The Sim to use. target_sim_info (SimInfo) – The Target Sim to use.
Returns:	The current level of romance between two Sims.
Return type:	float

classmethod get_romance_relationship_track(sim_info_a, sim_info_b)¶

Get an appropriate Romance Relationship track between Sim A and Sim B.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	The decimal identifier of the Romance Relationship Track appropriate for Sim A to have with Sim B or None if not found.
Return type:	Union[CommonRelationshipTrackId, None]

classmethod get_romantically_committed_relationship_bits()¶

Retrieve a collection of relationship bits that signify two Sims are in a committed relationship.

Returns:	A collection of relationship bits.
Return type:	Tuple[CommonRelationshipBitId]

classmethod get_sim_info_of_all_sims_romantically_committed_to_generator(sim_info, instanced_only=True)¶

Retrieve a SimInfo object for all Sims romantically committed with the specified Sim.

Note

Romantic Commitments:

Married
Getting Married
Engaged
Significant Other
Promised

Parameters:	sim_info (SimInfo) – The Sim to locate romantically involved Sims with. instanced_only (bool, optional) – If True, only Sims that are currently loaded will be returned.
Returns:	An iterator of Sims the specified Sim is romantically committed to.
Return type:	Iterator[SimInfo]

classmethod get_sim_info_of_all_sims_with_relationship_bit_generator(sim_info, relationship_bit_id, instanced_only=True)¶

Retrieve an Iterator of SimInfo for all Sims that have the specified relationship bit with the specified Sim.

Note

For UNIDIRECTIONAL relationship bits, the direction is sim_info has relationship bit with target_sim_info

Caregiver example:

The Caregiver has a relationship bit pointed at Toddler (The Caregiver would show “caregiving ward” when hovering over the Toddler in the relationships panel)
The Toddler would NOT have the relationship bit.
Sim is Caregiver of Toddler.

Parameters:	sim_info (SimInfo) – The Sim to locate the relationship bit on. relationship_bit_id (Union[int, CommonRelationshipBitId]) – The identifier of the relationship bit to locate connections with. instanced_only (bool, optional) – If True, only Sims that are currently loaded will be returned.
Returns:	An iterator of Sims that have the specified relationship bit with the specified Sim.
Return type:	Iterator[SimInfo]

classmethod get_sim_info_of_all_sims_with_relationship_bits_generator(sim_info, relationship_bit_ids, instanced_only=True)¶

Retrieve an Iterator of SimInfo for all Sims that have the specified relationship bits with the specified Sim.

Note

For UNIDIRECTIONAL relationship bits, the direction is sim_info has relationship bit with target_sim_info Caregiver example:

The Caregiver has a relationship bit pointed at Toddler (The Caregiver would show “caregiving ward” when hovering over the toddler in the relationships panel)
The toddler would NOT have the relationship bit.
Sim is Caregiver of Toddler.

Parameters:	sim_info (SimInfo) – The Sim to locate relationship bits on. relationship_bit_ids (Iterator[Union[int, CommonRelationshipBitId]]) – A collection of identifiers for relationship bits to locate connections with. instanced_only (bool, optional) – If True, only Sims that are currently loaded will be returned.
Returns:	An iterator of Sims that have any of the specified relationship bits with the specified Sim.
Return type:	Iterator[SimInfo]

classmethod has_met(sim_info, target_sim_info)¶

Determine if a Sim has met the Target Sim.

Parameters:	sim_info (SimInfo) – The Sim to check. target_sim_info (SimInfo) – The Target Sim to check.
Returns:	True, if both Sims have met each other. False, if not.
Return type:	bool

classmethod has_permission_for_romantic_relationship_with(sim_info_a: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd18f38950>, sim_info_b: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd18f38950>) → sims4communitylib.classes.testing.common_test_result.CommonTestResult¶: Determine if two Sims are allowed to have a Romantic relationship together.

classmethod has_permission_for_romantic_relationships(sim_info)¶

Determine if a Sim has permission to have romantic relationships with other Sims.

Note

In the vanilla game, only Teen, Adult, and Elder Sims have permission for romantic relationships.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The result of the test. True, if the test passes. False, if the test fails.
Return type:	CommonTestResult

classmethod has_permission_to_be_blood_relative_of(sim_info_a, sim_info_b)¶

Determine if Sim A has permission to be a Blood Relative of Sim B. (Such as Mother, Daughter, etc.)

Note

In the vanilla game, only Sims of the same species have permission to be Blood Relatives.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. sim_info_b (SimInfo) – An instance of a Sim.
Returns:	The result of the test. True, if the test passes. False, if the test fails.
Return type:	CommonTestResult

classmethod has_positive_romantic_combo_relationship_bit_with(sim_info, target_sim_info)¶

Determine if a Sim has a positive romantic combo with the Target Sim.

Note

Positive Romantic Combo Relationship Bits:

Soul Mates
Lovers
Sweethearts
Love Birds

Parameters:	sim_info (SimInfo) – The Sim to check. target_sim_info (SimInfo) – The Target Sim to check.
Returns:	True, if the Sims have positive romantic combo relationship bits with each other. False, if not.
Return type:	bool

classmethod has_relationship_bit_with_any_sims(sim_info, relationship_bit_id, instance_only=True)¶

Determine if a Sim has the specified relationship bit with any Sims.

Parameters:	sim_info (SimInfo) – The Sim to use. relationship_bit_id (Union[int, CommonRelationshipBitId]) – The identifier of the Relationship Bit to check for. instanced_only (bool, optional) – If True, only Sims that are currently loaded will be valid.
Returns:	True, if the Sim has the specified Relationship Bit with any Sims. False, if not.
Return type:	bool

classmethod has_relationship_bit_with_sim(sim_info, target_sim_info, relationship_bit_id)¶

Determine if two Sims have the specified relationship bit with each other.

Parameters:	sim_info (SimInfo) – The Sim to check. target_sim_info (SimInfo) – The Target Sim of the relationship bit (The target is especially important for Unidirectional/One Way Relationship Bits). relationship_bit_id (Union[int, CommonRelationshipBitId]) – The identifier of the Relationship Bit to check for.
Returns:	True, if the Sim has the specified Relationship Bit with the Target Sim. False, if not.
Return type:	bool

classmethod has_relationship_bits_with_any_sims(sim_info, relationship_bit_ids, instanced_only=True)¶

Determine if a Sim has the specified relationship bits with any Sims.

Parameters:	sim_info (SimInfo) – The Sim to use. relationship_bit_ids (int) – A collection of identifier of Relationship Bits to check for. instanced_only (bool, optional) – If True, only Sims that are currently loaded will be valid.
Returns:	True, if the Sim has any of the specified Relationship Bits with any Sims. False, if not.
Return type:	bool

classmethod has_relationship_bits_with_sim(sim_info, target_sim_info, relationship_bit_ids)¶

Determine if two sims have any of the specified relationship bits with each other.

Parameters:	sim_info (SimInfo) – The Sim to check. target_sim_info (SimInfo) – The Target Sim of the relationship bit (The target is especially important for Unidirectional/One Way Relationship Bits). relationship_bit_ids (Iterator[Union[int, CommonRelationshipBitId]]) – A collection of identifier of Relationship Bits to check for.
Returns:	True, if the Sim has any of the specified Relationship Bits with the Target Sim. False, if not.
Return type:	bool

classmethod is_friendly_with(sim_info, target_sim_info)¶

Determine if a Sim is friendly with a Target Sim.

Note

By default, a Sim is friendly with another Sim when their Friendship relationship is at or above 30. If both Sims are Animals, they are friendly with each other if they have the Friendly relationship bit.

Parameters:	sim_info (SimInfo) – The info of a Sim. target_sim_info (SimInfo) – The info of a Sim.
Returns:	True, if the Sim is friendly with the Target Sim. False, if not.
Return type:	bool

classmethod is_romantic_with(sim_info, target_sim_info)¶

Determine if a Sim is romantic with a Target Sim.

Note

By default, a Sim is romantic with another Sim when their Romance relationship is at or above 30.

Parameters:	sim_info (SimInfo) – The info of a Sim. target_sim_info (SimInfo) – The info of a Sim.
Returns:	True, if the Sim is romantic with the Target Sim. False, if not.
Return type:	bool

classmethod is_romantically_committed_to(sim_info, target_sim_info)¶

Determine if a Sim is romantically committed to the Target Sim.

Parameters:	sim_info (SimInfo) – The Sim to check. target_sim_info (SimInfo) – The Target Sim to check.
Returns:	True, if the Sim is romantically committed to the Target Sim. False, if not.
Return type:	bool

classmethod is_romantically_committed_to_any_sims(sim_info)¶

Determine if the Sim is romantically committed to any Sims.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is romantically committed to any Sims. False, if not.
Return type:	bool

classmethod load_relationship_bit_by_id(relationship_bit)¶

Load an instance of a Relationship Bit by its identifier.

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

classmethod load_relationship_track_by_id(relationship_track)¶

Load an instance of a Relationship Track by its identifier.

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

classmethod remove_relationship_bit(sim_info, target_sim_info, relationship_bit_id)¶

Remove a relationship bit between two sims.

Note

If the relationship bit is UNIDIRECTIONAL, it will only be removed from sim_info in the direction of the Target. i.e. Sim will have no longer have relationship bit towards Target, but Target will still have relationship bit towards Sim.

One example is the Caregiver relationship:

Sim is caregiver of Target.
Target is being cared for by Sim.

Parameters:	sim_info (SimInfo) – The source Sim of the Relationship Bit. target_sim_info (SimInfo) – The target Sim of the Relationship Bit. relationship_bit_id (Union[int, CommonRelationshipBitId]) – The identifier of the Relationship Bit to remove.
Returns:	True, if the relationship bit was removed successfully. False, if not.
Return type:	CommonExecutionResult

classmethod remove_relationship_bit_from_all(sim_info, relationship_bit_id)¶

Remove a relationship bit between a Sim and all other Sims.

Note

If the relationship bit is UNIDIRECTIONAL, it will only be removed from sim_info in the direction of the Target. i.e. Sim will have no longer have relationship bit towards Target, but Target will still have relationship bit towards Sim.

One example is the Caregiver relationship:

Sim is caregiver of Target.
Target is being cared for by Sim.

Parameters:	sim_info (SimInfo) – The source Sim of the Relationship Bit. relationship_bit_id (Union[int, CommonRelationshipBitId]) – The identifier of the Relationship Bit to remove.
Returns:	True, if the relationship bit was removed successfully. False, if not.
Return type:	bool

classmethod set_relationship_level_of_sims(sim_info, target_sim_info, relationship_track_id, level)¶

Set the level of a relationship track between two Sims.

Parameters:	sim_info (SimInfo) – The sim that owns the relationship track. target_sim_info (SimInfo) – The target of the relationship track. relationship_track_id (: Union[int, CommonRelationshipTrackId]) – The identifier of the Relationship Track to set. level (float) – The amount to set the relationship track to (Can be positive or negative).
Returns:	True, if the relationship track was set successfully. False, if not.
Return type:	bool

Phone¶

Plumbob¶

class CommonSimPlumbobUtils¶

Bases: object

Utilities for manipulating the Plumbob of a Sim.

static hide_plumbob(sim_info)¶

Hide the plumbob of a Sim.

Note

If the plumbob of the Sim is already hidden, this function will do nothing.

Parameters:	sim_info (SimInfo) – An instance of a Sim.

static reset_plumbob_position(sim_info)¶

Reset the position of the Plumbob for a Sim to it’s original position.

Parameters:	sim_info (SimInfo) – An instance of a Sim.

static set_plumbob_position(sim_info, position, bone_name='b__ROOT__', balloon_position=CommonVector3.empty())¶

Set the position of the Plumbob for a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. position (CommonVector3) – The position to set the plumbob to. bone_name (str, optional) – The name of the bone to slot the Plumbob to. Default is ‘b__ROOT__’ balloon_position (CommonVector3, optional) – The position of the Balloon above Sims heads. Default is CommonVector3.empty().

static show_plumbob(sim_info)¶

Show the plumbob of a Sim.

Note

If the plumbob of the Sim is already shown, this function will do nothing.

Parameters:	sim_info (SimInfo) – An instance of a Sim.

Posture¶

class CommonSimPostureUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for managing the posture of Sims.

classmethod can_sim_be_picked_up(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a764050>) → sims4communitylib.classes.testing.common_test_result.CommonTestResult¶

can_be_picked_up(sim_info)

Determine if a Sim can be picked up.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim can be picked up. False, it not.
Return type:	bool

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:	The identifier for the log
Return type:	str

classmethod get_posture(sim_info)¶

Retrieve the posture of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The posture of a Sim.
Return type:	Union[Posture, None]

classmethod get_posture_aspects(sim_info)¶

Retrieve the posture aspects of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The aspects of the posture of the Sim.
Return type:	Tuple[Posture]

classmethod get_posture_state(sim_info)¶

Retrieve the posture aspects of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The posture state of a Sim.
Return type:	Union[PostureState, None]

classmethod get_posture_target(sim_info)¶

Retrieve the target of the posture of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The target of the posture of a Sim.
Return type:	Union[Any, None]

classmethod has_posture(sim_info, posture)¶

Determine if a Sim has a posture.

Parameters:	sim_info (SimInfo) – An instance of a Sim. posture (Union[int, CommonPostureId, Posture, CommonInt]) – The identifier of the posture to check.

classmethod has_posture_with_sim(sim_info, target_sim_info, posture)¶

Determine if a Sim has a posture with another Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. target_sim_info (SimInfo) – An instance of another Sim. posture (Union[int, CommonPostureId, Posture, CommonInt]) – The identifier of the posture to check.

classmethod is_on_container_supporting_posture(sim_info, posture)¶

Determine if the container a Sim is interacting with has a posture.

Parameters:	sim_info (SimInfo) – An instance of a Sim. posture (Union[int, CommonPostureId, Posture, CommonInt]) – The identifier of the posture to check.

classmethod is_on_container_supporting_posture_with_sim(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a764050>, target_sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a764050>, posture: Union[int, sims4communitylib.enums.common_posture_id.CommonPostureId, <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a6e57d0>, sims4communitylib.enums.enumtypes.common_int.CommonInt]) → sims4communitylib.classes.testing.common_test_result.CommonTestResult¶

is_on_container_supporting_posture(sim_info, target_sim_info, posture)

Determine if the container a Sim is interacting with has a posture that supports another Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. target_sim_info (SimInfo) – An instance of another Sim. posture (Union[int, CommonPostureId, Posture, CommonInt]) – The identifier of the posture to check.

classmethod load_posture_by_id(posture)¶

Load an instance of a Posture by its identifier.

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

Pregnancy¶

class CommonSimPregnancyUtils¶

Bases: sims4communitylib.logging.has_class_log.HasClassLog

Utilities for manipulating the pregnancy status of Sims.

classmethod can_be_impregnated(sim_info)¶

Determine if a Sim can be impregnated.

Parameters:	sim_info (SimInfo) – The Sim being checked.
Returns:	The result of testing. True, if they can. False, if they cannot.
Return type:	CommonTestResult

classmethod can_impregnate(sim_info)¶

Determine if a Sim can impregnate other sims.

Parameters:	sim_info (SimInfo) – The Sim being checked.
Returns:	The result of testing. True, if they can. False, if they cannot.
Return type:	CommonTestResult

classmethod clear_pregnancy(sim_info)¶

Clear the pregnancy status of a Sim.

Parameters:	sim_info (SimInfo) – The Sim being cleared.
Returns:	True, if successful. False, if not.
Return type:	bool

classmethod determine_can_be_impregnated_trait(sim_info)¶

Determine the trait that would indicate a Sim can be impregnated by other Sims.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The trait that would indicate the Sim can be impregnated by other Sims or None if no trait is found.
Return type:	Union[CommonTraitId, None]

classmethod determine_can_impregnate_trait(sim_info)¶

Determine the trait that would indicate a Sim can impregnate other Sims.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The trait that would indicate the Sim can impregnate other Sims or None if no trait is found.
Return type:	Union[CommonTraitId, None]

classmethod determine_can_not_be_impregnated_trait(sim_info)¶

Determine the trait that would indicate a Sim can not be impregnated by other Sims.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The trait that would indicate the Sim can not be impregnated by other Sims or None if no trait is found.
Return type:	Union[CommonTraitId, None]

classmethod determine_can_not_impregnate_trait(sim_info)¶

Determine the trait that would indicate a Sim can not impregnate other Sims.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The trait that would indicate the Sim can not impregnate other Sims or None if no trait is found.
Return type:	Union[CommonTraitId, None]

classmethod determine_pregnancy_statistic(sim_info)¶

Determine the statistic that would indicate the pregnancy progress of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The statistic that would indicate the pregnancy progress of the Sim or None if no trait is found.
Return type:	Union[CommonStatisticId, None]

classmethod get_in_labor_buff(sim_info)¶

Retrieve an In Labor buff appropriate for causing the Sim to go into labor (Give Birth).

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The decimal identifier of a Buff that will cause the specified Sim to go into labor. If no appropriate Buff is found, -1 will be returned.
Return type:	Union[int, CommonBuffId]

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:	The identifier for the log
Return type:	str

classmethod get_mod_identity()¶

Retrieve the identity of the mod that owns the class.

Warning

Override this function with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:	An instance of CommonModIdentity
Return type:	CommonModIdentity
Raises:	NotImplementedError – Thrown when the function is not implemented.

classmethod get_partner_of_pregnant_sim(sim_info)¶

Retrieve a SimInfo object of the Sim that impregnated the specified Sim.

Parameters:	sim_info (SimInfo) – The Sim being checked.
Returns:	The Sim that has impregnated the specified Sim or None if the Sim does not have a partner.
Return type:	Union[SimInfo, None]

classmethod get_pregnancy_partner(sim_info)¶

Retrieve the Sim that caused a Sim to become pregnant.

Parameters:	sim_info (SimInfo) – The Sim to get the partner of.
Returns:	The Sim that impregnated the specified Sim or None if not found.
Return type:	Union[SimInfo, None]

classmethod get_pregnancy_progress(sim_info)¶

Retrieve the pregnancy progress of a Sim.

Parameters:	sim_info (SimInfo) – The Sim being checked.
Returns:	The current progress of the pregnancy of a Sim.
Return type:	float

classmethod get_pregnancy_rate(sim_info)¶

Retrieve the rate at which pregnancy progresses.

Parameters:	sim_info (SimInfo) – The Sim being checked.
Returns:	The rate at which the pregnancy state of a Sim is progressing.
Return type:	float

classmethod get_pregnancy_tracker(sim_info)¶

Retrieve the tracker for tracking pregnancy of a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The pregnancy tracker for the Sim or None if the Sim does not have a pregnancy tracker.
Return type:	Union[PregnancyTracker, None]

classmethod has_permission_for_pregnancies(sim_info)¶

Determine if a Sim has the permissions to cause a Pregnancy or to become Pregnant. (Regardless of traits)

Note

In the vanilla game, only Adult and Elder Sims have permission for pregnancies.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The result of the test. True, if the test passes. False, if the test fails.
Return type:	CommonTestResult

classmethod has_permission_for_pregnancies_with(sim_info_a, sim_info_b)¶

Determine if Sim A has the permissions to cause a Pregnancy with Sim B or to become pregnant from Sim B.

Note

In the vanilla game, only Adult and Elder Sims of the same species have permission for pregnancies with each other.

Parameters:	sim_info_a (SimInfo) – An instance of a Sim. (Sim A) sim_info_b (SimInfo) – An instance of a Sim. (Sim B)
Returns:	The result of the test. True, if the test passes. False, if the test fails.
Return type:	CommonTestResult

classmethod induce_labor_in_sim(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1a927f10>) → bool¶

induce_labor(sim_info)

Induce Labor in a pregnant Sim.

Parameters:	sim_info (SimInfo) – The Sim to go into labor.
Returns:	True, if labor was induced successfully. False, if not.

classmethod is_pregnant(sim_info)¶

Determine if the a Sim is pregnant.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the specified Sim is pregnant. False, if not.
Return type:	bool

classmethod set_pregnancy_progress(sim_info, value)¶

Set the pregnancy progress of a Sim.

Parameters:	sim_info (SimInfo) – The Sim being checked. value (float) – The value to set the progress to.
Returns:	The current progress of the pregnancy of a Sim.
Return type:	float

classmethod start_pregnancy(sim_info, partner_sim_info, pregnancy_origin=PregnancyOrigin.DEFAULT)¶

Start a pregnancy between a Sim and a Partner Sim.

Parameters:	sim_info (SimInfo) – The Sim getting pregnant. partner_sim_info (SimInfo) – The Sim that is getting the other Sim pregnant. pregnancy_origin (PregnancyOrigin, optional) – The origin of the pregnancy. Default is PregnancyOrigin.DEFAULT.
Returns:	True, if the Sim is successfully impregnated by the Partner Sim. False, if not.
Return type:	bool

Rabbit Hole¶

class CommonSimRabbitHoleUtils¶

Bases: object

Utilities for manipulating Rabbit Holes for Sims.

classmethod get_first_rabbit_hole_id_for_sim(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1aa19650>) → Optional[int]¶

get_rabbit_hole_id(sim_info)

Retrieve the id of the rabbit hole a Sim is in.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The id of the first rabbit hole the Sim is in or None if not found.
Return type:	Union[int, None]

classmethod put_sim_into_rabbit_hole(sim_info, rabbit_hole_identifier, on_exit_rabbit_hole_callback=None)¶

Put a Sim into a Rabbit Hole.

Parameters:	sim_info (SimInfo) – An instance of a Sim. rabbit_hole (Union[RabbitHole, int]) – The identifier of a rabbit hole to put the Sim into. on_exit_rabbit_hole_callback (Callable[[SimInfo, bool], None]) – A callback invoked upon the Sim leaving the rabbit hole. Default is None.
Returns:	A result indicating the success of putting the Sim into the rabbit hole.
Return type:	CommonTestResult

classmethod try_remove_sim_from_rabbit_hole(sim_info, on_remove_from_rabbit_hole_result_callback=None)¶

Remove a Sim from a rabbit hole.

Parameters:	sim_info (SimInfo) – An instance of a Sim. on_remove_from_rabbit_hole_result_callback (Callable[[SimInfo, bool], None]) – A callback invoked upon the Sim being removed from the rabbit hole. Default is None.
Returns:	A result indicating the success of the removal.
Return type:	CommonTestResult

Situations¶

class CommonSimSituationUtils¶

Bases: sims4communitylib.logging.has_class_log.HasClassLog

Utilities for manipulating the Situations of Sims.

static complete_situation_goal(sim_info, situation_goal_id, target_sim_info=None, score_override=None, start_cooldown=True)¶

Complete a situation goal for a Sim using the specified Target Sim.

Parameters:

sim_info (SimInfo) – An instance of a Sim.
situation_goal_id (int) – The decimal identifier of a Situation Goal to mark as completed.
target_sim_info (SimInfo, optional) – A target used in the completion of the situation goal. Default is None.
score_override (int, optional) – An alternative score to award to the Sim instead of the score specified by the goal. Default is None.
start_cooldown (bool, optional) – Whether or not to start a cooldown for the situation. Default is True.

static create_situation_for_sim(sim_info, situation_type, creation_source, invite_only=True, user_facing=False, situation_job=None, purpose=SituationInvitationPurpose.INVITED, **__)¶

Create a situation and put a Sim in it.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_type (Type[Situation]) – The type of situation to create. invite_only (bool, optional) – If True, the situation will be invitation only. Default is True. user_facing (bool, optional) – If True, the situation will be visible to the player (Like an Active Situation would be). If False, it will not be visible. Default is False. situation_job (SituationJob, optional) – The Situation Job to assign to the Sim upon situation creation. Default is whatever the situation specifies as the default job. creation_source (str) – The source of creation. purpose (SituationInvitationPurpose, optional) – The purpose of the situation. Default is SituationInvitationPurpose.INVITED.
Returns:	The identifier of the situation that was created or 0 if an error occurs.
Return type:	int

static create_visit_situation(sim_info, duration_override_in_sim_seconds=None, visit_situation_override=None)¶

Create a visit situation for a Sim.

Parameters:	sim_info (SimInfo) – An instance of a Sim. duration_override_in_sim_seconds (int, optional) – An override in Sim seconds for the visit to last. Default is None. visit_situation_override (Situation, optional) – An instance of a Situation to use for the Visit. If not specified, the default visit situation will be used. Default is None.

static get_first_running_situation_sim_is_in_by_tag(sim_info, tag)¶

Retrieve the first Situation that a Sim is currently involved in that has a tag.

Parameters:	sim_info (SimInfo) – An instance of a Sim tag (CommonGameTag) – The tag to locate a situation with.
Returns:	A situation the Sim is involved in that has the specified tag or None if not found.
Return type:	Union[Situation, None]

static get_first_running_situation_sim_is_in_by_type(sim_info, situation_type)¶

Retrieve the first Situation that a Sim is currently involved in that is a specific type.

Parameters:	sim_info (SimInfo) – An instance of a Sim situation_type (Type[Situation]) – A situation type to locate a situation with.
Returns:	A situation the Sim is involved in that is of the specified type or None if not found.
Return type:	Union[Situation, None]

static get_guids_of_all_running_situations_for_sim(sim_info)¶

Retrieve GUIDs for all Situations a Sim is involved in.

Parameters:	sim_info (SimInfo) – The sim to check.
Returns:	A collection of Situation GUIDs the specified Sim is involved in.
Return type:	Tuple[int]

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:	The identifier for the log
Return type:	str

classmethod get_mod_identity()¶

Retrieve the identity of the mod that owns the class.

Warning

Override this function with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:	An instance of CommonModIdentity
Return type:	CommonModIdentity
Raises:	NotImplementedError – Thrown when the function is not implemented.

static get_running_situations_sim_is_in_by_tag(sim_info, tag)¶

Retrieve all Situations that a Sim is currently involved in that have the specified tag.

Parameters:	sim_info (SimInfo) – An instance of a Sim tag (CommonGameTag) – The tag to locate situations with.
Returns:	An iterator of Situations the Sim is running that have the specified tag.
Return type:	Iterator[Situation]

static get_running_situations_sim_is_in_by_tags(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1aa8b090>, tags: Tuple[sims4communitylib.enums.tags_enum.CommonGameTag]) → Tuple[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1aa9b8d0>]¶

get_running_situations_sim_is_in_by_tag(sim_info, tags)

Retrieve all Situations that a Sim is currently involved in that have the specified tag.

Parameters:	sim_info (SimInfo) – An instance of a Sim tags (Iterator[CommonGameTag]) – A collection of tags to locate situations with. Matching situations will have at least one of these tags.
Returns:	An iterator of Situations the Sim is running that have any of the specified tags.
Return type:	Iterator[Situation]

static get_running_situations_sim_is_in_by_type(sim_info, situation_type)¶

Retrieve all Situations that a Sim is currently involved in that match the specified type.

Parameters:	sim_info (SimInfo) – An instance of a Sim situation_type (Type[Situation]) – A situation type to locate situations with.
Returns:	An iterator of Situations the Sim is running that are of the specified type.
Return type:	Iterator[Situation]

static get_situation_goals(sim_info)¶

Retrieve the goals of all situations a Sim is currently in.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	The situation goals of all Situations the Sim is currently involved in.
Return type:	Tuple[Union[SituationGoal, SituationGoalTargetedSim]]

static get_situation_guids(sim_info)¶

Retrieve GUIDs for all Situations a Sim is involved in.

Parameters:	sim_info (SimInfo) – The sim to check.
Returns:	A collection of Situation GUIDs the specified Sim is involved in.
Return type:	List[int]

static get_situation_ids(sim_info)¶

Retrieve decimal identifiers for all Situations a Sim is involved in.

Parameters:	sim_info (SimInfo) – The sim to check.
Returns:	A collection of Situation decimal identifiers the specified Sim is involved in.
Return type:	List[int]

static get_situations(sim_info, include_situation_callback=None)¶

Retrieve all Situations that a Sim is currently involved in.

Parameters:	sim_info (SimInfo) – An instance of a Sim include_situation_callback (Callable[[Situation], bool], optional) – If the result of this callback is True, the Situation will be included in the results. If set to None, All situations will be included. Default is None.
Returns:	An iterator of Situations that pass the include callback filter.
Return type:	Iterator[Situation]

static has_leave_situation(sim_info: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1aa8b090>) → bool¶

has_situation_jobs(sim_info, situation_job_ids)

Determine if a Sim is currently involved in a leaving situation.

Parameters:	sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Sim is currently involved in a leaving situation. False, if not.
Return type:	bool

static has_situation(sim_info, situation_guid)¶

Determine if a Sim is involved in the specified Situation.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_guid (Union[int, CommonSituationId]) – The GUID of a Situation.
Returns:	True, if the Sim is involved in the specified Situation. False, if not.
Return type:	bool

static has_situation_job(sim_info, situation_job_id)¶

Determine if a Sim has been assigned a situation job.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_job_id (int) – The situation job to check for.
Returns:	True, if the Sim has the specified situation job. False, if not.
Return type:	bool

static has_situation_jobs(sim_info, situation_job_ids)¶

Determine if a Sim has been assigned any specified situation jobs.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_job_ids (Tuple[int]) – The situation jobs to check for.
Returns:	True, if the Sim has any of the specified situation jobs. False, if not.
Return type:	bool

static has_situations(sim_info, situation_guids)¶

Determine if a Sim is involved in any of the specified Situations.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_guids (Iterator[Union[int, CommonSituationId]]) – The GUID of Situations.
Returns:	True, if the Sim has any of the specified situations. False, if not.
Return type:	bool

static is_assigned_situation_job(sim_info, situation_job_id)¶

Determine if a Sim is currently assigned a situation job.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_job_id (int) – The decimal identifier of a Situation Job.
Returns:	True, if the Sim is assigned the specified situation job. False, if not.
Return type:	bool

static is_assigned_situation_jobs(sim_info, situation_job_ids)¶

Determine if a Sim is currently assigned any of the specified situation jobs.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_job_ids (Tuple[int]) – A collection of decimal identifier for Situation Jobs.
Returns:	True, if the Sim is assigned any of the specified situation jobs. False, if not.
Return type:	bool

static is_in_situations_of_type(sim_info, situation_type)¶

Determine if a Sim is currently in a situation that is of the a specific type.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_type (Type[Situation]) – The type of situation to check.
Returns:	True, if the Sim is involved in any situations with any of the specified tags. False, if not.
Return type:	bool

static is_in_situations_with_any_tags(sim_info, tags)¶

Determine if a Sim is currently in a situation with any of the specified tags.

Parameters:	sim_info (SimInfo) – An instance of a Sim. tags (Tuple[CommonGameTag]) – A collection of game tags.
Returns:	True, if the Sim is involved in any situations with any of the specified tags. False, if not.
Return type:	bool

static is_in_situations_with_tag(sim_info, tag)¶

Determine if a Sim is currently in a situation with a tag.

Parameters:	sim_info (SimInfo) – An instance of a Sim. tag (CommonGameTag) – A tag to check for.
Returns:	True, if the Sim is involved in any situations with any of the specified tags. False, if not.
Return type:	bool

static make_sim_leave(sim_info)¶

Make a Sim leave the current lot.

Parameters:	sim_info (SimInfo) – An instance of a Sim.

static remove_sim_from_situation(sim_info, situation_id)¶

Remove a Sim from a Situation.

Parameters:	sim_info (SimInfo) – An instance of a Sim. situation_id (int) – The instance identifier of the Situation to remove the Sim from.
Returns:	True, if the Sim was successfully removed from the situation. False, if not.
Return type:	bool

State¶

class CommonSimStateUtils¶

Bases: object

Utilities for checking the state of a sim.

static is_dying(sim_info)¶

Determine if a Sim is currently dying.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the Sim is dying. False, if the Sim is not dying.
Return type:	CommonTestResult

static is_hidden(sim_info)¶

Determine if a Sim is hidden.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is hidden. False, if the Sim is not hidden.
Return type:	bool

static is_in_sunlight(sim_info)¶

Determine if a Sim is in sunlight.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is in sunlight. False, if the Sim is not in sunlight.
Return type:	bool

static is_leaving_zone(sim_info)¶

Determine if a Sim is currently leaving the zone.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is leaving the zone. False, if the Sim is not leaving the zone.
Return type:	bool

static is_visible(sim_info)¶

Determine if a Sim is visible.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	True, if the Sim is visible. False, if the Sim is not visible.
Return type:	bool

static is_wearing_towel(sim_info)¶

Determine if a Sim is wearing a towel.

..warning:: Obsolete: Use is_wearing_towel() in CommonOutfitUtils instead.

Parameters:	sim_info (SimInfo) – The Sim to check.
Returns:	The result of testing. True, if the sim is wearing a towel. False, if not.
Return type:	CommonTestResult