Resource Utilities¶

Clubs¶

Note

To manipulate clubs of Sims, take a look at CommonSimClubUtils

class CommonClubUtils¶

Bases: object

Utilities for manipulating Clubs.

static get_club_members_gen(club, include_club_member_callback=CommonFunctionUtils.noop_true)¶

Retrieve the SimInfo of all members who are a part of a Club.

Parameters:	club (Club) – An instance of a Club. include_club_member_callback (Callable[[SimInfo], bool], optional) – If the result of this callback is True, the Club Member will be included in the results. The default callback will allow all.
Returns:	An iterator of all Sims in a Club that pass the include callback filter.
Return type:	Iterator[SimInfo]

static get_club_rules_gen(club, include_club_rule_callback=CommonFunctionUtils.noop_true)¶

Retrieve all Club Rules of a Club.

Parameters:	club (Club) – An instance of a Club. include_club_rule_callback (Callable[[ClubRule], bool], optional) – If the result of this callback is True, the Club Rule will be included in the results. The default callback will allow all.
Returns:	An iterator of all Club Rules for the specified Club that pass the include callback filter.
Return type:	Iterator[ClubRule]

static get_clubs_currently_gathering_gen(include_club_callback=CommonFunctionUtils.noop_true)¶

Retrieve all Clubs that are currently hosting a gathering.

Parameters:	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 that are currently gathering and that pass the include callback filter.
Return type:	Iterator[Club]

Components¶

class CommonComponentUtils¶

Bases: object

Utilities for handling components of component containers.

static add_dynamic_component(component_container, component_type)¶

Add a dynamic component to a ComponentContainer.

Parameters:	component_container (ComponentContainer) – The ComponentContainer to add to. component_type (CommonComponentType) – The type of component being added.
Returns:	The added Component or None
Return type:	Union[Component, None]

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

Retrieve a component from a ComponentContainer.

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

static has_component(component_container, component_type)¶

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

Parameters:	component_container (ComponentContainer) – The ComponentContainer to check. component_type (CommonComponentType) – The type of component to locate.
Returns:	True, if the ComponentContainer contains a component of the specified type. False, if not.
Return type:	bool

Game Pack¶

class CommonGamePackUtils¶

Bases: object

Utilities for checking various information about Game Packs and their availability.

static get_available_game_packs()¶

Retrieve a collection of all available Game Packs.

Returns:	A collection of all Game Packs currently available and installed.
Return type:	Tuple[Pack]

static get_game_pack_name(game_pack)¶

Retrieve the name of a Game Pack.

Parameters:	game_pack (Pack) – The Game Pack to retrieve the name of.
Returns:	The name of the Game Pack or <Unknown Pack> if not available.
Return type:	str

static has_game_pack_available(game_pack)¶

Whether or not the specified Game Pack is available.

Parameters:	game_pack (Pack) – The Game Pack to check for.
Returns:	True, if the specified Game Pack is available. False, if not.
Return type:	bool

static has_game_packs_available(game_packs)¶

Whether or not the specified Game Pack is available.

Parameters:	game_packs (Tuple[Pack]) – The Game Packs to check for.
Returns:	True, if all of the specified Game Packs are available. False, if any of them are not available.
Return type:	bool

Recipes¶

Resources¶

class CommonResourceUtils¶

Bases: object

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

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

Convert a text string into an FNV32 decimal identifier.

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

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

Convert a text string into an FNV64 decimal identifier.

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

static get_enum_by_int_value(value, enum_type, default_value=None)¶

Retrieve an enum value by its value.

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

static get_enum_by_name(name, enum_type, default_value=None)¶

Retrieve an enum value by its name.

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

static get_instance_manager(instance_manager_type)¶

Get an InstanceManager for the specified type.

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

static get_resource_key(resource_type, resource_key)¶

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

Note

Possible Usages:

Retrieve the identifier of an Icon to display next to an Interaction in the Pie Menu.
Retrieve the identifier of an Image for display in Dialogs or Notifications.

Example Usage:

# This will retrieve the key for the image with identifier 1234
icon_resource_key = CommonResourceUtils.get_resource_key(Types.PNG, 1234)

Parameters:	resource_type (Types) – The type of resource being loaded. resource_key (Union[int, str]) – The decimal identifier or string resource key of the resource.
Returns:	The resource key of an instance or None if no instance was found.
Return type:	CommonResourceKey

static load_all_instance_types(instance_type, return_type=Any)¶

Load all instances of the specified type.

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

static load_all_instance_values(instance_type, return_type=Any)¶

Load all instance values of the specified type.

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

static load_all_instances(instance_type, return_type=Any)¶

