The Sims 4 Community Library

https://sims4communitylibrary.readthedocs.io/en/latest/
Admin
A Python library providing utilities, events, dialogs, and services for The Sims 4 game modding.
Tokens:439,137
Snippets:3,506
Trust Score:9.6
Update:47 minutes ago
Show doc for...
Tokens:
Raw
### Show CommonInputIntegerDialog example

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example function that creates and shows a CommonInputFloatDialog (note: the example uses CommonInputFloatDialog, not CommonInputIntegerDialog) with localized title and description tokens, and a submit callback that does nothing. The dialog is shown with the active Sim by default.

```python
def _common_testing_show_input_integer_dialog():

    def _on_submit(input_value: integer, outcome: CommonChoiceOutcome):
        pass

    # LocalizedStrings within other LocalizedStrings
    title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
    description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    dialog = CommonInputFloatDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        2,
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_submit=_on_submit)
```

--------------------------------

### CommonService Singleton Usage Example

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.services.html

Shows how to create a service class by inheriting from CommonService and retrieve its singleton instance using get(). Calling get() again returns the same instance.

```python
class ExampleService(CommonService):
    @property
    def first_value(self) -> str:
        return 'yes'

# ExampleService.get() returns an instance of ExampleService.
# Calling ExampleService.get() again, will return the same instance.
ExampleService.get().first_value
```

--------------------------------

### start(time_span=None, on_end=None)

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.effects.html

Starts the visual effect.

```APIDOC
## start(time_span=None, on_end=None)

### Description
Start the effect.

### Parameters
- **time_span** (TimeSpan, optional) - A span of time indicating how long to run the effect for. Default is however long the vfx itself runs.
- **on_end** (Callable[['CommonVisualEffect'], None], optional) - A callback invoked when the effect ends. This is only used when sim_minutes_until_end is specified. Default is None.

### Returns
- **bool** - True, if the effect was started successfully. False, if not.
```

--------------------------------

### S4CLBuildBuyExitEvent Example Listener

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.events.build_buy.events.html

Example of listening to the S4CLBuildBuyExitEvent. The listener function must be static, have an argument named 'event_data' with the correct type hint, and be registered with the mod name.

```python
from sims4communitylib.events.event_handling.common_event_registry import CommonEventRegistry
from sims4communitylib.modinfo import ModInfo

class ExampleEventListener:

    # In order to listen to an event, your function must match these criteria:
    # - The function is static (staticmethod).
    # - The first and only required argument has the name "event_data".
    # - The first and only required argument has the Type Hint for the event you are listening for.
    # - The argument passed to "handle_events" is the name of your Mod.
    @staticmethod
    @CommonEventRegistry.handle_events(ModInfo.get_identity().name)
    def handle_event(event_data: S4CLBuildBuyExitEvent):
        pass
```

--------------------------------

### S4CLBuildBuyEnterEvent Example Listener

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.events.build_buy.events.html

Example of listening to the S4CLBuildBuyEnterEvent. The listener function must be static, have an argument named 'event_data' with the correct type hint, and be registered with the mod name.

```python
from sims4communitylib.events.event_handling.common_event_registry import CommonEventRegistry
from sims4communitylib.modinfo import ModInfo

class ExampleEventListener:

    # In order to listen to an event, your function must match these criteria:
    # - The function is static (staticmethod).
    # - The first and only required argument has the name "event_data".
    # - The first and only required argument has the Type Hint for the event you are listening for.
    # - The argument passed to "handle_events" is the name of your Mod.
    @staticmethod
    @CommonEventRegistry.handle_events(ModInfo.get_identity().name)
    def handle_event(event_data: S4CLBuildBuyEnterEvent):
        pass
```

--------------------------------

### Example usage of CommonChooseButtonOptionDialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.option_dialogs.options.response.html

This example demonstrates how to create and show a CommonChooseButtonOptionDialog. It defines callback functions for option selection, previous button, and close events. It creates localized strings for title and description tokens, adds three options using CommonDialogButtonOption, and shows the dialog for the active Sim. The example is triggered by the in-game console command 's4clib_testing.show_choose_button_option_dialog'.

