Object Utilities¶

Creation¶

Spawn, Despawn, Destroy¶

class CommonObjectSpawnUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for creating, spawning, and despawning Objects.

classmethod create_object(object_definition_id, on_object_initialize_callback=None, post_object_spawned_callback=None, location_type=ItemLocation.ON_LOT, **kwargs)¶

Create an Object.

Parameters:	object_definition_id (int) – The decimal identifier of the definition of an Object. on_object_initialize_callback (Callable[[GameObject], Any], optional) – Called when initializing the Object. post_object_spawned_callback (Callable[[GameObject], Any], optional) – Called after the Object was added. location_type (ItemLocation, optional) – The location the object is intended to be spawned at. Default is on the lot.
Returns:	An instance of the created Object or None if not successfully created.
Return type:	GameObject

classmethod destroy_object(game_object, source=None, cause=None, **kwargs)¶

Destroy an Object.

Parameters:	game_object (GameObject) – An instance of an Object. source (str, optional) – The source of the destruction. cause (str, optional) – The cause of the destruction.
Returns:	True, if the Object was successfully destroyed. False, if not.
Return type:	bool

classmethod fade_in(game_object, fade_duration=1.0, immediate=False, additional_channels=None)¶

Change the opacity of an Object from invisible to visible.

Parameters:

game_object (GameObject) – An instance of an Object.
fade_duration (float, optional) – The number of milliseconds the fade effect should take to complete. Default is 1.0.
immediate (bool, optional) – If set to True, fade in will occur immediately. Default is False.
additional_channels (Iterator[Tuple[int, int, int]], optional) – A collection of additional channels. The order of the inner tuple is Manager Id, Object Id, and Mask. Default is None.

classmethod fade_out(game_object, fade_duration=1.0, immediate=False, additional_channels=None)¶

Change the opacity of an Object from visible to invisible.

Parameters:

game_object (GameObject) – An instance of an Object.
fade_duration (float, optional) – The number of milliseconds the fade effect should take to complete. Default is 1.0.
immediate (bool, optional) – If set to True, fade out will occur immediately. Default is False.
additional_channels (Iterator[Tuple[int, int, int]], optional) – A collection of additional channels. The order of the inner tuple is Manager Id, Object Id, and Mask. Default is None.

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:	The identifier for the log
Return type:	str

classmethod hard_reset(game_object, reset_reason=ResetReason.RESET_EXPECTED, source=None, cause=None)¶

Perform a hard reset on an Object.

Parameters:	game_object (GameObject) – An instance of an Object. reset_reason (ResetReason, optional) – The reason for the reset. Default is ResetReason.RESET_EXPECTED. source (Any, optional) – The source of the reset. Default is the GameObject. cause (Any, optional) – The cause of the reset. Default is ‘S4CL Hard Reset’.
Returns:	True, if the reset was successful. False, if not.
Return type:	bool

classmethod schedule_object_for_destroy(game_object, source=None, cause=None, on_destroyed=None, **kwargs)¶

Schedule an Object to be destroyed.

Parameters:	game_object (GameObject) – An instance of an Object. source (str, optional) – The source of the destruction. Default is None. cause (str, optional) – The cause of the destruction. Default is None. on_destroyed (Callable[[], None], optional) – A callback that occurs after the Object is destroyed. Default is None.
Returns:	True, if the Object was successfully scheduled for destruction. False, if not.
Return type:	bool

classmethod soft_reset(game_object, reset_reason=ResetReason.RESET_EXPECTED, hard_reset_on_exception=False, source=None, cause=None)¶

Perform a soft reset on an Object.

Parameters:	game_object (GameObject) – An instance of an Object. reset_reason (ResetReason, optional) – The reason for the reset. Default is ResetReason.RESET_EXPECTED. hard_reset_on_exception (bool, optional) – If set to True, a hard reset of the Object will be attempted upon an error occurring. If set to False, nothing will occur if the reset failed. Default is False. source (Any, optional) – The source of the reset. Default is the GameObject. cause (Any, optional) – The cause of the reset. Default is ‘S4CL Soft Reset’.
Returns:	True, if the reset was successful. False, if not.
Return type:	bool

classmethod spawn_object_near_location(object_definition_id: int, location: sims4communitylib.classes.math.common_location.CommonLocation, radius: int = 1, on_object_initialize_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd29ac8410>], Any] = None, post_object_spawned_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd29ac8410>], Any] = None, **kwargs) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd29ac8410>¶

spawn_object_near_location( object_definition_id, location, radius=1, on_object_initialize_callback=None, post_object_spawned_callback=None, **kwargs )

Spawn an Object near a location.