Load all instances of the specified type.

Parameters:	instance_type (Types) – The type of instances being loaded. return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:	An items view of all instances of the specified type. (Resource Key, Instance)
Return type:	ItemsView[str, Any]

static load_all_instances_as_guid_to_instance(instance_type, return_type=Any)¶

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

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

static load_instance(instance_type, instance_id, return_type=Any)¶

Load an instance of the specified type.

Example Usage 1:

# This will retrieve an instance for the Confident mood and will be of type statistics.mood.Mood
mood_instance = CommonResourceUtils.load_instance(Types.MOOD, CommonMoodId.CONFIDENT)

Example Usage 2:

# This will retrieve an instance for the Walk Style Angry buff and will be of type buffs.buff.Buff
buff_instance = CommonResourceUtils.load_instance(Types.BUFF, CommonBuffId.WALK_STYLE_ANGRY)

Parameters:	instance_type (Types) – The type of instance being loaded. instance_id (int) – The decimal identifier of an instance. return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Any.
Returns:	An instance of the specified type or None if no instance was found.
Return type:	Any

static load_instance_from_manager(instance_manager, instance_id, return_type=Any)¶

Load an instance from the specified InstanceManager.

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

static load_instances_with_any_tags(resource_type, tags, return_type=Any)¶

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

Note

Possible Usages:

Load all Snippet files containing properties with any of the specified tags.

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

static load_resource_bytes(resource_key, silent_fail=True)¶

Retrieve the bytes of a resource.

Parameters:	resource_key (CommonResourceKey) – The key of the resource. silent_fail (bool, optional) – Set to True to ignore errors if they occur. Set to False to throw errors when they occur. Default is True.
Returns:	An Input Output Byte reader/writer for the resource.
Return type:	BytesIO

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

Load the bytes of a resource into a Bytes Reader.

Note

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

Parameters:	resource_type (Types) – The type of resource being loaded. resource_name (str) – The tuning name of the resource. has_fnv64_identifier (bool, optional) – Set to True to indicate the resource uses a 64 bit identifier. Set to False to indicate the resource uses a 32 bit identifier. Default is True. has_high_bit_identifier (bool, optional) – Set to True to indicate the resource uses a high bit identifier. Set to False to indicate the resource uses a low bit identifier. Default is False.
Returns:	An Input Output Byte reader/writer for the resource or None if a problem occurs.
Return type:	Union[BytesIO, None]

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

Dynamically register a tuning instance.

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

Situations¶

Note

To manipulate situations of Sims, take a look at CommonSimSituationUtils

class CommonSituationUtils¶

Bases: object

Utilities for manipulating Situations.

static get_sim_info_for_all_sims_in_running_situations_by_type(situation_type)¶

Retrieve a SimInfo object for all Sims in a Situation.

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

static get_sim_info_for_all_sims_in_situation(situation)¶

Retrieve a SimInfo object for all Sims in a Situation.

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

static get_situation_guid(situation_identifier)¶

Retrieve the GUID of a Situation.

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

static get_situation_id(situation_identifier)¶

Retrieve the decimal identifier of a Situation.

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

static get_situation_job_guid(situation_job_identifier)¶

Retrieve the GUID of a Situation Job.

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

static get_situation_manager_for_zone(zone_id=None)¶

Retrieve the situation manager for a zone.

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

static get_situation_name(situation)¶

Retrieve the Name of a Situation.

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

static get_situation_names(situations)¶

Retrieve the Names of a collection of Situation.

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

static load_situation_by_id(situation_id)¶

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

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

static locate_first_running_situation_by_tag(situation_type, zone_id=None)¶

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

Parameters:	tag (CommonGameTag) – A tag to search for the situation with. zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:	A collection of situations from the specified zone that have the specified tag.
Return type:	Tuple[Situation]

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

locate_first_running_situation_by_tag(situation_type, zone_id=None)

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

Parameters:	tags (Iterator[CommonGameTag]) – A list of tags to search for the situation with. zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:	A collection of situations from the specified zone that have the specified tag.
Return type:	Tuple[Situation]

static locate_first_running_situation_by_type(situation_type, zone_id=None)¶

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

Parameters:	situation_type (Type[Situation]) – The type of situation to search for. zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:	A collection of situations from the specified zone that have the specified tag.
Return type:	Tuple[Situation]

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

locate_situation_by_id(situation_id, zone_id=None)

Locate a running Situation from a Zone by its id.

Parameters:	situation_id (Union[int, CommonSituationId, Situation]) – The decimal identifier of a Situation. (Not to be confused with the instance id) zone_id (int, optional) – The zone to retrieve the situation from. Default is None, which is the current zone.
Returns:	The situation from the specified zone that matches the specified id or None if not found.
Return type:	Union[Situation, None]