```python
def _on_option_chosen(option_identifier: DialogOptionIdentifierType, choice: DialogOptionValueType):
    pass

def _on_previous_chosen() -> None:
    pass

def _on_close() -> None:
    pass

# LocalizedStrings within other LocalizedStrings
title_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
        text_color=CommonLocalizedStringColor.GREEN
    ),
)
description_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME,
        tokens=(CommonSimUtils.get_active_sim_info(),),
        text_color=CommonLocalizedStringColor.BLUE
    ),
)
option_dialog = CommonChooseButtonOptionDialog(
    ModInfo.get_identity(),
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    on_previous=_on_previous_chosen,
    on_close=_on_close
)

# We add the options, in this case we have three options.
option_dialog.add_option(
    CommonDialogButtonOption(
        'Option 1',
        'Value 1',
        CommonDialogResponseOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            subtext_identifier=CommonStringId.TESTING_TEST_BUTTON_ONE
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.add_option(
    CommonDialogButtonOption(
        'Option 2',
        'Value 2',
        CommonDialogResponseOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            subtext_identifier=CommonStringId.TESTING_TEST_BUTTON_TWO,
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.add_option(
    CommonDialogButtonOption(
        'Option 3',
        'Value 3',
        CommonDialogResponseOptionContext(
            CommonLocalizationUtils.create_localized_string('Value 3'),
            subtext_identifier=CommonStringId.TESTING_TEST_BUTTON_TWO
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info()
)
```

--------------------------------

### Example: Show CommonInputTextDialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example function that creates and shows a CommonInputTextDialog with localized title and description tokens. The on_submit callback is defined but does nothing. The dialog is shown with the active Sim by default.

```python
def _common_testing_show_input_text_dialog():

    def _on_submit(input_value: str, outcome: CommonChoiceOutcome):
        pass

    # LocalizedStrings within other LocalizedStrings
    title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
    description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    dialog = CommonInputTextDialog(
        ModInfo.get_identity(),
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        'default_text',
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_submit=_on_submit)
```

--------------------------------

### CommonModInfo implementation example

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.mod_support.html

Example usage of CommonModInfo to provide mod information. This is how the sims4communitylib.modinfo.ModInfo implementation works. The class defines properties for name, author, base namespace, file path, and version.

```python
from sims4communitylib.mod_support.common_mod_info import CommonModInfo

# This is how the sims4communitylib.modinfo.ModInfo implementation works.
class ModInfo(CommonModInfo):
    _FILE_PATH: str = str(__file__)

    @property
    def _name(self) -> str:
        return 'Sims4CommunityLib'

    @property
    def _author(self) -> str:
        return 'ColonolNutty'

    @property
    def _base_namespace(self) -> str:
        return 'sims4communitylib'

    @property
    def _file_path(self) -> str:
        return ModInfo._FILE_PATH

    @property
    def _version(self) -> str:
        return '3.5.6'
```

--------------------------------

### CommonBaseSuperInteraction Example

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.interactions.html

Example of creating a custom Super Interaction using CommonBaseSuperInteraction, demonstrating how to control display, hiding, and disabling with tooltips.

```APIDOC
## CommonBaseSuperInteraction Example

### Description
Example interaction that varies when it will display, when it will be hidden, and when it will be disabled with a tooltip.

### Usage
Inherit from CommonBaseSuperInteraction and override the on_test class method.

### Example
```python
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
```
```

--------------------------------

### Example usage of CommonBasicNotification

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.notifications.html

This example shows how to create and display a basic notification using CommonBasicNotification. It uses localized strings with tokens and sets the urgency to URGENT. The dialog is shown with the show() method.

```python
# Will display a test dialog.
def _common_testing_show_basic_notification():
    # LocalizedStrings within other LocalizedStrings
    title_tokens = (
        CommonLocalizationUtils.create_localized_string(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            text_color=CommonLocalizedStringColor.BLUE
        ),
    )
    description_tokens = (
        CommonLocalizationUtils.create_localized_string(
            CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME,
            tokens=(CommonSimUtils.get_active_sim_info(),),
            text_color=CommonLocalizedStringColor.BLUE
        ),
    )
    dialog = CommonBasicNotification(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        urgency=UiDialogNotification.UiDialogNotificationUrgency.URGENT
    )
    dialog.show()
```