Parameters:	object_definition_id (int) – The decimal identifier of the definition of an Object. location (CommonLocation) – The location to spawn the Object at. radius (int, optional) – The radius at which the object may spawn in with the location at the center. Default is 1 square out. on_object_initialize_callback (Callable[[GameObject], Any], optional) – Called when initializing the Object. post_object_spawned_callback (Callable[[GameObject], Any], optional) – Called after the Object was added to the lot.
Returns:	An instance of the spawned Object or None if not successfully spawned.
Return type:	GameObject

classmethod spawn_object_on_lot(object_definition_id, location, on_object_initialize_callback=None, post_object_spawned_callback=None, **kwargs)¶

Spawn an Object on the current lot.

Parameters:	object_definition_id (int) – The decimal identifier of the definition of an Object. location (CommonLocation) – The location to spawn the Object at. on_object_initialize_callback (Callable[[GameObject], Any], optional) – Called when initializing the Object. post_object_spawned_callback (Callable[[GameObject], Any], optional) – Called after the Object was added to the lot.
Returns:	An instance of the spawned Object or None if not successfully spawned.
Return type:	GameObject

Locational¶

Location¶

Visibility¶

class CommonObjectVisibilityUtils¶

Bases: object

Utilities for manipulating the visibility and persistence of Objects.

static get_opacity(game_object)¶

Retrieve the opacity of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	How opaque the Object is.
Return type:	int

static get_persistence_group(game_object)¶

Retrieve the persistence group of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The persistence group of the Object.
Return type:	PersistenceGroups, optional

static set_opacity(game_object, opacity)¶

Set the opacity of an Object.

Parameters:	game_object (GameObject) – An instance of an Object. opacity (int) – Determines how opaque the Object will be.
Returns:	True, if successful. False, if not.
Return type:	bool

static set_persistence_group(game_object, persistence_group)¶

Set the persistence group of an Object.

Parameters:	game_object (GameObject) – An instance of an Object. persistence_group (PersistenceGroups) – The PersistenceGroup of the Object.
Returns:	True, if successful. False, if not.
Return type:	bool

Data¶

Inventory¶

class CommonObjectInventoryUtils¶

Bases: object

Utilities for manipulating the inventory of Objects.

static add_to_inventory(game_object, object_definition_id, count=1)¶

Add a number of Newly Created Objects to the Inventory of an Object.

Parameters:	game_object (GameObject) – An instance of an Object. object_id (int) – The decimal identifier of an Object. count (int, optional) – The number of the specified Object to add. Default is 1.
Returns:	True, if the count of the specified Object were added successfully. False, it not.
Return type:	bool

static get_all_objects_in_inventory_gen(game_object, include_object_callback=None)¶

Retrieve all Objects in the inventory of an Object.

Parameters:	game_object (GameObject) – An instance of a Game Object. include_object_callback (Callable[[int], bool], optional) – If the result of this callback is True, the object will be included in the results. If set to None, All objects in the inventory will be included.
Returns:	An iterator containing the decimal identifiers for the objects in the inventory of an Object.
Return type:	Iterator[GameObject]

static get_count_of_object_in_inventory(game_object, object_id)¶

Count the number of an Object in the inventory of an Object.

Parameters:	game_object (GameObject) – An instance of an Object. object_id (int) – The decimal identifier of an object.
Returns:	The number of a particular Object found in the inventory of the specified Object.
Type:	int

static has_inventory(game_object)¶

Determine if an Object has an inventory.

Parameters:	game_object (GameObject) – An instance of a Game Object.
Returns:	True, if the Sim has an inventory. False, if not.
Return type:	bool

static move_object_to_inventory(game_object_container, game_object_to_move)¶

Move an Object to the inventory of an Object container.

Parameters:	game_object_container (GameObject) – The Object container to receive the moved Object. game_object_to_move (GameObject) – The Object to move.
Returns:	True, if the object was successfully moved to the inventory of the specified Object container. False, if not.
Return type:	bool

static open_inventory(game_object)¶

Open the inventory of an Object.

Parameters:	game_object (GameObject) – The Object to open the inventory of.

static remove_from_inventory_by_definition(game_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1948fd90>, object_definition: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd1948f9d0>, count: int = 1) → bool¶

remove_from_inventory(game_object, object_id, count=1)

Remove a number of Objects from the inventory of an Object.

Parameters:	game_object (GameObject) – An instance of an Object. object_definition (ObjectDefinition) – The definition of an Object. count (int, optional) – The amount of the Object to remove. Default is 1.
Returns:	True, if the count of the specified Object were removed successfully. False, if not.

static remove_from_inventory_by_id(game_object, object_id, count=1)¶

Remove a number of Objects by their Id from the inventory of an Object.

