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: sphinx.ext.autodoc.importer._MockObject, sims4communitylib.logging.has_class_log.HasClassLog, sims4communitylib.classes.interactions._common_interaction_hooks_mixin._CommonInteractionHooksMixin, sims4communitylib.classes.interactions._common_interaction_custom_mixin._CommonInteractionCustomMixin

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
CommonInteraction
CommonSocialMixerInteraction
CommonSocialSuperInteraction
CommonSuperInteraction
CommonObjectInteraction
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!

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

Immediate Super Interaction¶

class CommonImmediateSuperInteraction(*_, **__)¶

Bases: sphinx.ext.autodoc.importer._MockObject, sims4communitylib.logging.has_class_log.HasClassLog, sims4communitylib.classes.interactions._common_interaction_hooks_mixin._CommonInteractionHooksMixin, sims4communitylib.classes.interactions._common_interaction_custom_mixin._CommonInteractionCustomMixin

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!

apply_posture_state(posture_state: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb24190>, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb20910> = <sphinx.ext.autodoc.importer._MockObject object>, sim: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb24b50> = <sphinx.ext.autodoc.importer._MockObject object>)¶

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.

get_name(inst: sims4communitylib.classes.interactions.common_immediate_super_interaction.CommonImmediateSuperInteraction, target: Any = <sphinx.ext.autodoc.importer._MockObject object>, context: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb241d0> = <sphinx.ext.autodoc.importer._MockObject object>, **interaction_parameters) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb24a90>¶

get_participants(inst, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb20910>, sim=<sphinx.ext.autodoc.importer._MockObject object>, target=<sphinx.ext.autodoc.importer._MockObject object>, carry_target=<sphinx.ext.autodoc.importer._MockObject object>, **kwargs)¶

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

on_reset()¶: A function that occurs upon an interaction being reset.

send_current_progress(*args, **kwargs)¶: A function that occurs upon a progress bar update.

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

Mixer Interaction¶

class CommonMixerInteraction(*_, **__)¶

Bases: sphinx.ext.autodoc.importer._MockObject, sims4communitylib.logging.has_class_log.HasClassLog, sims4communitylib.classes.interactions._common_interaction_hooks_mixin._CommonInteractionHooksMixin, sims4communitylib.classes.interactions._common_interaction_custom_mixin._CommonInteractionCustomMixin

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) -> CommonTestResult:
        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 CommonTestResult.NONE
        # Interaction will display and be enabled.
        return CommonTestResult.TRUE

    def on_started(self, interaction_sim: Sim, interaction_target: Any) -> CommonExecutionResult:
        result = True
        if not result:
            return CommonExecutionResult.FALSE
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return CommonExecutionResult.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

apply_posture_state(posture_state: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272ee250>, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2baf1150> = <sphinx.ext.autodoc.importer._MockObject object>, sim: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb37c90> = <sphinx.ext.autodoc.importer._MockObject object>)¶

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 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.

get_name(inst: sims4communitylib.classes.interactions.common_mixer_interaction.CommonMixerInteraction, target: Any = <sphinx.ext.autodoc.importer._MockObject object>, context: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb37cd0> = <sphinx.ext.autodoc.importer._MockObject object>, **interaction_parameters) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bb37bd0>¶

get_participants(inst, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2baf1150>, sim=<sphinx.ext.autodoc.importer._MockObject object>, target=<sphinx.ext.autodoc.importer._MockObject object>, carry_target=<sphinx.ext.autodoc.importer._MockObject object>, **kwargs)¶

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

on_reset()¶: A function that occurs upon an interaction being reset.

send_current_progress(*args, **kwargs)¶: A function that occurs upon a progress bar update.

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 Mixer Interaction¶

class CommonSocialMixerInteraction(*_, **__)¶

Bases: sphinx.ext.autodoc.importer._MockObject, sims4communitylib.logging.has_class_log.HasClassLog, sims4communitylib.classes.interactions._common_interaction_hooks_mixin._CommonInteractionHooksMixin, sims4communitylib.classes.interactions._common_interaction_custom_mixin._CommonInteractionCustomMixin

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 CommonTestResult.NONE
        # Interaction will display and be enabled.
        return CommonTestResult.TRUE

    def on_started(self, interaction_sim: Sim, interaction_target: Any) -> CommonExecutionResult:
        result = True
        if not result:
            return CommonExecutionResult.FALSE
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return CommonExecutionResult.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