--------------------------------

### Show Choose Response Dialog Example

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example function that builds and shows a CommonChooseResponseDialog with three responses, title and description tokens, and per_page=2. The on_chosen callback is a no-op placeholder. The dialog is shown with include_previous_button=False.

```python
def _common_testing_show_choose_response_dialog():

    def _on_chosen(choice: str, outcome: CommonChoiceOutcome):
        pass

    responses: Tuple[CommonUiDialogResponse] = (
        CommonUiDialogResponse(
            1,
            'Value 1',
            text=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE)
        ),
        CommonUiDialogResponse(
            2,
            'Value 2',
            text=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO)
        ),
        CommonUiDialogResponse(
            3,
            'Value 3',
            text=CommonLocalizationUtils.create_localized_string('Test Button 3')
        )
    )
    title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
    description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)

    active_sim_info = CommonSimUtils.get_active_sim_info()
    dialog = CommonChooseResponseDialog(
        ModInfo.get_identity(),
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        responses,
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        per_page=2
    )
    dialog.show(
        on_chosen=_on_chosen,
        sim_info=active_sim_info,
        include_previous_button=False
    )
```

--------------------------------

### CommonRunnableContext.setup

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.runnables.html

Sets up the context.

```APIDOC
## setup(**kwargs, **kwargs2)

### Description
Sets up the context.

### Method
setup

### Parameters
- **kwargs (Any) - Optional - Additional keyword arguments.
- **kwargs2 (Any) - Optional - Additional keyword arguments.

### Returns
- **CommonExecutionResult** - True, if successful. False, if not.

```

--------------------------------

### SimData XML for S4CL_Example_Buff_ApplyBareFeet

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.buffs.html

Example SimData XML defining the Buff instance and its schema. Includes resource keys, localization keys, and column definitions for the Buff schema.

```xml
<?xml version="1.0" encoding="utf-8"?>
<SimData version="0x00000101" u="0x0000001F">
  <Instances>
    <I name="S4CL_Example_Buff_ApplyBareFeet" schema="Buff" type="Object">
      <T name="audio_sting_on_add">FD04E3BE-001407EC-8AF8B916CF64C646</T>
      <T name="audio_sting_on_remove">FD04E3BE-001407EC-3BF33216A25546EA</T>
      <T name="buff_description">0x00000000</T>
      <T name="buff_name">0x00000000</T>
      <T name="icon">00B2D882-00000000-30F0846C783606F9</T>
      <T name="mood_type">0</T>
      <T name="mood_weight">0</T>
      <T name="timeout_string">0x00000000</T>
      <T name="timeout_string_no_next_buff">0x00000000</T>
      <T name="ui_sort_order">1</T>
    </I>
  </Instances>
  <Schemas>
    <Schema name="Buff" schema_hash="0x0D045687">
      <Columns>
        <Column name="audio_sting_on_add" type="ResourceKey" flags="0x00000000" />
        <Column name="audio_sting_on_remove" type="ResourceKey" flags="0x00000000" />
        <Column name="buff_description" type="LocalizationKey" flags="0x00000000" />
        <Column name="buff_name" type="LocalizationKey" flags="0x00000000" />
        <Column name="icon" type="ResourceKey" flags="0x00000000" />
        <Column name="mood_type" type="TableSetReference" flags="0x00000000" />
        <Column name="mood_weight" type="Int32" flags="0x00000000" />
        <Column name="timeout_string" type="LocalizationKey" flags="0x00000000" />
        <Column name="timeout_string_no_next_buff" type="LocalizationKey" flags="0x00000000" />
        <Column name="ui_sort_order" type="Int32" flags="0x00000000" />
      </Columns>
    </Schema>
  </Schemas>
</SimData>
```

--------------------------------

### Show OK Dialog Example (s4clib_testing.show_ok_dialog)

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example of creating and showing a CommonOkDialog with localized title and description tokens, and a custom OK button text. The callback _on_acknowledged handles the dialog result. Run the command s4clib_testing.show_ok_dialog in the in-game console to see this dialog.