Parameters:	game_object (GameObject) – The Object to remove Objects from. object_id (int) – The decimal identifier of an Object. count (int, optional) – The amount of the Object to remove. Default is 1.
Returns:	True, if the count of the specified Object were removed successfully. False, if not.

static set_ownership_of_all_items_in_object_inventory_to_sim(game_object, sim_info)¶

Change the ownership status of all items in the inventory of an Object to be owned by the household of a Sim.

Parameters:	game_object (GameObject) – The objects in the inventory of this Object will become owned by the household of the Sim sim_info (SimInfo) – The household of this Sim will be the new owner for all items in the inventory of the Object.
Returns:	True, if ownership was transferred successfully. False, if not.
Return type:	bool

Lock Utils¶

class CommonObjectLockUtils¶

Bases: object

Utilities for manipulating the locking component of Objects, such as the ones found on Doors.

static get_portal_locking_component(game_object)¶

Retrieve the Portal Locking component of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The Portal Locking component of the Object or None if an error occurs.
Return type:	Union[BaseLockingComponent, None]

static is_door_locked_for_sim(door, sim_info)¶

Determine if a Door is locked for a Sim.

Parameters:	door (Door) – An instance of a Door. sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the Door is locked for the specified Sim. False, if not.
Return type:	bool

static lock_door(door, sim_info_list, lock_priority=LockPriority.PLAYER_LOCK, lock_sides=LockSide.LOCK_BOTH, clear_existing_locks=ClearLock.CLEAR_OTHER_LOCK_TYPES, replace_same_lock_type=False)¶

Lock a Door for Sims.

Parameters:	door (Door) – An instance of a Door. sim_info_list (Iterator[SimInfo]) – A collection of Sims to lock the door for. lock_priority (LockPriority, optional) – The priority of the lock being locked. Default is LockPriority.PLAYER_LOCK. lock_sides (LockSide, optional) – The side(s) of the door to lock. Default is Both Sides. clear_existing_locks (ClearLock, optional) – The other types of locks to clear from the door when locking it. Default is ClearLock.CLEAR_OTHER_LOCK_TYPES. replace_same_lock_type (bool, optional) – Set to True to replace lock types that are the same. Set to False to keep lock types that are the same. Default is False.
Returns:	True, if the Door was locked successfully. False, if not.
Return type:	bool

static refresh_portal_locks(game_object)¶

Refresh the Portal Locks of an Object.

Note

If an Object cannot be locked, this function will do nothing.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if locks were refreshed successfully. False, if not.
Return type:	bool

static refresh_portal_locks_on_all_objects(include_object_callback=None)¶

Refresh the Portal Locks on all Objects.

Parameters:	include_object_callback (Callable[[GameObject], bool], optional) – If the result of this callback is True, the Object will be have it’s locks refreshed. If set to None, All Objects will have their locks refreshed. Default is None.
Returns:	True, if the locks on all Objects were successfully refreshed. False, if not.
Return type:	bool

static test_door_lock_for_sim(door, sim_info)¶

Determine if a door is locked for a Sim.

Parameters:	door (Door) – An instance of a Door. sim_info (SimInfo) – An instance of a Sim.
Returns:	The result of the door being locked and which side it is on.
Return type:	bool

static unlock_door(door, sim_info_list, lock_priority=LockPriority.PLAYER_LOCK, unlock_sides=LockSide.LOCK_BOTH, clear_existing_locks=ClearLock.CLEAR_NONE, replace_same_lock_type=False)¶

Unlock a Door for Sims.

Parameters:	door (Door) – An instance of a Door. sim_info_list (Iterator[SimInfo]) – A collection of Sims to lock the door for. lock_priority (LockPriority, optional) – The priority of the lock being unlocked. Default is LockPriority.PLAYER_LOCK. unlock_sides (LockSide, optional) – The side(s) of the door to unlock. Default is Both Sides. clear_existing_locks (ClearLock, optional) – The other types of locks to clear from the door when unlocking it. Default is ClearLock.CLEAR_NONE.
Returns:	True, if the Door was unlocked successfully. False, if not.
Return type:	bool

Slots¶

class CommonObjectSlotUtils¶

Bases: object

Utilities for manipulating object slots.

classmethod get_all_connected_objects_gen(script_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd193f5610>, include_self: bool = False, direct_connections_only: bool = False, include_object_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd193f5610>], bool] = None) → Iterator[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd19dec5d0>]¶

get_all_connected_objects_generator( script_object, include_self=False, direct_connections_only=False, include_object_callback=None )

Retrieve all objects connected to the specified Object.

