Custom Interactions

Note

To add Custom Interactions to various objects and places, take a look at CommonInteractionRegistry

For an example on creating a Custom Interaction, take a look at this Custom Interaction Tutorial

Interaction

class CommonInteraction(...)

Bases: sims4communitylib.classes.interactions.common_interaction.Interaction, sims4communitylib.logging.has_class_log.HasClassLog

An inheritable class that provides a way to create Custom Interactions.

Note

It is recommended to inherit from one of the following classes instead of CommonInteraction directly:

  • CommonImmediateSuperInteraction
  • CommonMixerInteraction
  • CommonSocialMixerInteraction
  • CommonSuperInteraction
  • CommonTerrainInteraction

Warning

Due to an issue with how Read The Docs functions, the base classes of this class will have different namespaces in the docs than they do in the source code!

_on_reset(interaction_sim, interaction_target)

A hook that occurs upon the interaction being reset.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
_send_current_progress(interaction_sim, interaction_target, *args, **kwargs)

A hook that occurs upon sending the current progress for the interaction.

Warning

The returned value from here replaces the original returned value.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
Returns:

True, if progress was sent successfully. False, if not. Return None to run the original code.

Return type:

bool

_setup_asm_default(interaction_sim, interaction_target, asm, *args, **kwargs)

A hook that occurs upon the animation state machine being setup for the interaction.

Warning

The returned value from here replaces the original returned value. Return None from here to return the original value.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
  • interaction_asm (NativeAsm) – An instance of an Animation State Machine
Returns:

True, if the ASM was setup properly. False, if not. or None to run through the original code.

Return type:

bool

cancel(finishing_type, cancel_reason_msg, **kwargs)

Cancel the interaction. (Soft Cancel)

Parameters:
  • finishing_type (FinishingType) – The type of cancellation occurring.
  • cancel_reason_msg (str) – The reason the interaction was cancelled.
Returns:

True, if the interaction was cancelled successfully. False, if the interaction was not cancelled successfully.

Return type:

bool

classmethod create_test_result(result, reason=None, text_tokens=(), tooltip=None, icon=None, influence_by_active_mood=False)

Create a TestResult with the specified information.

Note

TestResult is an object used to disable, hide, or display tooltips on interactions. See on_test() for more information.

Parameters:
  • result (bool) – The result of a test. True for passed, False for failed.
  • reason (str, optional) – The reason for the Test Result (This is displayed as a tooltip to the player when the interaction is disabled).
  • text_tokens (Union[Tuple[Any], List[Any], Set[Any]], optional) – Any text tokens to include format into the reason.
  • tooltip (Union[int, str, LocalizedTooltip], optional) – The tooltip displayed when hovering the interaction while it is disabled.
  • icon (_resourceman.Key, optional) – The icon of the outcome.
  • influence_by_active_mood (bool, optional) – If true, the Test Result will be influenced by the active mood.
Returns:

The desired outcome for a call of on_test(), default is TestResult.NONE

Return type:

TestResult

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.
kill()

Kill the interaction. (Hard Cancel)

Returns:True, if the interaction was killed successfully. False, if the interaction was not killed successfully.
Return type:bool
modify_posture_state(posture_state, participant_type=ParticipantType.Actor, sim=DEFAULT)

A hook that allows modification of the posture state of the interactions participants.

Parameters:
  • posture_state (PostureState) – The posture state being modified.
  • participant_type (ParticipantType, optional) – The position in the interaction that the sim is considered at. Example: ParticipantType.Actor represents the source Sim of the interaction.
  • sim (Sim, optional) – The Sim the posture state is being applied to.
Returns:

Return a modified PostureState, ParticipantType, and Sim.

Return type:

Tuple[PostureState, ParticipantType, Sim]

on_cancelled(interaction_sim, interaction_target, finishing_type, cancel_reason_msg, **kwargs)

A hook that occurs upon the interaction being cancelled.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
  • finishing_type (FinishingType) – The type of cancellation of the interaction.
  • cancel_reason_msg (str) – The reason the interaction was cancelled.
on_killed(interaction_sim, interaction_target)

A hook that occurs upon the interaction being killed.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
Returns:

True, if the interaction hook was executed successfully. False, if the interaction hook was not executed successfully.

Return type:

bool

on_performed(interaction_sim, interaction_target)

A hook that occurs after the interaction has been performed.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
on_started(interaction_sim, interaction_target)

A hook that occurs upon the interaction being started.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
Returns:

True, if the interaction hook was executed successfully. False, if the interaction hook was not executed successfully.

Return type:

bool

classmethod on_test(interaction_sim, interaction_target, interaction_context, **kwargs)

A hook that occurs upon the interaction being tested for availability.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
  • interaction_context (InteractionContext) – The context of the interaction.
Returns:

The outcome of testing the availability of the interaction

Return type:

TestResult

set_current_progress_bar(initial_value, progress_rate)

Set the current progress rate of the interaction.

Parameters:
  • percent (float) – A percentage indicating the starting progress.
  • rate_change (float) – A value that indicates how fast progress will be made.
  • start_message (bool, optional) – If True, progress will begin changing immediately. If False, it will not. Default is True.