```python
def _common_testing_show_ok_dialog():

    def _on_acknowledged(_dialog: UiDialogOk):
        if _dialog.accepted:
            pass
        else:
            pass

    # LocalizedStrings within other LocalizedStrings
    title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
    description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
    dialog = CommonOkDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        ok_text_identifier=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE, text_color=CommonLocalizedStringColor.RED)
    )
    dialog.show(on_acknowledged=_on_acknowledged)
```

--------------------------------

### CommonTerrainInteraction Example

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.interactions.html

An example of creating a custom terrain interaction by subclassing CommonTerrainInteraction and overriding on_test and on_started.

```APIDOC
## Example: Creating a Custom Terrain Interaction

### Description
This example demonstrates how to create a custom terrain interaction by subclassing CommonTerrainInteraction and overriding the on_test and on_started methods.

### Code
```python
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
```
```

--------------------------------

### Example usage of CommonChooseSimsOptionDialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.option_dialogs.options.sims.html

Shows how to create and display a dialog for selecting multiple Sims. The example defines an on_submit callback, creates localized title and description tokens, adds options for up to 25 Sims with random enabled/selected states, and shows the dialog with 4 columns and a maximum of 5 selectable Sims.

```python
def _on_submit(sim_info_list: Tuple[SimInfo]):
    pass

# LocalizedStrings within other LocalizedStrings
title_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
        text_color=CommonLocalizedStringColor.GREEN
    ),
)
description_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME,
        tokens=(CommonSimUtils.get_active_sim_info(),),
        text_color=CommonLocalizedStringColor.BLUE
    ),
)

# Create the dialog and show a number of Sims in 4 columns and being able to select up to 5 Sims.
option_dialog = CommonChooseSimsOptionDialog(
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    mod_identity=ModInfo.get_identity()
)

current_count = 0
count = 25

for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
    if current_count >= count:
        break
    should_select = random.choice((True, False))
    is_enabled = random.choice((True, False))
    option_dialog.add_option(
        CommonDialogSimOption(
            sim_info,
            CommonDialogSimOptionContext(
                is_enabled=is_enabled,
                is_selected=should_select
            )
        )
    )

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info(),
    column_count=4,
    max_selectable=5,
    on_submit=_on_submit
)
```

--------------------------------

### CommonRunnableContext.initialize

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.runnables.html

Initializes the context.

```APIDOC
## initialize(**kwargs, **kwargs2)

### Description
Initializes the context.

### Method
initialize

### Parameters
- **kwargs (Any) - Optional - Additional keyword arguments.
- **kwargs2 (Any) - Optional - Additional keyword arguments.

### Returns
- **CommonExecutionResult** - True, if successful. False, if not.

```

--------------------------------

### CommonSaveUtils.get_save_slot_guid()

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.utils.io.html

Static method that retrieves the GUID identifier for the current save slot. Returns an integer GUID.

```APIDOC
## get_save_slot_guid()

### Description
Retrieves the guid identifier for the current save slot.

### Method
Static method

### Returns
- **int** - The GUID identifier for the current save slot.

```

--------------------------------

### Example: Show Input Float Dialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example function that creates and shows a CommonInputFloatDialog. The dialog prompts the player to enter a float value, with an initial value of 2.0. The on_submit callback is a no-op in this example. The title and description use localized strings with text colors.

```python
def _common_testing_show_input_float_dialog():

    def _on_submit(input_value: float, outcome: CommonChoiceOutcome):
        pass

    # LocalizedStrings within other LocalizedStrings
    title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
    description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    dialog = CommonInputFloatDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        2.0,
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_submit=_on_submit)
```

--------------------------------

### Example usage of CommonChooseObjectOptionDialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.option_dialogs.options.objects.html

Shows how to create a CommonChooseObjectOptionDialog with localized title and description tokens, add three options with icons and callbacks, and display it to the active Sim. The example sets per_page=2 to enable pagination. The on_chosen callback is a placeholder that should be replaced with actual logic.