apply_posture_state(posture_state: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2ba931d0>, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2ba90810> = <sphinx.ext.autodoc.importer._MockObject object>, sim: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2ba96e50> = <sphinx.ext.autodoc.importer._MockObject object>)¶

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 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.

get_name(inst: sims4communitylib.classes.interactions.common_social_mixer_interaction.CommonSocialMixerInteraction, target: Any = <sphinx.ext.autodoc.importer._MockObject object>, context: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2ba90bd0> = <sphinx.ext.autodoc.importer._MockObject object>, **interaction_parameters) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2ba93090>¶

get_participants(inst, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2ba90810>, sim=<sphinx.ext.autodoc.importer._MockObject object>, target=<sphinx.ext.autodoc.importer._MockObject object>, carry_target=<sphinx.ext.autodoc.importer._MockObject object>, **kwargs) → Union[Tuple[Any], Set[Any]]¶

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

on_reset()¶: A function that occurs upon an interaction being reset.

send_current_progress(*args, **kwargs)¶: A function that occurs upon a progress bar update.

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

Base Super Interaction¶

class CommonBaseSuperInteraction(*_, **__)¶

Bases: sphinx.ext.autodoc.importer._MockObject, sims4communitylib.logging.has_class_log.HasClassLog, sims4communitylib.classes.interactions._common_interaction_hooks_mixin._CommonInteractionHooksMixin, sims4communitylib.classes.interactions._common_interaction_custom_mixin._CommonInteractionCustomMixin

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

Note

Use this Base class when you don’t wish _run_interaction_gen to be overridden.

Note

The main use for this class is to create interactions that wrap sub interactions. One example Super interaction is the sim-chat interaction, where other interactions (Such as the Get To Know interaction), run as sub interactions of sim-chat

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(CommonBaseSuperInteraction):
    @classmethod
    def on_test(cls, interaction_sim: Sim, interaction_target: Any, interaction_context: InteractionContext, **kwargs) -> CommonTestResult:
        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 CommonTestResult.NONE
        # Interaction will display and be enabled.
        return CommonTestResult.TRUE

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.

Super Interaction¶

class CommonSuperInteraction(*_, **__)¶

Bases: sims4communitylib.classes.interactions.common_super_interaction.CommonBaseSuperInteraction

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

Note

The main use for this class is to create interactions that wrap sub interactions. One example Super interaction is the sim-chat interaction, where other interactions (Such as the Get To Know interaction), run as sub interactions of sim-chat

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(CommonSuperInteraction):
    @classmethod
    def on_test(cls, interaction_sim: Sim, interaction_target: Any, interaction_context: InteractionContext, **kwargs) -> CommonTestResult:
        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 CommonTestResult.NONE
        # Interaction will display and be enabled.
        return CommonTestResult.TRUE

    # Instead of on_started, SuperInteractions use on_run.
    def on_run(self, interaction_sim: Sim, interaction_target: Any: timeline: Timeline) -> 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

apply_posture_state(posture_state: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2baa61d0>, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2baa65d0> = <sphinx.ext.autodoc.importer._MockObject object>, sim: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2bab2590> = <sphinx.ext.autodoc.importer._MockObject object>)¶

get_name(inst: sims4communitylib.classes.interactions.common_super_interaction.CommonSuperInteraction, target: Any = <sphinx.ext.autodoc.importer._MockObject object>, context: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2baa6cd0> = <sphinx.ext.autodoc.importer._MockObject object>, **interaction_parameters) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2baa6850>¶

get_participants(inst, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd2baa65d0>, sim=<sphinx.ext.autodoc.importer._MockObject object>, target=<sphinx.ext.autodoc.importer._MockObject object>, carry_target=<sphinx.ext.autodoc.importer._MockObject object>, **kwargs)¶

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

on_reset()¶: A function that occurs upon an interaction being reset.

send_current_progress(*args, **kwargs)¶: A function that occurs upon a progress bar update.

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 Super Interaction¶

class CommonSocialSuperInteraction(*_, **__)¶

Bases: sphinx.ext.autodoc.importer._MockObject, sims4communitylib.logging.has_class_log.HasClassLog, sims4communitylib.classes.interactions._common_interaction_hooks_mixin._CommonInteractionHooksMixin, sims4communitylib.classes.interactions._common_interaction_custom_mixin._CommonInteractionCustomMixin

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