Parameters:	script_object (ScriptObject) – The Object to locate connections with. include_self (bool, optional) – If True, then script_object will be included in the results. If False, script_object will not be included in the results. Default is False. direct_connections_only (bool, optional) – If True, then only directly connected objects will be included in the results. If False, all connected objects as well as all objects connected to those objects recursively will be included in the results. include_object_callback (Callable[[ScriptObject], bool], optional) – If the result of this callback is True, the Object will be included in the results. If set to None, All Objects will be included. Default is None.
Returns:	An iterator of Objects connected to the specified Object.
Return type:	Iterator[BaseObject]

classmethod get_connected_objects_by_slot_name_gen(script_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd193f5610>, slot_name: sims4communitylib.enums.common_slot_type.CommonSlotType, include_object_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd193f5610>], bool] = None) → Iterator[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd193f5610>]¶

get_connected_objects_by_slot_generator(script_object, slot_name, include_object_callback=None)

Get all connected objects by slot.

Parameters:	script_object (ScriptObject) – The Object to locate connections with. slot_name (CommonSlotType) – The name of the slot to locate a connected objects at. include_object_callback (Callable[[ScriptObject], bool], optional) – If the result of this callback is True, the Object will be included in the results. If set to None, All Objects will be included. Default is None.
Returns:	An iterator of objects connected to the specified object at the specified slot.
Return type:	Iterator[ScriptObject]

classmethod get_containment_slots(game_object)¶

Retrieve the containment slots of an object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	A collection of containment slots on the specified object.
Return type:	Tuple[CommonObjectContainmentSlot]

classmethod get_first_connected_object_by_slot_name(script_object, slot_name, include_object_callback=None)¶

Get the first connected object by slot.

Note

If only the first object found matching the slot type will be returned.

Parameters:	script_object (ScriptObject) – The Object to locate connections with. slot_name (CommonSlotType) – The name of the slot to locate a connected object at. include_object_callback (Callable[[ScriptObject], bool], optional) – If the result of this callback is True, the Object will be included in the results. If set to None, All Objects will be included. Default is None.
Returns:	The object connected to the specified object at the specified slot or None if no object is found.
Return type:	Union[ScriptObject, None]

classmethod get_slot_component(game_object)¶

Retrieve the SlotComponent of an Object.

Parameters:	game_object (GameObject) – An instance of an object.
Returns:	The SlotComponent of the object or None if not found.
Return type:	bool

classmethod get_slot_name(slot)¶

Retrieve the name of a slot.

Parameters:	slot (SlotType) – The slot to use.
Returns:	The name of the slot or ‘No Slot Name’ if a problem occurs.
Return type:	str

State¶

class CommonObjectStateUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for manipulating the state of Objects.

static break_object(game_object)¶

Break an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object has been broken. False, if not.
Return type:	bool

static can_become_broken(game_object)¶

Determine if an Object is able to break.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object is able to break. False, if not.
Return type:	bool

static can_become_dirty(game_object)¶

Determine if an Object is able to get dirty.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object is able to get dirty. False, if not.
Return type:	bool

static convert_quality_from_object_state_value(value)¶

Convert an ObjectStateValue to a matching CommonObjectQuality value.

Parameters:	value (ObjectStateValue) – An instance of ObjectStateValue
Returns:	The specified ObjectStateValue translated to CommonObjectQuality or None if the value could not be translated.
Return type:	Union[‘CommonObjectQuality’, None]

static convert_quality_to_object_state_value(value)¶

Convert CommonObjectQuality to an ObjectStateValue.

Parameters:	value (CommonObjectQuality) – The value to convert.
Returns:	The value translated to an ObjectStateValue, or None if the value could not be translated.
Return type:	Union[ObjectStateValue, None]

static fix_object(game_object)¶

Fix an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object has been fixed. False, if not.
Return type:	bool

classmethod get_current_object_state(game_object, object_state)¶

Get the value of a state on an Object.

Parameters:	game_object (GameObject) – The Object to change. object_state (Union[int, CommonObjectStateId, ObjectState]) – The state to use.
Returns:	The value of the specified state on an Object or None if a problem occurs.
Return type:	Union[ObjectStateValue, None]

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:	The identifier for the log
Return type:	str

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.

static get_object_state_component(game_object)¶

Retrieve the State Component of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The State Component of the specified Object or None if no state component is found.
Return type:	Union[StateComponent, None]

classmethod get_object_state_guid(object_state)¶

Retrieve the GUID of an object state. (Not to be confused with the instance id)

Parameters:	object_state (ObjectState) – An instance of an object state.
Returns:	The GUID of the state or None if no identifier is found.
Return type:	Union[int, None]

classmethod get_object_state_items(game_object)¶

Retrieve all Object States of an objects.

Parameters:	game_object (GameObject) – The object to check.
Returns:	A mapping of Object State to the current value of the object state.
Return type:	Dict[ObjectState, ObjectStateValue]

classmethod get_object_state_value_guid(object_state_value)¶

Retrieve the GUID of an object state. (Not to be confused with the instance id)