```python
def _on_option_chosen(option_identifier: DialogOptionIdentifierType, choice: DialogOptionValueType):
    pass

# LocalizedStrings within other LocalizedStrings
title_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
        text_color=CommonLocalizedStringColor.GREEN
    ),
)
description_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME,
        tokens=(CommonSimUtils.get_active_sim_info(),),
        text_color=CommonLocalizedStringColor.BLUE
    ),
)

# Create the dialog and only showing 2 options per page.
option_dialog = CommonChooseObjectOptionDialog(
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    per_page=2
)

from sims4communitylib.utils.common_icon_utils import CommonIconUtils

# We add the options, in this case we have three options.
option_dialog.add_option(
    CommonDialogObjectOption(
        'Option 1',
        'Value 1',
        CommonDialogOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            CommonStringId.TESTING_TEST_BUTTON_ONE,
            icon=CommonIconUtils.load_checked_square_icon()
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.add_option(
    CommonDialogObjectOption(
        'Option 2',
        'Value 2',
        CommonDialogOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            CommonStringId.TESTING_TEST_BUTTON_TWO,
            icon=CommonIconUtils.load_arrow_navigate_into_icon()
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.add_option(
    CommonDialogObjectOption(
        'Option 3',
        'Value 3',
        CommonDialogOptionContext(
            CommonLocalizationUtils.create_localized_string('Value 3'),
            CommonStringId.TESTING_TEST_BUTTON_TWO,
            icon=CommonIconUtils.load_arrow_navigate_into_icon()
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info()
)
```

--------------------------------

### Example: Show Purchase Objects Dialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example from the documentation showing how to create and display a CommonPurchaseObjectsDialog. It sets up title and description tokens with colored localized strings, creates a PurchasePickerRow for a specific object, builds categories from the object's build buy tags, and shows the dialog with a callback that prints the chosen outcome.

```python
def _common_testing_show_purchase_objects_dialog():
    def _on_chosen(choices: Any, outcome: CommonChoiceOutcome):
        output('Chose {} with result: {}.'.format(pformat(choices), pformat(outcome)))

# LocalizedStrings within other LocalizedStrings
title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
show_discount = True
from sims4communitylib.utils.common_icon_utils import CommonIconUtils
active_sim_info = CommonSimUtils.get_active_sim_info()
obj_id = 20359
obj_definition = CommonObjectUtils.get_object_definition(obj_id)
tags = obj_definition.build_buy_tags
options = [
    PurchasePickerRow(
        def_id=obj_definition.id,
        num_owned=CommonSimInventoryUtils.get_count_of_object_in_inventory(active_sim_info, obj_id),
        tags=obj_definition.build_buy_tags,
        num_available=2000,
        custom_price=50,
        objects=tuple(),
        show_discount=show_discount,
        icon_info_data_override=None,  # Should be an instance of IconInfoData
        is_enable=True,
        row_tooltip=None,
        row_description=None
    ),
]
categories = list()
for tag in tags:
    tag_name = CommonGameTag.value_to_name.get(tag, None)
    if tag_name is None:
        continue
    categories.append(CommonDialogObjectOptionCategory(tag, obj_definition.icon, category_name=tag_name))
dialog = CommonPurchaseObjectsDialog(
    ModInfo.get_identity(),
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    tuple(options),
    title_tokens=title_tokens,
    description_tokens=description_tokens
)
dialog.show(on_chosen=_on_chosen, categories=categories)
```

--------------------------------

### Example usage of S4CLZoneSaveEvent listener

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.events.zone_spin.events.html

Example listener for S4CLZoneSaveEvent. The function must be static, have an argument named 'event_data' with the correct type hint, and be decorated with @CommonEventRegistry.handle_events(ModInfo.get_identity().name).

```python
from sims4communitylib.events.event_handling.common_event_registry import CommonEventRegistry
from sims4communitylib.modinfo import ModInfo

class ExampleEventListener:

    # In order to listen to an event, your function must match these criteria:
    # - The function is static (staticmethod).
    # - The first and only required argument has the name "event_data".
    # - The first and only required argument has the Type Hint for the event you are listening for.
    # - The argument passed to "handle_events" is the name of your Mod.
    @staticmethod
    @CommonEventRegistry.handle_events(ModInfo.get_identity().name)
    def handle_event(event_data: S4CLZoneSaveEvent):
        pass
```

--------------------------------

### CommonRunnable.start

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.runnables.html

Starts the runnable. Returns a CommonExecutionResult indicating success or failure.

