Object Utilities

Creation

Spawn, Despawn, Destroy

class CommonObjectSpawnUtils

Bases: object

Utilities for creating, spawning, and despawning Objects.

static 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

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

static 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

static 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

static spawn_object_on_lot(object_definition_id, location, on_object_initialize_callback=None, post_object_spawned_callback=None)

Spawn an Object on the current lot.

Parameters:
  • object_definition_id (int) – The decimal identifier 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

Household Ownership

class CommonObjectHouseholdUtils

Bases: object

Utilities for manipulating Household ownership of Objects.

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

Location

class CommonObjectLocationUtils

Bases: object

Utilities for manipulating the location and draggability of Objects.

static can_be_routed_to(game_object)

Determine if an Object can be routed to by Sims.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:True, if the Object can be routed to by Sims. False, it not.
Return type:bool
static can_drag_object_in_live_mode(game_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fe481184e90>) → bool

can_live_drag(game_object)

Determine if an Object can be dragged in Live Mode.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:True, if the Object can be dragged in Live Mode. False, if not.
Return type:bool
static disable_object_drag_in_live_mode(game_object)

Disable the draggability an Object in Live Mode.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:True, if successful. False, if not.
Return type:bool
static enable_object_drag_in_live_mode(game_object)

Enable the draggability of an Object in Live Mode.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:True, if successful. False, if not.
Return type:bool
static get_bone_position(game_object, bone_name)

Retrieve the position of a joint bone on an Object.

Parameters:
  • game_object (GameObject) – An instance of an Object.
  • bone_name (str) – The name of the bone to retrieve the position of.
Returns:

The position of the Object or None if the Object does not have the specified bone.

Return type:

Union[CommonVector3, None]

static get_forward_vector(game_object)

Retrieve the forward vector of an Object.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The forward vector of the Object.
Return type:CommonVector3
static get_location(game_object)

Retrieve the location of an Object.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The location of the Object or None if the Object does not have a location.
Return type:Union[CommonLocation, None]
static get_orientation(game_object)

Retrieve the orientation of an Object.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The orientation of the Object.
Return type:CommonQuaternion
static get_orientation_degrees(game_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fe481184e90>) → float

get_orientation_in_degrees(game_object)

Retrieve the orientation of an Object in degrees.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The orientation of the Object represented in degrees.
Return type:float
static get_position(game_object)

Retrieve the position of an Object.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The position of the Object or None if the Object does not have a position.
Return type:CommonVector3
static get_root_position(game_object)

Calculate the position of an Object based off of the position of it’s Root bone.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The position of the Object based off of the position of it’s Root bone.
Return type:CommonVector3
static get_routing_surface(game_object)

Retrieve the routing surface of an Object.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The routing surface of the object or None if a problem occurs.
Return type:Union[CommonSurfaceIdentifier, None]
static get_surface_level(game_object)

Retrieve the surface level of an Object.

Parameters:game_object (GameObject) – An instance of an Object.
Returns:The surface level of the object.
Return type:int
static set_location(game_object, location)

Set the location of an Object.

Parameters:
  • game_object (GameObject) – An instance of an Object.
  • location (CommonLocation) – The location to put the Object.
Returns:

True, if successful. False, if not.

Return type:

bool

Visibility

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

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[int]) – 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

Misc

Object

class CommonObjectUtils

Bases: object

Utilities for retrieving Objects in various ways.

static 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 Object.
Return type:int
static 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
static 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
static get_instance_for_all_game_objects_generator(include_object_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fe47ed68cd0>], bool] = None) → Iterator[<sphinx.ext.autodoc.importer._MockObject object at 0x7fe47ed68cd0>]

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 iterable of all Objects matching the include_object_callback filter.
Return type:Iterator[GameObject]
static get_instance_for_all_visible_game_objects_generator(include_object_callback: Callable[[<sphinx.ext.autodoc.importer._MockObject object at 0x7fe47ed68cd0>], bool] = None) → Iterator[<sphinx.ext.autodoc.importer._MockObject object at 0x7fe47ed68cd0>]

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 iterable of all Objects matching the include_object_callback filter.
Return type:Iterator[GameObject]
static get_object_definition(object_id: int, pack_safe: bool = False, get_fallback_definition_id: bool = True) → <sphinx.ext.autodoc.importer._MockObject object at 0x7fe47ec97810>

get_definition(object_id)

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) – Whether or not to locate a fallback definition id. Default is True.
Returns:

The definition of the object with the id.

Return type:

Definition

static 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
static 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
static 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]
static 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
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_child_bed(game_object: <sphinx.ext.autodoc.importer._MockObject object at 0x7fe48126cb90>) → 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_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_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_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_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_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_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

class CommonObjectInteractionUtils

Bases: object

Utilities for manipulating the interactions of Objects.

static get_all_interactions_registered_to_object_gen(script_object, include_interaction_callback=None)

Retrieve all interactions that are registered to an object.

Parameters:
  • script_object (ScriptObject) – An instance of a ScriptObject
  • include_interaction_callback (Callable[[Interaction], bool], optional) – If the result of this callback is True, the Interaction will be included in the results. If set to None, All Interactions will be included. Default is None.
Returns:

An iterable of Interactions that pass the include callback filter.

Return type:

Iterator[Interaction]

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