Parameters:	object_state_value (ObjectStateValue) – An instance of an object state.
Returns:	The GUID of the state value or None if no identifier is found.
Return type:	Union[int, None]

classmethod get_object_states(game_object)¶

Retrieve the state values of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	A collection of ObjectStateValues.
Return type:	Tuple[ObjectStateValue]

static get_quality(game_object)¶

Retrieve the Quality of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The CommonObjectQuality that represents the quality of the Object, or None if the quality could not be determined.
Return type:	Union[CommonObjectQuality, None]

static get_quality_state(game_object)¶

Retrieve the Quality State of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The quality state of the Object or None when not found.
Return type:	Union[ObjectStateValue, None]

classmethod has_all_object_states(game_object, object_state_ids)¶

Determine if an Object has all of the specified object states.

Parameters:	game_object (GameObject) – An instance of an Object. object_state_ids (Tuple[int]) – A collection of decimal identifiers for object states.
Returns:	True, if the object has all of the specified object states. False, if not.
Return type:	bool

classmethod has_any_object_states(game_object, object_state_ids)¶

Determine if an Object has any of the specified object states.

Parameters:	game_object (GameObject) – An instance of an Object. object_state_ids (Tuple[int]) – A collection of decimal identifiers for object states.
Returns:	True, if the object has any of the specified object states. False, if not.
Return type:	bool

static has_normal_quality(game_object)¶

Determine if an object has normal quality.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object has normal quality. False, if not.
Return type:	bool

classmethod has_object_state(game_object, object_state_identifier)¶

Determine if an Object has an object state available.

Parameters:	game_object (GameObject) – The Object to check. object_state_identifier (Union[int, CommonObjectStateId, CommonObjectStateValueId, ObjectState, ObjectStateValue]) – The identifier of the state to check.
Returns:	True, if the Object has the specified object state as one of its available states (Not if the specified value is what the state on the object is set to). False, if not.
Return type:	bool

classmethod has_object_state_value(game_object, object_state_value_identifier)¶

Determine if an Object has a state set to an Object State Value

Parameters:	game_object (GameObject) – The Object to check. object_state_value_identifier (Union[int, CommonObjectStateValueId, ObjectStateValue]) – The identifier of the object state value to check.
Returns:	True, if the Object has the specified object state value set. False, if not.
Return type:	bool

static has_outstanding_quality(game_object)¶

Determine if an object has outstanding quality.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object has outstanding quality. False, if not.
Return type:	bool

static has_poor_quality(game_object)¶

Determine if an object has poor quality.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object has poor quality. False, if not.
Return type:	bool

static is_broken(game_object)¶

Determine if an Object is broken.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object is broken. False, if not.
Return type:	bool

static is_dirty(game_object)¶

Determine if an Object is dirty.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object is dirty. False, if not.
Return type:	bool

classmethod is_object_in_state(game_object, object_state_value)¶

Determine if an object is in a state.

Parameters:	game_object (GameObject) – The object to check. object_state_value (Union[int, CommonObjectStateValueId, ObjectStateValue]) – The object state value to check.
Returns:	True, if the state of an object has the specified object state value. False, if not.
Return type:	bool

classmethod is_object_usable(game_object)¶

Determine if an Object is in a usable state.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object is in a usable state. False, if not.
Return type:	bool

classmethod load_object_state_by_id(object_state_value)¶

Load an instance of an Object State by its identifier.

Parameters:	object_state (Union[int, CommonObjectStateId, ObjectState]) – The identifier of an Object State.
Returns:	An instance of an Object State Value matching the decimal identifier or None if not found.
Return type:	Union[ObjectState, None]

classmethod load_object_state_value_by_id(object_state_value)¶

Load an instance of an Object State Value by its identifier.

Parameters:	object_state_value (Union[int, CommonObjectStateValueId, ObjectStateValue]) – The identifier of an Object State Value.
Returns:	An instance of an Object State Value matching the decimal identifier or None if not found.
Return type:	Union[ObjectStateValue, None]

static make_clean(game_object)¶

Make an Object clean.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object has been made clean. False, if not.
Return type:	bool

static make_dirty(game_object)¶

Make an Object dirty.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the specified Object has been made dirty. False, if not.
Return type:	bool

classmethod set_object_state(script_object, object_state)¶

Set the object state of an Object.

Parameters:	game_object (GameObject) – The Object to modify. object_state_value (Union[int, CommonObjectStateValueId, ObjectStateValue]) – The state to set.

static set_quality(game_object, quality)¶

Set the quality of an object.

Parameters:	game_object (GameObject) – The object to modify. quality (CommonObjectQuality) – The quality to set.

Tags¶

class CommonObjectTagUtils¶

Bases: object