```APIDOC
## CommonRunnable.start

### Description
Starts the runnable.

### Method
start

### Signature
`start(**, **__)`

### Parameters
No parameters.

### Returns
- **CommonExecutionResult** - True if the runnable has been successfully started, False if not.
```

--------------------------------

### CommonSimToSimTestBasedScore

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.test_based_scores.html

Test based score for testing a resolver involving two Sims. Provides methods to calculate a score, get the log identifier, mod identity, and get the score.

```APIDOC
## CommonSimToSimTestBasedScore

### Description
A test based score used when testing a resolver involving two Sims.

### Methods

#### calculate_score(resolver, source_sim_info, target_sim_info, interaction)
- **Parameters**:
  - resolver (Resolver) – A resolver containing information about what is being tested.
  - source_sim_info (SimInfo) – The Source or Actor Sim of the test, also known as Sim A.
  - target_sim_info (SimInfo) – The Target or Listener Sim of the test, also known as Sim B.
  - interaction (Interaction) – The interaction or affordance, if available, that Sim A is attempting to perform with Sim B. If no interaction or affordance is present, this value will be None.
- **Return type**: int
- **Description**: Calculates a score involving two Sims.

#### get_log_identifier()
- **Return type**: str
- **Description**: Returns a string identifier for the log of the class.

#### get_mod_identity()
- **Return type**: CommonModIdentity
- **Raises**: NotImplementedError – Thrown when the function is not implemented.
- **Description**: Retrieves the identity of the mod that owns the class. Must be overridden.

#### get_score(resolver)
- **Parameters**:
  - resolver (Resolver) – A resolver containing information about what is being tested.
- **Description**: Calculates the score.
```

--------------------------------

### Example: Show Choose Sim Dialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example function that creates and shows a CommonChooseSimDialog. It builds a list of SimPickerRow options from all Sims, with random selection and enabled states, and shows the dialog with a callback that does nothing. The dialog uses localized strings for title and description tokens.

```python
def _common_testing_show_choose_sim_dialog():

    def _on_chosen(choice: Union[SimInfo, None], outcome: CommonChoiceOutcome):
        pass

    # LocalizedStrings within other LocalizedStrings
    title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
    description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    current_count = 0
    count = 25
    options = []
    for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
        if current_count >= count:
            break
        sim_id = CommonSimUtils.get_sim_id(sim_info)
        should_select = random.choice((True, False))
        is_enabled = random.choice((True, False))
        options.append(
            SimPickerRow(
                sim_id,
                select_default=should_select,
                tag=sim_info,
                is_enable=is_enabled
            )
        )
        current_count += 1

    dialog = CommonChooseSimDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        tuple(options),
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_chosen=_on_chosen, column_count=5)
```

--------------------------------

### CommonSingleSimTestBasedScore

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.test_based_scores.html

Test based score for testing a resolver involving one Sim. Provides methods to calculate a score, get the log identifier, mod identity, and get the score.

```APIDOC
## CommonSingleSimTestBasedScore

### Description
A test based score used when testing a resolver involving one Sim.

### Methods

#### calculate_score(resolver, source_sim_info, interaction)
- **Parameters**:
  - resolver (Resolver) – A resolver containing information about what is being tested.
  - source_sim_info (SimInfo) – The Source or Actor Sim of the test.
  - interaction (Interaction) – The interaction or affordance, if available, that the Source Sim is attempting to perform. If no interaction or affordance is present, this value will be None.
- **Return type**: int
- **Description**: Calculates a score involving one Sim.

#### get_log_identifier()
- **Return type**: str
- **Description**: Returns a string identifier for the log of the class.

#### get_mod_identity()
- **Return type**: CommonModIdentity
- **Raises**: NotImplementedError – Thrown when the function is not implemented.
- **Description**: Retrieves the identity of the mod that owns the class. Must be overridden.

#### get_score(resolver)
- **Parameters**:
  - resolver (Resolver) – A resolver containing information about what is being tested.
- **Description**: Calculates the score.
```

--------------------------------

### CommonVector3.y

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.classes.math.html

Gets the y position.

```APIDOC
## CommonVector3.y

### Description
The y position.

### Property
y

### Returns
- **float** - The y position.

```

--------------------------------

