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=<function 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=<function 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=<function 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=objects.components.Component)

Retrieve a component from a ComponentContainer.

Parameters:

  • component_container (ComponentContainer) – The ComponentContainer to retrieve a component from.

  • component_type (CommonComponentType) – The type of component being retrieved.

  • add_dynamic (bool, optional) – If True, the component will be added dynamically. If False, the component will not be added dynamically. Default is False.

  • return_type (Type[CommonExpectedReturnType], optional) – The type of the returned value. (This is to make type hinting more accurate). It is not actually used in the function. Default is Component.

Returns:

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

Return type:

Union[CommonExpectedReturnType, None]

static has_component(component_container, component_type)

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

Parameters:

  • component_container (ComponentContainer) – The ComponentContainer to check.

  • component_type (CommonComponentType) – The type of component to locate.

Returns:

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

Return type:

bool

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[Union[CommonGamePack, Pack]]

static get_game_pack_name(game_pack)

Retrieve the name of a Game Pack.

Parameters:

game_pack (Union[CommonGamePack, 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 (Union[CommonGamePack, 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)

Determine if specified Game Packs are available.

Parameters:

game_packs (Tuple[Union[CommonGamePack, Pack]]) – The Game Packs to check for.

Returns:

True, if all the specified Game Packs are available. False, if any of them are not available.

Return type:

bool

Recipes

class CommonRecipeUtils

Bases: _HasS4CLClassLog

Utilities for manipulating Recipes in various ways.

static get_all_recipes_gen(include_recipe_callback=None)

Retrieve all Recipes.

Parameters:

include_recipe_callback (Callable[[Recipe], bool], optional) – If the result of this callback is True, the Recipe will be included in the results. If set to None, All Recipes will be included.

Returns:

An iterator of Recipes that pass the specified include_recipe_callback.

Return type:

Iterator[Recipe]

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

static get_recipe_guid(recipe_identifier)

Retrieve the GUID of a Recipe.

Parameters:

recipe_identifier (Union[int, Recipe]) – The identifier or instance of a Recipe.

Returns:

The decimal identifier of the Recipe or None if the Recipe does not have an id.

Return type:

Union[int, None]

static get_short_name(recipe)

Retrieve the Short Name of a Recipe.

Parameters:

recipe (Recipe) – An instance of a Recipe.

Returns:

The short name of a Recipe or None if a problem occurs.

Return type:

Union[str, None]

static get_short_names(recipes)

Retrieve the Short Names of a collection of Recipes.

Parameters:

recipes (Iterator[Recipe]) – A collection of Recipe instances.

Returns:

A collection of short names of all Recipe instances.

Return type:

Tuple[str]

static load_recipe_by_guid(value_id)

Load an instance of a Recipe by a GUID.

Parameters:

value_id (Union[int, Recipe]) – The GUID of a Recipe.

Returns:

An instance of a Recipe matching the decimal identifier or None if not found.

Return type:

Union[Recipe, None]

Resources

class CommonResourceUtils

Bases: object

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

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

Convert a text string into an FNV32 decimal identifier.

Parameters:

  • text (str) – The text to convert.

  • seed (int) – A seed to use when converting. Default value is 2166136261.

  • high_bit (bool) – If True, the high FNV bit will be returned. If False, a low FNV bit will be returned.

Returns:

The text converted to a FNV32 decimal identifier.

Return type:

int

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

Convert a text string into an FNV64 decimal identifier.

Parameters:

  • text (str) – The text to convert.

  • seed (int) – A seed to use when converting. Default value is 14695981039346656037.

  • high_bit (bool) – If True, a high bit version of the FNV bit will be returned. If False, a low bit version of the FNV bit will be returned.

Returns:

The text converted to an FNV64 decimal identifier.

Return type:

int

static get_enum_by_int_value(value, enum_type, default_value=None)

Retrieve an enum value by its value.

Parameters:

  • value (int) – The integer value of the enum value to retrieve.

  • enum_type (Any) – The type of enum to retrieve.

  • default_value (Any, optional) – The default value to return if an enum value was not found using the specified name. Default is None.

Returns:

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

Return type:

Any

static get_enum_by_name(name, enum_type, default_value=None)

Retrieve an enum value by its name.

Parameters:

  • name (str) – The name of the enum value to retrieve.

  • enum_type (Any) – The type of enum to retrieve.

  • default_value (Any, optional) – The default value to return if an enum value was not found using the specified name. Default is None.

Returns:

The enum value with a name matching the specified name.

Return type:

Any

static get_instance_manager(instance_manager_type)

Get an InstanceManager for the specified type.

Parameters:

instance_manager_type (Types) – The type of InstanceManager to get.

Returns:

An InstanceManager for the specified type, or None if no InstanceManager is found.

Return type:

Union[InstanceManager, None]

static get_resource_key(resource_type, resource_key)

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

Note

Possible Usages:

  • Retrieve the identifier of an Icon to display next to an Interaction in the Pie Menu.

  • Retrieve the identifier of an Image for display in Dialogs or Notifications.

Example Usage:

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

  • resource_type (Types) – The type of resource being loaded.

  • resource_key (Union[int, str]) – The decimal identifier or string resource key of the resource.

Returns:

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

Return type:

CommonResourceKey

static load_all_instance_types(instance_type, return_type=typing.Any)

Load all instances of the specified type.

Parameters:

  • instance_type (Types) – The type of instances being loaded.

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

Returns:

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

Return type:

Dict[str, Any]

static load_all_instance_values(instance_type, return_type=typing.Any)

Load all instance values of the specified type.

Parameters:

  • instance_type (Types) – The type of instances being loaded.

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

Returns:

All instance values of the specified type.

Return type:

ValuesView[Any]

static load_all_instances(instance_type, return_type=typing.Any)

Load all instances of the specified type.

Parameters:

  • instance_type (Types) – The type of instances being loaded.

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

Returns:

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

Return type:

ItemsView[str, Any]

static load_all_instances_as_guid_to_instance(instance_type, return_type=typing.Any)

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

Parameters:

  • instance_type (Types) – The type of instances being loaded.

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

Returns:

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

Return type:

Dict[int, Any]

static load_instance(instance_type, instance_id, return_type=typing.Any)

Load an instance of the specified type.

Example Usage 1:

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

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

  • instance_type (Types) – The type of instance being loaded.

  • instance_id (int) – The decimal identifier of an instance.

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

Returns:

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

Return type:

Any

static load_instance_from_manager(instance_manager, instance_id, return_type=typing.Any)

Load an instance from the specified InstanceManager.

Parameters:

  • instance_manager (InstanceManager) – The InstanceManager an instance will be loaded from.

  • instance_id (int) – The decimal identifier of an instance.

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

Returns:

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

Return type:

Any

static load_instances_with_any_tags(resource_type, tags, return_type=typing.Any)

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

Note

Possible Usages:

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

Parameters:

  • resource_type (Types) – The type of resource being loaded.

  • tags (Tuple[str]) – A collection of tag names to locate within a tuning file.

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

Returns:

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

Return type:

Tuple[Any]

static load_resource_bytes(resource_key, silent_fail=True)

Retrieve the bytes of a resource.

Parameters:

  • resource_key (CommonResourceKey) – The key of the resource.

  • silent_fail (bool, optional) – Set to True to ignore errors if they occur. Set to False to throw errors when they occur. Default is True.

Returns:

An Input Output Byte reader/writer for the resource.

Return type:

BytesIO

static load_resource_bytes_by_name(resource_type, resource_name, has_fnv64_identifier=True, has_high_bit_identifier=False)

Load the bytes of a resource into a Bytes Reader.

Note

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

Parameters:

  • resource_type (Types) – The type of resource being loaded.

  • resource_name (str) – The tuning name of the resource.

  • has_fnv64_identifier (bool, optional) – Set to True to indicate the resource uses a 64 bit identifier. Set to False to indicate the resource uses a 32 bit identifier. Default is True.

  • has_high_bit_identifier (bool, optional) – Set to True to indicate the resource uses a high bit identifier. Set to False to indicate the resource uses a low bit identifier. Default is False.

Returns:

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

Return type:

Union[BytesIO, None]

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

Dynamically register a tuning instance.

Parameters:

  • mod_identity (CommonModIdentity) – The identity of the mod registering the tuning.

  • class_type (Type) – The type of class being registered.

  • tuning_type (Types) – The type of tuning being registered.

  • tuning_id (int) – The decimal identifier of the tuning being registered.

  • tuning_contents (str) – The xml contents of the tuning.

Situations

Note

To manipulate situations of Sims, take a look at CommonSimSituationUtils

class CommonSituationUtils

Bases: object

Utilities for manipulating Situations.

static get_sim_info_for_all_sims_in_running_situations_by_type(situation_type)

Retrieve a SimInfo object for all Sims in a Situation.

Parameters:

situation_type (Type[Situation]) – The type of situation to locate.

Returns:

A collection of SimInfo for all Sims in the situations that match the specified type.

Return type:

Tuple[SimInfo]

static get_sim_info_for_all_sims_in_situation(situation)

Retrieve a SimInfo object for all Sims in a Situation.

Parameters:

situation (Situation) – A situation

Returns:

A collection of SimInfo for all Sims in the situation.

Return type:

Tuple[SimInfo]

static get_situation_guid(situation_identifier)

Retrieve the GUID of a Situation.

Parameters:

situation_identifier (Union[int, Situation]) – The identifier or instance of a Situation.

Returns:

The GUID of the specified Situation or -1 if it does not have one.

Return type:

int

static get_situation_id(situation_identifier)

Retrieve the decimal identifier of a Situation.

Parameters:

situation_identifier (Union[int, Situation]) – The identifier or instance of a Situation.

Returns:

The decimal identifier of the Situation or None if the Situation does not have an id.

Return type:

Union[int, None]

static get_situation_job_guid(situation_job_identifier)

Retrieve the GUID of a Situation Job.

Parameters:

situation_job_identifier (Union[int, SituationJob]) – The identifier or instance of a Situation Job.

Returns:

The GUID of the specified Situation or -1 if it does not have one.

Return type:

int

static get_situation_manager_for_zone(zone_id=None)

Retrieve the situation manager for a zone.

Parameters:

zone_id (int, optional) – The zone to retrieve the situation manager of. Default is None, which is the current zone.

Returns:

The situation manager for the specified zone.

Return type:

SituationManager

static get_situation_name(situation)

Retrieve the Name of a Situation.

Parameters:

situation (Situation) – An instance of a Situation.

Returns:

The short name of a Situation or None if a problem occurs.

Return type:

Union[str, None]

static get_situation_names(situations)

Retrieve the Names of a collection of Situation.

Parameters:

situations (Iterator[Situation]) – A collection of Situation instances.

Returns:

A collection of names for all specified Situations.

Return type:

Tuple[str]

static load_situation_by_id(situation_guid)

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

Parameters:

situation_guid (Union[int, CommonSituationId, Situation]) – The decimal identifier of a Situation. (Not to be confused with the instance id)

Returns:

An instance of a Situation matching the decimal identifier or None if not found.

Return type:

Union[Situation, None]

static locate_first_running_situation_by_tag(tag, zone_id=None)

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

Parameters:

  • tag (CommonGameTag) – A tag to search for the situation with.

  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.

Returns:

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

Return type:

Tuple[Situation]

static locate_first_running_situation_by_tags(tags, zone_id=None)

locate_first_running_situation_by_tag(situation_type, zone_id=None)

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

Parameters:

  • tags (Iterator[CommonGameTag]) – A list of tags to search for the situation with.

  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.

Returns:

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

Return type:

Tuple[Situation]

static locate_first_running_situation_by_type(situation_type, zone_id=None)

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

Parameters:

  • situation_type (Type[Situation]) – The type of situation to search for.

  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.

Returns:

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

Return type:

Tuple[Situation]

static locate_running_situation_by_id(situation_id, zone_id=None)

locate_situation_by_id(situation_id, zone_id=None)

Locate a running Situation from a Zone by its id.

Parameters:

  • situation_id (Union[int, CommonSituationId, Situation]) – The decimal identifier of a Situation. (Not to be confused with the instance id)

  • zone_id (int, optional) – The zone to retrieve the situation from. Default is None, which is the current zone.

Returns:

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

Return type:

Union[Situation, None]

static locate_running_situations_by_tag(tag, zone_id=None)

Locate all running Situations in a Zone by a tag.

Parameters:

  • tag (CommonGameTag) – A tag to search for situations with.

  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.

Returns:

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

Return type:

Tuple[Situation]

static locate_running_situations_by_tags(tags, zone_id=None)

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

Parameters:

  • tags (Iterator[CommonGameTag]) – A list of tags to search for situations with.

  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.

Returns:

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

Return type:

Tuple[Situation]

static locate_running_situations_by_type(situation_type, zone_id=None)

Locate all running Situations in a Zone by Type.

Parameters:

  • situation_type (Type[Situation]) – The type of situation to search for.

  • zone_id (int, optional) – The zone to locate the situations in. Default is None, which is the current zone.

Returns:

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

Return type:

Tuple[Situation]

Skills

Note

To manipulate skills of Sims, take a look at CommonSimSkillUtils

Statistics

Note

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

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

classmethod combine_loot_actions(loot_action_a, loot_actions)

Combine Loot Actions into Loot Action A.

Note

Tests are not combined into Loot Action A.

Parameters:

  • loot_action_a (Union[int, CommonInt, LootActions]) – The loot action to modify.

  • loot_actions (Tuple[Union[int, CommonInt, LootActions]]) – The loot actions that will be combined into Loot Action A

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]