Immediate Super Interaction

class CommonImmediateSuperInteraction(*_, **__)

Bases: sims4communitylib.classes.interactions.common_interaction.CommonInteraction, sims4communitylib.classes.interactions.common_immediate_super_interaction.ImmediateSuperInteraction

An inheritable class that provides a way to create Custom Immediate Super Interactions.

Note

The main use for this class is to create interactions that do something upon starting the interaction, without the Sim needing to queue the interaction. One example would be the Replace interaction to replace objects that were destroyed in a fire.

Warning

Due to an issue with how Read The Docs functions, the base classes of this class will have different namespaces than they do in the source code!

Mixer Interaction

class CommonMixerInteraction(*args, **kwargs)

Bases: sims4communitylib.classes.interactions.common_mixer_interaction.MixerInteraction, sims4communitylib.classes.interactions.common_interaction.CommonInteraction

An inheritable class that provides a way to create Custom Mixer Interactions.

Warning

Due to an issue with how Read The Docs functions, the base classes of this class will have different namespaces than they do in the source code!

Example:
# The following is an example interaction that varies when it will display, when it will be hidden, and when it will be disabled with a tooltip.
class _ExampleInteraction(CommonMixerInteraction):
    @classmethod
    def on_test(cls, interaction_sim: Sim, interaction_target: Any, interaction_context: InteractionContext, **kwargs) -> TestResult:
        result = 1 + 1
        if result == 2:
            # Interaction will be displayed, but disabled, it will also have a tooltip that displays on hover with the text "Test Tooltip"
            return cls.create_test_result(False, reason="Test Tooltip")
            # Alternative way to specify a tooltip with the text "Test Tooltip"
            # return cls.create_test_result(False, reason="No Reason", tooltip=CommonLocalizationUtils.create_localized_tooltip("Test Tooltip"))
        if result == 3:
            # Interaction will be hidden completely.
            return TestResult.NONE
        # Interaction will display and be enabled.
        return TestResult.TRUE

    def on_started(self, interaction_sim: Sim, interaction_target: Any) -> bool:
        result = True
        if not result:
            return False
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return True

    def on_cancelled(self, interaction_sim: Sim, interaction_target: Any, finishing_type: FinishingType, cancel_reason_msg: str, **kwargs):
        result = True
        if not result:
            return False
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return True

Social Mixer Interaction

class CommonSocialMixerInteraction(*args, **kwargs)

Bases: sims4communitylib.classes.interactions.common_social_mixer_interaction.SocialMixerInteraction, sims4communitylib.classes.interactions.common_interaction.CommonInteraction

An inheritable class that provides a way to create Custom Social Mixer Interactions.

Note

The main use for this class is to create interactions that involve two or more Sims interacting with each other.

Warning

Due to an issue with how Read The Docs functions, the base classes of this class will have different namespaces than they do in the source code!

Example:
# The following is an example interaction that varies when it will display, when it will be hidden, and when it will be disabled with a tooltip.
class _ExampleInteraction(CommonSocialMixerInteraction):
    @classmethod
    def on_test(cls, interaction_sim: Sim, interaction_target: Any, interaction_context: InteractionContext, *args, **kwargs) -> TestResult:
        result = 1 + 1
        if result == 2:
            # Interaction will be displayed, but disabled, it will also have a tooltip that displays on hover with the text "Test Tooltip"
            return cls.create_test_result(False, reason="Test Tooltip")
            # Alternative way to specify a tooltip with the text "Test Tooltip"
            # return cls.create_test_result(False, reason="No Reason", tooltip=CommonLocalizationUtils.create_localized_tooltip("Test Tooltip"))
        if result == 3:
            # Interaction will be hidden completely.
            return TestResult.NONE
        # Interaction will display and be enabled.
        return TestResult.TRUE

    def on_started(self, interaction_sim: Sim, interaction_target: Any) -> bool:
        result = True
        if not result:
            return False
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return True

    def on_cancelled(self, interaction_sim: Sim, interaction_target: Any, finishing_type: FinishingType, cancel_reason_msg: str, **kwargs):
        result = True
        if not result:
            return False
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return True
is_social()
classmethod on_test(interaction_sim, interaction_target, interaction_context, *args, **kwargs)

A hook that occurs upon the interaction being tested for availability.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
  • interaction_context (InteractionContext) – The context of the interaction.
Returns:

The outcome of testing the availability of the interaction

Return type:

TestResult

setup_asm_default(asm, *args, **kwargs)

A function that occurs when setting up the Animation State Machine.

Parameters:asm (NativeAsm) – An instance of the Animation State Machine
Returns:True, if the ASM was setup properly. False, if not.
Return type:bool
social_group

Base Super Interaction

Super Interaction

Social Super Interaction

Terrain Interaction

An inheritable class that provides a way to create custom Terrain Interactions.

The main use for this class is to create interactions that occur when clicking on the ground, however it may be used for interactions on objects as well.

class CommonTerrainInteraction(*_, **__)