### Example Event Listener for S4CLSimChangingOccultTypeEvent

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.events.sim.events.html

Example usage of the S4CLSimChangingOccultTypeEvent event. The listener function must be static, have an argument named 'event_data' with the correct type hint, and be decorated with @CommonEventRegistry.handle_events(ModInfo.get_identity().name).

```python
from sims4communitylib.events.event_handling.common_event_registry import CommonEventRegistry
from sims4communitylib.modinfo import ModInfo

class ExampleEventListener:

    # In order to listen to an event, your function must match these criteria:
    # - The function is static (staticmethod).
    # - The first and only required argument has the name "event_data".
    # - The first and only required argument has the Type Hint for the event you are listening for.
    # - The argument passed to "handle_events" is the name of your Mod.
    @staticmethod
    @CommonEventRegistry.handle_events(ModInfo.get_identity().name)
    def handle_event(event_data: S4CLSimChangingOccultTypeEvent):
        pass
```

--------------------------------

### show(on_submit=CommonFunctionUtils.noop, sim_info=None, should_show_names=True, hide_row_descriptions=False, column_count=3, min_selectable=1, max_selectable=1)

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.option_dialogs.options.sims.html

Shows the dialog and invokes the callbacks upon the player submitting their selection.

```APIDOC
## show(on_submit=CommonFunctionUtils.noop, sim_info=None, should_show_names=True, hide_row_descriptions=False, column_count=3, min_selectable=1, max_selectable=1)

### Description
Shows the dialog and invokes the callbacks upon the player submitting their selection.

### Parameters
- **on_submit** (Callable[[Tuple[SimInfo]], Any], optional) - Optional - A callback invoked upon the player choosing Sims. Default is CommonFunctionUtils.noop.
- **sim_info** (SimInfo, optional) - Optional - The SimInfo of the Sim that will appear in the dialog image. If None, it will be the active Sim. Default is None.
- **should_show_names** (bool, optional) - Optional - If True, then the names of the Sims will display in the dialog. Default is True.
- **hide_row_descriptions** (bool, optional) - Optional - A flag to hide the row descriptions. Default is False.
- **column_count** (int, optional) - Optional - The number of columns to display Sims in. Default is 3.
- **min_selectable** (int, optional) - Optional - The minimum number of Sims that must be chosen. Default is 1.
- **max_selectable** (int, optional) - Optional - The maximum number of Sims that can be chosen. Default is 1.

### Example Usage
```python
current_count = 0
count = 25

for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
    if current_count >= count:
        break
    should_select = random.choice((True, False))
    is_enabled = random.choice((True, False))
    option_dialog.add_option(
        CommonDialogSimOption(
            sim_info,
            CommonDialogSimOptionContext(
                is_enabled=is_enabled,
                is_selected=should_select
            )
        )
    )

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info(),
    column_count=4,
    max_selectable=5,
    on_submit=_on_submit
)
```
```

--------------------------------

### Example: Show Choose Sims Dialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example function that creates and shows a CommonChooseSimsDialog. It builds a list of SimPickerRow options for up to 25 Sims, randomly enabling or disabling each row, and sets title/description tokens with colored localized strings. The dialog is shown with a callback that does nothing, 5 columns, and requires between 2 and 6 selections.

```python
def _common_testing_show_choose_sims_dialog():

     def _on_chosen(choice: Union[Tuple[SimInfo], None], outcome: CommonChoiceOutcome):
         pass

     # LocalizedStrings within other LocalizedStrings
     title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
     description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
     from sims4communitylib.utils.common_icon_utils import CommonIconUtils
     current_count = 0
     count = 25
     options = []
     for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
         if current_count >= count:
             break
         sim_id = CommonSimUtils.get_sim_id(sim_info)
         is_enabled = random.choice((True, False))
         options.append(
             SimPickerRow(
                 sim_id,
                 select_default=False,
                 tag=sim_info,
                 is_enable=is_enabled
             )
         )
         current_count += 1

     dialog = CommonChooseSimsDialog(
         CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
         CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
         tuple(options),
         title_tokens=title_tokens,
         description_tokens=description_tokens
     )
     dialog.show(
         on_chosen=_on_chosen,
         column_count=5,
         min_selectable=2,
         max_selectable=6
     )
```