Utilities for manipulating the tags of objects.

static add_game_tags(game_object, tags, persist=False)¶

Add tags to an Object.

Parameters:	game_object (GameObject) – An instance of an Object. tags (Tuple[Union[int, CommonGameTag]]) – A collection of Game Tags to add. persist (bool, optional) – If True, the Tags will persist to all instances of the Object. If False, the Tags will persist only to the specified Object. Default is False.
Returns:	True, if the Tags were successfully added. False, if not.
Return type:	bool

static get_game_tags(game_object)¶

Retrieve the tags of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	A collection of tags the Object has.
Return type:	Set[int]

static has_game_tags(game_object, tags)¶

Determine if an Object has any of the specified tags.

Parameters:	game_object (GameObject) – An instance of an Object. tags (Iterator[Union[int, CommonGameTag]]) – A collection of tags to locate.
Returns:	True, if the Object has any of the specified tags. False, if not.
Return type:	bool

static remove_game_tags(game_object, tags)¶

Remove tags from an Object.

Parameters:	game_object (GameObject) – An instance of an Object. tags (Tuple[Union[int, CommonGameTag]]) – A collection of Game Tags to remove.
Returns:	True, if the Tags were successfully removed. False, if not.
Return type:	bool

Misc¶

Object¶

class CommonObjectUtils¶

Bases: sims4communitylib.logging._has_s4cl_class_log._HasS4CLClassLog

Utilities for retrieving Objects in various ways.

classmethod create_unique_identifier(game_object)¶

Create a unique identifier for an Object.

Note

The unique identifier will be the same for all objects of the same type. For Example, with two The Ambassador toilets they will have the same unique identifier.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	An identifier that uniquely identifies a specific type of Object.
Return type:	int

classmethod get_catalog_name(game_object)¶

Retrieve the catalog name identifier of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The decimal identifier of the catalog name of an Object or -1 if no catalog name is found.
Return type:	int

classmethod get_game_object(game_object_id)¶

Retrieve an instance of an Object in the game world.

Parameters:	game_object_id (int) – The decimal identifier of an Object.
Returns:	An instance of an Object or None if not found.
Return type:	GameObject

classmethod get_game_object_definition(game_object, pack_safe=False, get_fallback_definition_id=True)¶

Retrieve the definition for an Object.

Parameters:	game_object (GameObject) – An instance of a GameObject. pack_safe (bool, optional) – If true, objects will be searched for keeping package safety in mind. Default is False. get_fallback_definition_id (bool, optional) – Set True, to locate a fallback definition id. Default is True.
Returns:	The definition of the Game Object or None if no definition is found.
Return type:	Definition

classmethod get_game_object_definition_id(game_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd28725690>, pack_safe: bool = False, get_fallback_definition_id: bool = True) → Optional[int]¶

get_game_object_definition(game_object, pack_safe=False, get_fallback_definition_id=True)

Retrieve the definition for an Object.

Parameters:	game_object (GameObject) – An instance of a GameObject. pack_safe (bool, optional) – If true, objects will be searched for keeping package safety in mind. Default is False. get_fallback_definition_id (bool, optional) – Set True, to locate a fallback definition id. Default is True.
Returns:	The id of the definition of the Game Object or None if no definition is found.
Return type:	Union[int, None]

classmethod get_game_object_manager()¶

Retrieve the manager that manages all Game Objects in a game world.

Returns:	The manager that manages all Game Objects in a game world.
Return type:	ObjectManager

classmethod get_instance_for_all_game_objects_generator(include_object_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd28725690>], bool] = None) → Iterator[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd28725690>]¶

get_instance_for_all_objects_generator(include_object_callback=None)

Retrieve an instance for each and every Object in the game world.

Parameters:	include_object_callback (Callable[[GameObject], bool], optional) – If the result of this callback is True, the Object will be included in the results. If set to None, All Objects will be included.
Returns:	An iterator of all Objects matching the include_object_callback filter.
Return type:	Iterator[GameObject]

classmethod get_instance_for_all_visible_game_objects_generator(include_object_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd28725690>], bool] = None) → Iterator[<sphinx.ext.autodoc.importer._MockObject object at 0x7fcd28725690>]¶

get_instance_for_all_visible_objects_generator(include_object_callback=None)

Retrieve an instance for each and every visible Object in the game world.

Parameters:	include_object_callback (Callable[[GameObject], bool], optional) – If the result of this callback is True, the Object will be included in the results. If set to None, All Objects will be included.
Returns:	An iterator of all Objects matching the include_object_callback filter.
Return type:	Iterator[GameObject]

classmethod get_log_identifier()¶

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:	The identifier for the log
Return type:	str

classmethod get_object_definition(object_id, pack_safe=False, get_fallback_definition_id=True)¶