static locate_running_situations_by_tag(tag, zone_id=None)¶

Locate all running Situations in a Zone by a tag.

Parameters:	tag (CommonGameTag) – A tag to search for situations with. zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:	A collection of situations from the specified zone that have the specified tag.
Return type:	Tuple[Situation]

static locate_running_situations_by_tags(tags, zone_id=None)¶

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

Parameters:	tags (Iterator[CommonGameTag]) – A list of tags to search for situations with. zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:	A collection of situations from the specified zone that have any of the specified tags.
Return type:	Tuple[Situation]

static locate_running_situations_by_type(situation_type, zone_id=None)¶

Locate all running Situations in a Zone by Type.

Parameters:	situation_type (Type[Situation]) – The type of situation to search for. zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.
Returns:	A collection of situations from the specified zone that have the specified tag.
Return type:	Tuple[Situation]

Skills¶

Note

To manipulate skills of Sims, take a look at CommonSimSkillUtils

class CommonSkillUtils¶

Bases: object

Utilities for manipulating Skills.

static get_all_skills_gen(include_skill_callback=None)¶

Retrieve all Skills.

Parameters:	include_skill_callback (Callable[[Skill], bool], optional) – If the result of this callback is True, the Skill will be included in the results. If set to None, All Skills will be included.
Returns:	An iterator of Skills that pass the specified include_skill_callback.
Return type:	Iterator[Skill]

static get_short_name(skill)¶

Retrieve the Short Name of a Skill.

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

static get_short_names(skills)¶

Retrieve the Short Names of a collection of Skills.

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

static get_skill_id(skill_identifier)¶

Retrieve the decimal identifier of a Skill.

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

static load_skill_by_id(skill_id)¶

Load an instance of a Skill by its decimal identifier.

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

Statistics¶

Note

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

class CommonStatisticUtils¶

Bases: object

Utilities for manipulating Statistics.

static get_statistic_id(statistic_identifier)¶

Retrieve the decimal identifier of a Statistic.

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

static get_statistic_initial_value(statistic_id)¶

Retrieve the Initial Value of a Statistic.

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

static get_statistic_instance_manager()¶

Retrieve the manager that manages all Statistics.

Returns:	The manager that manages all Statistics.
Return type:	StatisticInstanceManager

static get_statistic_max_value(statistic_id)¶

Retrieve the Maximum Value of a Statistic.

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

static get_statistic_min_value(statistic_id)¶

Retrieve the Minimum Value of a Statistic.

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

static load_statistic_by_id(statistic_id)¶

Load an instance of a Statistic by its decimal identifier.

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

Loot Actions¶

Note

To manipulate or apply Loot Actions to Sims, take a look at CommonSimLootActionUtils

class CommonLootActionUtils¶

Bases: object

Utilities for manipulating Loot Actions.

static apply_loot_actions_by_id_using_resolver(loot_actions_id, resolver)¶

Apply loot actions by id using a resolver.

Parameters:	loot_actions_id (int) – The decimal identifier of a loot actions instance to apply. resolver (Resolver) – A resolver used in various ways by loot actions. The resolver could be a SingleSimResolver, which will attempt to apply the loot to a single Sim, a DoubleSimResolver, which will attempt to apply to two Sims, or various other types of resolvers.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

static apply_loot_actions_by_ids_using_resolver(loot_actions_ids, resolver)¶

Apply loot actions by their ids using a resolver.

Parameters:	loot_actions_ids (Tuple[int]) – A collection of decimal identifiers of LootActions instances to apply. resolver (Resolver) – A resolver used in various ways by loot actions. The resolver could be a SingleSimResolver, which will attempt to apply the loot to a single Sim, a DoubleSimResolver, which will attempt to apply to two Sims, or various other types of resolvers.
Returns:	True, if at least one of the loot actions applied successfully. False, if not.
Return type:	bool

static apply_loot_actions_using_resolver(loot_actions, resolver)¶

Apply loot actions using a resolver.

Parameters:	loot_actions (LootActions) – The loot actions to apply. resolver (Resolver) – A resolver used in various ways by loot actions. The resolver could be a SingleSimResolver, which will attempt to apply the loot to a single Sim, a DoubleSimResolver, which will attempt to apply to two Sims, or various other types of resolvers.
Returns:	True, if the loot actions applied successfully. False, if not.
Return type:	bool

static load_loot_actions_by_id(loot_actions_id)¶

Load a Loot Actions instance by its decimal identifier.

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