Note

The main use for this class is to create interactions that wrap sub 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(CommonSocialSuperInteraction):
    @classmethod
    def on_test(cls, interaction_sim: Sim, interaction_target: Any, interaction_context: InteractionContext, interaction=None, **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 CommonTestResult.NONE
        # Interaction will display and be enabled.
        return CommonTestResult.TRUE

    # Instead of on_started, SocialSuperInteractions use on_run.
    def on_run(self, interaction_sim: Sim, interaction_target: Any, timeline: Timeline) -> 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

apply_posture_state(posture_state: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272eed50>, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272ee210> = <sphinx.ext.autodoc.importer._MockObject object>, sim: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272b63d0> = <sphinx.ext.autodoc.importer._MockObject object>)¶

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.

get_name(inst: sims4communitylib.classes.interactions.common_social_super_interaction.CommonSocialSuperInteraction, target: Any = <sphinx.ext.autodoc.importer._MockObject object>, context: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272b6c90> = <sphinx.ext.autodoc.importer._MockObject object>, **interaction_parameters) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272b6750>¶

get_participants(inst, participant_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd272ee210>, sim=<sphinx.ext.autodoc.importer._MockObject object>, target=<sphinx.ext.autodoc.importer._MockObject object>, carry_target=<sphinx.ext.autodoc.importer._MockObject object>, **kwargs)¶

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

classmethod on_post_super_test(interaction_sim, interaction_target, interaction_context, *args, interaction=None, **kwargs)¶

A hook that occurs after the interaction being tested for availability by on_test and the super _test functions.

Note

This will only run if both on_test and _test returns CommonTestResult.TRUE or similar.

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. interaction (Interaction, optional) – The interaction being tested or None. Default is None.
Returns:	The outcome of testing the availability of the interaction
Return type:	CommonTestResult

on_reset()¶: A function that occurs upon an interaction being reset.

classmethod on_test(interaction_sim, interaction_target, interaction_context, *args, interaction=None, **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. interaction (Interaction, optional) – The interaction being tested or None. Default is None.
Returns:	The outcome of testing the availability of the interaction
Return type:	CommonTestResult

send_current_progress(*args, **kwargs)¶: A function that occurs upon a progress bar update.

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

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_terrain_interaction.TravelMixin, sims4communitylib.classes.interactions.common_terrain_interaction.TerrainInteractionMixin, sims4communitylib.classes.interactions.common_immediate_super_interaction.CommonImmediateSuperInteraction

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. It CAN be used for interactions that appear when clicking on Sims and Objects, but it is not recommended.

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) -> CommonTestResult:
        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 CommonTestResult.NONE
        # Interaction will display and be enabled.
        return CommonTestResult.TRUE

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

Object Interaction¶

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

The main use for this class is to create interactions that occur when clicking on objects.

class CommonObjectInteraction(*_, **__)¶

Bases: sims4communitylib.classes.interactions.common_immediate_super_interaction.CommonImmediateSuperInteraction

An inheritable class that provides a way to create custom Object 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:

class _ExampleObjectInteraction(CommonObjectInteraction):
    @classmethod
    def on_test(cls, interaction_sim: Sim, interaction_target: Any, interaction_context: InteractionContext, **kwargs) -> CommonTestResult:
        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 CommonTestResult.NONE
        # Interaction will display and be enabled.
        return CommonTestResult.TRUE

    def on_started(self, interaction_sim: Sim, interaction_target: Any) -> CommonExecutionResult:
        result = True
        if not result:
            return CommonExecutionResult.FALSE
        # Put here what you want the interaction to do as soon as the player clicks it while it is enabled.
        return CommonExecutionResult.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 obsolete. All interaction types come with their own get_name() function. 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, **interaction_parameters)¶

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. interaction_parameters (Any) – Extra interaction parameters.
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, sims4communitylib.logging._has_s4cl_log._HasS4CLLog

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.

log_identifier¶

A string identifier for the log used by instances of the class.

Note

This is the message identifier that will appear when logging messages.

Returns:	The identifier of the log
Return type:	str

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]

register_pre_roll_super_interactions_on_script_object_add(script_object, *args, **kwargs)¶

A hook that occurs upon a Script Object being added.

Parameters:	script_object (ScriptObject) – The script object being added.

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