Math Classes

Note

These classes wrap the vanilla Sims 4 classes to provide insight into the property and functions of them.

Location

class CommonLocation(transform: sims4communitylib.classes.math.common_transform.CommonTransform, routing_surface: sims4communitylib.classes.math.common_surface_identifier.CommonSurfaceIdentifier, parent_ref: Any = None, joint_name_or_hash: Any = None, slot_hash: int = 0)

Bases: object

A class that contains locational data.

static empty()

Create an empty location.

Returns:An empty location.
Return type:CommonLocation
static from_location(location)

Convert a vanilla Location object into a CommonLocation.

Parameters:location (Union[Location, CommonLocation]) – An instance of a Location.
Returns:An instance of a CommonLocation or None if the object failed to convert.
Return type:Union[CommonLocation, None]
joint_name_or_hash

The name or hash identifier of the joint the location is located at.

Returns:The name or hash identifier of the joint the location is located at.
Return type:Union[str, int]
parent_ref

The parent reference of the location.

Returns:The parent reference of the location.
Return type:Any
routing_surface

The routing surface the location is located on.

Returns:The routing surface the location is located on.
Return type:CommonSurfaceIdentifier
slot_hash

The hash identifier of the Slot the location is located at.

Returns:The hash identifier of the Slot the location is located at.
Return type:int
transform

The translation and orientation of the location.

Returns:The translation and orientation of the location.
Return type:CommonTransform

Routing Location

class CommonRoutingLocation(position, orientation=None, routing_surface=None)

Bases: object

A Location used for routing.

Parameters:
  • position (CommonVector3) – The position of the location.
  • orientation (CommonQuaternion, optional) – The orientation of the location. Default is None.
  • routing_surface (CommonSurfaceIdentifier, optional) – The routing surface of the location. Default is None.
static empty()

Create an empty location.

Returns:An empty location.
Return type:CommonRoutingLocation
static from_location(location)

Convert a vanilla Location object into a CommonRoutingLocation.

Parameters:location (Union[routing.Location, sims4.math.Location, CommonLocation, CommonRoutingLocation]) – An instance of a Location.
Returns:An instance of a CommonRoutingLocation or None if the object failed to convert.
Return type:Union[CommonRoutingLocation, None]
get_world_surface_location(self)

Retrieve the Location as a world surface location.

Returns:A world surface location.
Return type:CommonRoutingLocation
orientation

The orientation of the location.

Returns:The orientation of the Location.
Return type:CommonQuaternion
position

The translation and orientation of the location.

Returns:The translation and orientation of the location.
Return type:CommonTransform
routing_surface

The routing surface the location is located on.

Returns:The routing surface the location is located on.
Return type:CommonSurfaceIdentifier

Polygon

class CommonPolygon(polygon_vertices: Tuple[sims4communitylib.classes.math.common_vector3.CommonVector3])

Bases: object

A class that contains polygonal data.

static empty()

Create an empty Polygon.

Returns:An empty Polygon.
Return type:CommonPolygon
static from_polygon(polygon)

Convert a vanilla Polygon object into a CommonPolygon.

Parameters:polygon (Union[Polygon, CommonPolygon]) – An instance of a Polygon
Returns:An instance of a CommonPolygon or None if the object failed to convert.
Return type:Union[CommonLocation, None]

Quaternion

class CommonQuaternion(x: float, y: float, z: float, w: Any)

Bases: object

A class that contains orientation data.

static empty()

Create an empty quaternion.

Returns:An empty quaternion.
Return type:CommonQuaternion
static from_degrees(degrees)

Convert an angle in degrees into a CommonQuaternion.

Parameters:degrees (float) – An angle in degrees
Returns:An instance of a CommonQuaternion.
Return type:CommonQuaternion
static from_quaternion(quaternion)

Convert a Quaternion into a CommonQuaternion.

Parameters:quaternion (Union[Quaternion, MathPb2Quaternion, CommonQuaternion]) – An instance of a Quaternion.
Returns:An instance of a CommonQuaternion or None if the object failed to convert.
Return type:Union[CommonQuaternion, None]
static from_radian(radian)

Convert a radian value into a CommonQuaternion.

Parameters:radian (float) – An angle in radians
Returns:An instance of a CommonQuaternion.
Return type:CommonQuaternion
static to_degrees(quaternion)

Convert a Quaternion into degrees.

Parameters:quaternion (Union[Quaternion, MathPb2Quaternion, CommonQuaternion]) – An instance of a Quaternion.
Returns:The quaternion represented in degrees.
Return type:float
static to_radian(quaternion)

Convert a Quaternion into radians.

Parameters:quaternion (Union[Quaternion, MathPb2Quaternion, CommonQuaternion]) – An instance of a Quaternion.
Returns:The quaternion represented in radians.
Return type:float
transform_vector(vector: CommonVector3) → CommonVector3
w

The rotation.

Returns:The rotation.
Return type:Any
x

The x position.

Returns:The x position.
Return type:float
y

The y position.

Returns:The y position.
Return type:float
z

The z position.

Returns:The z position.
Return type:float

Range (Float)

class CommonFloatRange(min_value=None, max_value=None)

Bases: object

A range with a minimum and maximum for use in calculations.

Parameters:
  • min_value (float, optional) – The minimum threshold. Set to None if there is no minimum. Default is None.
  • max_value (float, optional) – The maximum threshold. Set to None if there is no maximum. Default is None.