Bases: sims4communitylib.classes.interactions.common_interaction.CommonInteraction, sims4communitylib.classes.interactions.common_terrain_interaction.TravelMixin, sims4communitylib.classes.interactions.common_terrain_interaction.TerrainInteractionMixin, sims4communitylib.classes.interactions.common_terrain_interaction.ImmediateSuperInteraction

An inheritable class that provides a way to create custom Terrain Interactions.

Note

The main use for this class is to create interactions that appear when clicking on the ground. However, it can also be used for interactions that appear when clicking on Sims.

Warning

Due to an issue with how Read The Docs functions, the base classes of this class will have different namespaces than they do in the source code!

Example:
class _ExampleTerrainInteraction(CommonTerrainInteraction):
    @classmethod
    def on_test(cls, interaction_sim: Sim, interaction_target: Any, interaction_context: InteractionContext, **kwargs) -> TestResult:
        result = 1 + 1
        if result == 2:
            # Interaction will be displayed, but disabled, it will also have a tooltip that displays on hover with the text "Test Tooltip"
            return cls.create_test_result(False, reason="Test Tooltip")
            # Alternative way to specify a tooltip with the text "Test Tooltip"
            # return cls.create_test_result(False, reason="No Reason", tooltip=CommonLocalizationUtils.create_localized_tooltip("Test Tooltip"))
        if result == 3:
            # Interaction will be hidden completely.
            return TestResult.NONE
        # Interaction will display and be enabled.
        return TestResult.TRUE

    def on_started(self, interaction_sim: Sim, interaction_target: Any) -> bool:
        result = True
        if not result:
            return False
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return True

Interaction Overrides

Name Override

class CommonInteractionOverrideName

Bases: sims4communitylib.logging.has_class_log.HasClassLog

An inheritable class that provides a way to override the get_name() function of CommonInteraction.

Warning

This class is to be used in conjunction with CommonInteraction. Inheriting from this class will do nothing for class that does not also inherit from CommonInteraction.

classmethod _create_display_name(interaction_sim, interaction_target, interaction=None, interaction_context=None)

A hook that allows using a custom display name for an Interaction.

Parameters:
  • interaction_sim (Sim) – The source Sim of the interaction.
  • interaction_target (Any) – The target Object of the interaction.
  • interaction (Union[Interaction, None], optional) – An instance of an interaction or None if no instance of the interaction is available. Default is None.
  • interaction_context (Union[InteractionContext, None], optional) – The context of the interaction or None if no interaction context is available. Default is None.
  • args (Any) – Extra arguments not accounted for.
  • kwargs (Any) – Extra Keyword arguments not accounted for.
Returns:

A Localized String to display for the interaction or None if the original display name should be used.

Return type:

Union[LocalizedString, None]

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.

Interaction Registration

Interaction Registry

class CommonInteractionRegistry

Bases: sims4communitylib.services.common_service.CommonService

Manage the registration of interactions to script objects, terrain, sims, etc.

Note

Take a look at CommonScriptObjectInteractionHandler for more info and an example of usage.

register_handler(handler, interaction_type)

Manually register an interaction handler.

Note

It is recommended to decorate classes with register_interaction_handler() instead of manually registering interaction handlers.

Parameters:
  • handler (CommonInteractionHandler) – The interaction handler being registered.
  • interaction_type (CommonInteractionType) – The type of place the interactions will show up.
static register_interaction_handler(interaction_type)

Decorate a class to register that class as an interaction handler.

Note

Take a look at CommonScriptObjectInteractionHandler for more info and example usage.

Parameters:interaction_type (CommonInteractionType) – The type of place the interactions will show up.
Returns:A wrapped function.
Return type:Callable[.., Any]

Script Object Interaction Handler

class CommonScriptObjectInteractionHandler

Bases: sims4communitylib.services.interactions.interaction_registration_service.CommonInteractionHandler

An inheritable class that enables registration of interactions to script objects.

Note

Script Objects can be both Sims and Furniture.

Example usage:
# In this example, the interaction `sim-chat` will be added to any script object that is a `Sim`.
@CommonInteractionRegistry.register_interaction_handler(CommonInteractionType.ON_SCRIPT_OBJECT_LOAD)
class ExampleInteractionHandler(CommonScriptObjectInteractionHandler):
    @property
    def interactions_to_add(self) -> Tuple[int]:
        # Interaction Ids
        # These are the decimal identifiers of the interactions from a package file.
        from sims4communitylib.enums.interactions_enum import CommonInteractionId
        return tuple([int(CommonInteractionId.SIM_CHAT), 2])

    def should_add(self, script_object: ScriptObject, *args, **kwargs) -> bool:
        # Verify it is the object your are expecting. Return True, if it is.
        # In this case we are adding these interactions to Sims.
        from sims.sim import Sim
        return isinstance(script_object, Sim)
interactions_to_add

A collection of interactions that will be added to the script objects that pass the should_add() check.

Returns:A collection of interaction decimal identifiers.
Return type:Tuple[int]
should_add(script_object, args, kwargs)

Determine whether to add the interactions of this handler to the script object.

Parameters:
  • script_object – An object of type ScriptObject
  • script_object – ScriptObject
Returns:

True if the interactions specified by interactions_to_add should be added to the script_object. False if not.

Return type:

bool