--------------------------------

### CommonPurchaseObjectsDialog.__init__

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Creates a new CommonPurchaseObjectsDialog instance with the specified title, description, and purchasable objects.

```APIDOC
## CommonPurchaseObjectsDialog.__init__

### Description
Creates a dialog that allows the player to purchase some objects.

### Method
Constructor

### Signature
`CommonPurchaseObjectsDialog(mod_identity, title_identifier, description_identifier, purchasable_object_rows, title_tokens=(), description_tokens=(), required_tooltip=None, required_tooltip_tokens=())`

### Parameters
- **mod_identity** (CommonModIdentity) - Required - The identity of the mod creating the dialog.
- **title_identifier** (Union[int, str, LocalizedString, CommonStringId]) - Required - The title to display in the dialog.
- **description_identifier** (Union[int, str, LocalizedString, CommonStringId]) - Required - The description to display in the dialog.
- **purchasable_object_rows** (Iterator[PurchasePickerRow]) - Required - The objects that may be purchased.
- **title_tokens** (Iterator[Any], optional) - Tokens to format into the title.
- **description_tokens** (Iterator[Any], optional) - Tokens to format into the description.
- **required_tooltip** (Union[int, str, LocalizedString, CommonStringId], optional) - If provided, this text will display when the dialog requires at least one choice and a choice has not been made. Default is None.
- **required_tooltip_tokens** (Iterator[Any], optional) - Tokens to format into the required tooltip. Default is an empty collection.

### Example
```python
dialog = CommonPurchaseObjectsDialog(
    ModInfo.get_identity(),
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    tuple(options),
    title_tokens=title_tokens,
    description_tokens=description_tokens
)
```
```

--------------------------------

### Inherit from CommonPersistedGameObjectDataStorage

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.persistence.html

Example of creating a subclass of CommonPersistedGameObjectDataStorage. Must override get_mod_identity with your mod's CommonModIdentity. The example shows a property getter and setter using get_data and set_data, with optional key parameters.

```python
# Inherit from CommonPersistedGameObjectDataStorage
class ExamplePersistedGameObjectDataStorage(CommonPersistedGameObjectDataStorage):
    @classmethod
    def get_mod_identity(cls) -> CommonModIdentity:
        # !!!Override with the CommonModIdentity of your own mod!!!
        from sims4communitylib.modinfo import ModInfo
        return ModInfo.get_identity()

    @property
    def example_property_one(self) -> bool:
        # Could also be written self.get_data(default=False, key='example_property_one') and it would do the same thing.
        return self.get_data(default=False)

    @example_property_one.setter
    def example_property_one(self, value: bool):
        # Could also be written self.set_data(value, key='example_property_one') and it would do the same thing.
        self.set_data(value)
```

--------------------------------

### Example: Show Choose Object Dialog

Source: https://sims4communitylibrary.readthedocs.io/en/latest/sims4communitylib.dialogs.basic_dialogs.html

Example function that creates and shows a CommonChooseObjectDialog. It defines a callback for when a choice is made, creates localized strings for title and description tokens, builds a list of ObjectPickerRow options, and shows the dialog with pagination set to 2 rows per page.

```python
def _common_testing_show_choose_object_dialog():

    def _on_chosen(choice: str, outcome: CommonChoiceOutcome):
        pass

    # LocalizedStrings within other LocalizedStrings
    title_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING, text_color=CommonLocalizedStringColor.GREEN),)
    description_tokens = (CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME, tokens=(CommonSimUtils.get_active_sim_info(),), text_color=CommonLocalizedStringColor.BLUE),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    options = [
        ObjectPickerRow(
            option_id=1,
            name=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE),
            row_tooltip=None,
            icon=CommonIconUtils.load_checked_square_icon(),
            tag='Value 1'
        ),
        ObjectPickerRow(
            option_id=2,
            name=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 2'
        ),
        ObjectPickerRow(
            option_id=3,
            name=CommonLocalizationUtils.create_localized_string('Value 3'),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 3'
        )
    ]
    dialog = CommonChooseObjectDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        tuple(options),
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        per_page=2
    )
    dialog.show(on_chosen=_on_chosen)
```
Tokens:
Raw