core.physics package

Submodules

core.physics.vector module

Two-dimensional vectors in Forge.

class core.physics.vector.Vector2D(x: float, y: float)

Bases: object

Forge’s representation of a two-dimensional vector.

as_pygame_vector() Vector2

Return the vector as a Pygame 2D vector. Beneficial for internal interoperability with Pygame.

Returns

Pygame vector from the vector’s x and y components respectively.

Return type

pygame.math.Vector2

as_tuple() tuple[float, float]

Return the x and y components of the vector in a tuple. Beneficial for internal interoperability with Pygame.

Returns

Tuple of the vector’s x and y components respectively.

Return type

tuple[float, float]

is_normalized(precision: int = 4) bool

Check whether the vector is normalized, i.e., its length is equal to one.

Parameters

precision – Precision to which the length of the vector is to be checked to keep a delta for

floating-point inaccuracies; defaults to 4. :type precision: int

Returns

True if the length or magnitude of the vector is equal to one; else False.

Return type

bool

length() float

Compute the length of the vector.

Returns

Length or magnitude of the vector.

Return type

float

length_squared() float

Compute the square of the length of the vector. Faster due to lack of a square root operation.

Returns

Square of the length or magnitude of the vector.

Return type

float

normalize() None

Normalize the vector, i.e., set its length to one while maintaining the same direction.

Raises

ZeroDivisionError – A vector of zero length cannot be normalized.

x: float
y: float
core.physics.vector.angle(from_vector: Vector2D, to_vector: Vector2D) float

Calculate the unsigned angle between one vector and another. The unsigned angle means that the direction of rotation becomes irrelevant.

Parameters
  • from_vector (Vector2D) – Initial vector from which the angle is measured.

  • to_vector (Vector2D) – Final vector from which the angle is stopped being measured.

Returns

Unsigned angle between the two vectors in radians.

Return type

float

core.physics.vector.clamp(vector: Vector2D, min_: Vector2D, max_: Vector2D) Vector2D

Clamp a vector between a specified minimum and maximum bound.

Parameters
  • vector (Vector2D) – Vector to be clamped.

  • min (Vector2D) – Minimum bound of the clamp.

  • max (Vector2D) – Maximum bound of the clamp.

Returns

Vector clamped to the minimum and maximum bound.

Return type

Vector2D

Raises

ValueError – The maximum bound cannot be greater than the minimum bound on either component axis.

core.physics.vector.cross(vector1: Vector2D, vector2: Vector2D) float

Compute the cross product of two vectors.

Parameters
Returns

Magnitude of the cross or vector product of the two vectors.

Return type

float

core.physics.vector.distance_between(vector1: Vector2D, vector2: Vector2D) float

Compute the distance between two vectors.

Parameters
Returns

Distance between the two vectors.

Return type

float

core.physics.vector.distance_squared_between(vector1: Vector2D, vector2: Vector2D) float

Compute the square of the distance between two vectors. Faster due to lack of a square root operation.

Parameters
Returns

Square of the distance between the two vectors.

Return type

float

core.physics.vector.dot(vector1: Vector2D, vector2: Vector2D) float

Compute the dot product of two vectors.

Parameters
Returns

Dot or scalar product of the two vectors.

Return type

float

core.physics.vector.down() Vector2D

Create a new vector pointing in the down direction, i.e., x: 0, y: 1.

Returns

New down vector.

Return type

Vector2D

core.physics.vector.from_pygame_vector(vector: Vector2) Vector2D

Create a new vectory using an existing Pygame vector. Beneficial for internal interoperability with Pygame.

Parameters

vector (pygame.math.Vector2) – Pygame 2D vector.

Returns

Forge vector created from the Pygame vector.

Return type

Vector2D

core.physics.vector.from_tuple(position: tuple[float, float]) Vector2D

Create a new vector using an existing tuple of components. Beneficial for internal interoperability with Pygame.

Parameters

position (tuple[float, float]) – Tuple of the vector’s x and y component respectively.

Returns

Vector created from the tuple.

Return type

Vector2D

core.physics.vector.left() Vector2D

Create a new vector pointing in the left direction, i.e., x: -1, y: 0.

Returns

New left vector.

Return type

Vector2D

core.physics.vector.lerp(from_vector: Vector2D, to_vector: Vector2D, t: float) Vector2D

Compute a smooth linear interpolation of a vector along both axes with respect to a constraint.

Parameters
  • from_vector (Vector2D) – Initial vector for the interpolation.

  • to_vector (Vector2D) – Final vector for the interpolation.

  • t (float) – Interpolation parameter to smoothly go from the initial to final vector.

Returns

Linearly interpolated vector between the initial and final vectors.

Return type

Vector2D

core.physics.vector.normalized(vector: Vector2D) Vector2D

Normalize a vector, i.e., set its length to one while maintaining the same direction and return it.

Parameters

vector (Vector2D) – Vector to be normalized.

Returns

Normalized vector of length or magnitude of one.

Return type

Vector2D

Raises

ZeroDivisionError – A vector of zero length cannot be normalized.

core.physics.vector.one() Vector2D

Create a new one vector: i.e., x: 1, y: 1.

Returns

New one vector.

Return type

Vector2D

core.physics.vector.orthogonal(vector: Vector2D) Vector2D

Calculate the orthogonal to a given vector.

Parameters

vector (Vector2D) – Vector whose orthogonal is to be calculated.

Returns

Orthogonal of the vector.

Return type

Vector2D

core.physics.vector.random() Vector2D

Create a new vector pointing in a random direction, i.e. x: -1 | 0 | 1, y: -1 | 0 | 1.

Returns

New random vector.

Return type

Vector2D

core.physics.vector.reflect(direction: Vector2D, normal: Vector2D) Vector2D

Reflect a vector along a given normal to the direction of the vector.

Parameters
  • direction (Vector2D) – Vector to be reflected.

  • normal (Vector2D) – Normal to the reflection.

Returns

Reflected vector with respect to the normal.

Return type

Vector2D

Raises

ValueError – The normal vector must be normalized, or have a length or magnitude of one.

core.physics.vector.right() Vector2D

Create a new vector pointing in the right direction, i.e., x: 1, y: 0.

Returns

New right vector.

Return type

Vector2D

core.physics.vector.scaled(vector: Vector2D, new_scale: float) Vector2D

Scale a vector to a given length while maintaining its current direction.

Parameters
  • vector (Vector2D) – Vector to be scaled.

  • new_scale (float) – New length of the vector.

Returns

Scaled vector with the given length and same direction.

Return type

Vector2D

core.physics.vector.transformed(vector: Vector2D, transform: core.physics.transform.Transform2D) Vector2D

Transform a vector by calculating its position against a supplied transform.

Parameters
  • vector (Vector2D) – Vector to be transformed.

  • transform (core.physics.transform.Transform2D) – Transform for the vector.

Returns

Transformed vector.

Return type

Vector2D

core.physics.vector.up() Vector2D

Create a new vector pointing in the up direction, i.e., x: 0, y: -1.

Returns

New up vector.

Return type

Vector2D

core.physics.vector.zero() Vector2D

Create a new zero vector, i.e., x: 0, y: 0.

Returns

New zero vector.

Return type

Vector2D

core.physics.world module

Game environment in Forge.

core.physics.world.verify_body_constraints(area: float, density: float) None

Verify that a given body fits within Forge’s world constraints of a certain area and density.

Parameters
  • area (float) – Area of the body.

  • density (float) – Density of the body.

Raises

ValueError – The body’s area and density must lie within the given world constraints.

Module contents