Retrieve the definition for an Object.

Parameters:	object_id (int) – The decimal identifier of an Object. pack_safe (bool, optional) – If true, objects will be searched for keeping package safety in mind. Default is False. get_fallback_definition_id (bool, optional) – Set True, to locate a fallback definition id. Default is True.
Returns:	The definition of the object with the id.
Return type:	Definition

classmethod get_object_definition_id(object_id, pack_safe=False, get_fallback_definition_id=True)¶

Retrieve the definition for an Object.

Parameters:	object_id (int) – The decimal identifier of an Object. pack_safe (bool, optional) – If true, objects will be searched for keeping package safety in mind. Default is False. get_fallback_definition_id (bool, optional) – Set True, to locate a fallback definition id. Default is True.
Returns:	The id of the definition of the object with the id.
Return type:	Union[int, None]

classmethod get_object_guid(game_object)¶

Retrieve the GUID of an Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The GUID of the specified Object or -1 if it does not have one.
Return type:	int

classmethod get_object_id(object_instance)¶

Retrieve the decimal identifier of an Object.

Parameters:	object_instance (BaseObject) – An instance of an Object.
Returns:	The decimal identifier of the BaseObject or -1 if the id could not be gained.
Return type:	int

classmethod get_root_parent(object_instance)¶

Retrieve the root parent of an Object.

Parameters:	object_instance (ScriptObject) – An instance of an Object.
Returns:	The root parent of the Object or None if a problem occurs.
Return type:	Union[ScriptObject, None]

classmethod has_root_parent(object_instance)¶

Determine if an Object has a root parent.

Parameters:	object_instance (ScriptObject) – An instance of an Object.
Returns:	True, if the Object has a root parent. False, if not.
Return type:	bool

Object Type¶

class CommonObjectTypeUtils¶

Bases: object

Utilities for determining the type of an object.

static is_adult_bed(game_object)¶

Determine if an Object is a Bed for Adult Sims.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Bed for Adult Sims. False, if not.
Return type:	bool

static is_bed(game_object)¶

Determine if an Object is a Bed.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Bed. False, if not.
Return type:	bool

static is_chicken(game_object)¶

Determine if an Object is a Chicken.

Note

A Chicken is either a Hen or Rooster.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Chicken. False, if not.
Return type:	bool

static is_child_bed(game_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd19288c50>) → bool¶

is_adult_bed(game_object)

Determine if an Object is a Bed for Child Sims.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Bed for Child Sims. False, if not.
Return type:	bool

static is_cow(game_object)¶

Determine if an Object is a Cow.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Cow. False, if not.
Return type:	bool

static is_dolphin(game_object)¶

Determine if an Object is a Dolphin.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Dolphin. False, if not.
Return type:	bool

static is_door(game_object)¶

Determine if an Object is a Door.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Door. False, if not.
Return type:	bool

static is_double_bed(game_object)¶

Determine if an Object is a Double Bed.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Double Bed. False, if not.
Return type:	bool

static is_fence(game_object)¶

Determine if an Object is a Fence.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Door. False, if not.
Return type:	bool

static is_hen(game_object)¶

Determine if an Object is a Hen.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Hen. False, if not.
Return type:	bool

static is_human_sim_bed(game_object)¶

Determine if an Object is a Bed for Human Sims.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Bed for Human Sims. False, if not.
Return type:	bool

static is_light(game_object)¶

Determine if an Object is a Light.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Light. False, if not.
Return type:	bool

static is_livestock(game_object)¶

Determine if an Object is considered to be Livestock.

Note

Objects considered to be Livestock are Llamas and Cows.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is Livestock. False, if not.
Return type:	bool

static is_llama(game_object)¶

Determine if an Object is a Llama.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Llama. False, if not.
Return type:	bool

static is_loveseat(game_object)¶

Determine if an Object is a Loveseat.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Loveseat. False, if not.
Return type:	bool

static is_pet_sim_bed(game_object)¶

Determine if an Object is a Bed for Pet Sims.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Bed for Pet Sims. False, if not.
Return type:	bool

static is_rabbit(game_object)¶

Determine if an Object is a Rabbit.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Rabbit. False, if not.
Return type:	bool

static is_rooster(game_object)¶

Determine if an Object is a Rooster.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Rooster. False, if not.
Return type:	bool

static is_single_bed(game_object)¶

Determine if an Object is a Single Bed.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Single Bed. False, if not.
Return type:	bool

static is_stair(game_object)¶

Determine if an Object is a Stair.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Stair. False, if not.
Return type:	bool

static is_swimming_pool(game_object)¶

Determine if an Object is a Swimming Pool.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Swimming Pool. False, if not.
Return type:	bool

static is_swimming_pool_seat(game_object)¶