in_range(value, or_equal=True)

If a Minimum and Maximum value are specified, determine if the specified value is between or equal to the Minimum and Maximum values. If a Maximum value is not specified, determine if the specified value is greater than or equal to the Minimum value. If a Minimum value is not specified, determine if the specified value is less than or equal to the Maximum value.

Parameters:
  • value (float) – The value to check.
  • or_equal (bool, optional) – If True, the value may equal the minimum or maximum values to pass. Default is True.
Returns:

True, if the value is within range of the Minimum and Maximum values. False, it not.

Return type:

bool

max_value

The maximum threshold of this range.

Returns:The maximum threshold of this range.
Return type:Union[float, None]
min_value

The minimum threshold of this range.

Returns:The minimum threshold of this range.
Return type:Union[float, None]

Range (Integer)

class CommonIntegerRange(min_value=None, max_value=None)

Bases: object

A range with a minimum and maximum for use in calculations.

Parameters:
  • min_value (int, optional) – The minimum threshold. Set to None if there is no minimum. Default is None.
  • max_value (int, optional) – The maximum threshold. Set to None if there is no maximum. Default is None.
in_range(value, or_equal=True)

If a Minimum and Maximum value are specified, determine if the specified value is between or equal to the Minimum and Maximum values. If a Maximum value is not specified, determine if the specified value is greater than or equal to the Minimum value. If a Minimum value is not specified, determine if the specified value is less than or equal to the Maximum value.

Parameters:
  • value (int) – The value to check.
  • or_equal (bool, optional) – If True, the value may equal the minimum or maximum values to pass. Default is True.
Returns:

True, if the value is within range of the Minimum and Maximum values. False, it not.

Return type:

bool

max_value

The maximum threshold of this range.

Returns:The maximum threshold of this range.
Return type:Union[int, None]
min_value

The minimum threshold of this range.

Returns:The minimum threshold of this range.
Return type:Union[int, None]

Surface Identifier

class CommonSurfaceIdentifier(primary_id: int, secondary_id: int = None, surface_type: <sphinx.ext.autodoc.importer._MockObject object at 0x7ff1c36b7790> = <sphinx.ext.autodoc.importer._MockObject object>)

Bases: object

A class that contains surface data.

static empty(secondary_id=0)

Create an empty surface identifier for the current zone.

Parameters:secondary_id (int, optional) – The secondary id to give to the surface identifier. Default is 0.
Returns:An empty surface identifier.
Return type:CommonSurfaceIdentifier
static from_surface_identifier(surface_identifier)

Convert a SurfaceIdentifier into a CommonSurfaceIdentifier.

Parameters:surface_identifier (Union[SurfaceIdentifier, CommonSurfaceIdentifier]) – An instance of a surface identifier.
Returns:An instance of a CommonSurfaceIdentifier or None if it failed to convert.
Return type:Union[CommonSurfaceIdentifier, None]
primary_id

The primary identifier for the surface. This value is usually the identifier of a Zone.

Returns:The primary identifier.
Return type:int
secondary_id

The secondary identifier for the surface. This value is usually the level at which the surface is.

Returns:The secondary identifier.
Return type:Union[int, None]
type

The type of surface.

Returns:The type of surface.
Return type:Union[SurfaceType, None]

Transform

class CommonTransform(translation: sims4communitylib.classes.math.common_vector3.CommonVector3, orientation: sims4communitylib.classes.math.common_quaternion.CommonQuaternion)

Bases: object

A class that contains transformational data.

static empty()

Create an empty transform.

Returns:An empty transform.
Return type:CommonTransform
static from_transform(transform)

Convert a Transform into a CommonTransform.

Parameters:transform (Union[Transform, MathPb2Transform, CommonTransform]) – An instance of a transform.
Returns:An instance of a CommonTransform or None if it failed to convert.
Return type:Union[CommonTransform, None]
orientation

The orientation.

Returns:The orientation.
Return type:CommonQuaternion
translation

The translation.

Returns:The translation.
Return type:CommonVector3

Vector3

class CommonVector3(x: float, y: float, z: float)

Bases: object

A class that contains positional data with three coordinates.

static distance_between(position_one, position_two)

Calculate the distance between two vectors.

Parameters:
Returns:

The distance between the two specified vectors.

Return type:

float

static empty()

Create an empty vector.

Returns:An empty vector.
Return type:CommonVector3
static flatten(vector)

Flatten a Vector.

Parameters:vector (Union[Vector3, Vector3Immutable, MathPb2Vector3, CommonVector3]) – An instance of a vector.
Returns:An instance of a flattened CommonVector3.
Return type:CommonVector3
static from_vector3(vector)

Convert a Vector into a CommonVector3.

Parameters:vector (Union[Vector3, Vector3Immutable, MathPb2Vector3, CommonVector3]) – An instance of a vector.
Returns:An instance of a CommonVector3 or None if it failed to convert.
Return type:Union[CommonVector3, None]
magnitude_squared() → float
static normalize(vector)

Normalize a Vector.

Parameters:vector (Union[Vector3, Vector3Immutable, MathPb2Vector3, CommonVector3]) – An instance of a vector.
Returns:An instance of a normalized CommonVector3.
Return type:float
x

The x position.

Returns:The x position.
Return type:float
y

The y position.

Returns:The y position.
Return type:float
z

The z position.

Returns:The z position.
Return type:float