Determine if an Object is a Swimming Pool Seat.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Swimming Pool Seat. False, if not.
Return type:	bool

static is_toddler_bed(game_object)¶

Determine if an Object is a Bed for Toddler Sims.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Bed for Toddler Sims. False, if not.
Return type:	bool

static is_toilet(game_object)¶

Determine if an Object is a Toilet.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Toilet. False, if not.
Return type:	bool

static is_vacuum_cleaner(game_object)¶

Determine if an Object is a Vacuum Cleaner.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Vacuum Cleaner. False, if not.
Return type:	bool

static is_window(game_object)¶

Determine if an Object is a window.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	True, if the Object is a Window. False, if not.
Return type:	bool

Interactions¶

Ownership¶

class CommonObjectOwnershipUtils¶

Bases: object

Utilities for manipulating the ownership of Objects.

static get_ownable_component(game_object)¶

Retrieve the Ownable Component of an Object if it has one.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The OwnableComponent of the Object or None if no OwnableComponent was found.
Return type:	Union[OwnableComponent, None]

static get_owning_household_id(game_object)¶

Retrieve the decimal identifier of the Household that owns the Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The decimal identifier of the Household that owns the object.
Return type:	int

static get_owning_sim(game_object)¶

Retrieve the Sim that owns an Object, if a Sim owns the Object.

Parameters:	game_object (GameObject) – An instance of an Object.
Returns:	The SimInfo of the Sim that owns the specified Object or None if no Sim owns the Object.
Return type:	Union[SimInfo, None]

static set_owning_household_id(game_object, household_id)¶

Set the Household that owns the Object.

Parameters:	game_object (GameObject) – An instance of an Object. household_id (int) – The decimal identifier of a Household.
Returns:	True, if the Household was successfully set as the owner. False, if not.
Return type:	bool

static set_owning_sim(game_object, sim_info, make_sim_sole_owner=True)¶

Change the ownership of an Object to become owned by the household of a Sim and optional by the Sim themselves.

Parameters:	game_object (GameObject) – An instance of an Object. sim_info (SimInfo) – An instance of a Sim. make_sim_sole_owner (bool, optional) – If True, the Sim will become the sole owner in their household of the Object (In addition to the household owning it). If False, only the household will own the Object. Default is True.
Returns:	True, if ownership was transferred successfully. False, if not.
Return type:	bool

Reservation¶

class CommonObjectReservationUtils¶

Bases: object

Utilities for object reservations.

static begin_reservation(reservation_handler)¶

Begin reservation for the specified reservation handler.

Parameters:	reservation_handler (_ReservationHandler) – The reservation handler to start.
Returns:	The result of beginning the reservation.
Return type:	ReservationResult

static can_be_reserved_by(game_object, sim_info)¶

Determine if an object can be reserved by the Sim.

Parameters:	game_object (GameObject) – An instance of an object. sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the object can be reserved. False, if not.
Return type:	bool

static create_reservation_handler(object_instance, sim_info, **kwargs)¶

Create a reservation handler for a Sim to reserve an object.

Parameters:	object_instance (Union[GameObject, Part, BasicPropObject]) – An instance of an object. sim_info (SimInfo) – An instance of a Sim. This Sim will be reserving the object. kwargs (Any) – Keyword arguments used when creating the reservation handler.
Returns:	An instance of a Reservation Handler or None if a problem occurs.
Return type:	Union[_ReservationHandler, None]

static end_reservation(reservation_handler)¶

End reservation for the specified reservation handler.

Parameters:	reservation_handler (_ReservationHandler) – The reservation handler to end.
Returns:	The result of ending the reservation.
Return type:	bool

static get_sims_using_object(game_object)¶

Retrieve a collection of Sims using the object.

Parameters:	game_object (GameObject) – An instance of an object.
Returns:	A collection of Sims using the object.
Return type:	Tuple[SimInfo]

static has_all_free_slots(game_object, slot_types=())¶

Determine if an Object has all of the specified slots available for use.

Parameters:	game_object (GameObject) – An instance of an object. slot_types (Tuple[CommonSlotTypes], optional) – A collection of CommonSlotTypes. Default is an empty collection.
Returns:	True, if all of the specified slots are free on the Object. False, if not.
Return type:	bool

static is_in_use(game_object)¶

Determine if an Object is in use.

Parameters:	game_object (GameObject) – An instance of an object.
Returns:	True, if the object is in use. False, if not.
Return type:	bool

static is_in_use_by(game_object, sim_info)¶

Determine if an Object is in use by the specified Sim.

Parameters:	game_object (GameObject) – An instance of an object. sim_info (SimInfo) – An instance of a Sim.
Returns:	True, if the object is in use by the specified Sim. False, if not.
Return type:	bool