math
FreeBodyEngine.math
#
VECTOR_LIKE = Union[GenericVector, float, Sequence[float]]
module-attribute
#
BounceOut
#
Curve
#
Bases: ABC
Base class for easing curves: given a progress value x (typically
0-1), maps it to an eased output value used to interpolate animations.
get_value(x)
abstractmethod
#
Evaluates the curve at x.
EaseInOut
#
EaseInOutCircular
#
EaseInOutExpo
#
EaseInOutSin
#
GenericRotation
#
Placeholder for a future rotation representation shared between 2D and 3D transforms; not yet implemented or used anywhere.
GenericVector
#
Linear
#
Rotation
#
Placeholder for a future rotation representation; not yet implemented or used anywhere.
Transform(position, rotation, scale)
#
A 2D position/rotation/scale triple, with rotation a single scalar
angle (degrees) around Z rather than a full rotation object.
position and scale are coerced through Vector(...), so any
VECTOR_LIKE value (a vector, scalar, or 2-sequence) works.
model
property
#
Builds this transform's 4x4 model matrix (scale @ rotation @ translation, as a row-vector affine matrix).
position = Vector(position)
instance-attribute
#
rotation = rotation
instance-attribute
#
scale = Vector(scale)
instance-attribute
#
compose_with(parent_transform)
#
Combines this (local) transform with parent_transform to get
the equivalent world transform, via 3x3 matrix multiplication
rather than combining position/rotation/scale directly - this is
what lets Node2D.world_transform account for a rotated or scaled
parent's effect on a child's position.
copy()
#
Returns an independent copy of this transform.
from_matrix(mat)
classmethod
#
Decomposes a 3x3 affine matrix (as produced by to_matrix) back
into a Transform's position/rotation/scale.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the matrix's extracted scale is zero on either axis, since rotation can't be recovered from it then. |
neg()
#
Returns a new transform with position, rotation and scale all negated.
to_matrix()
#
Builds this transform's 3x3 2D affine matrix (column-vector
convention: [[cos*sx, -sin*sy, px], [sin*sx, cos*sy, py], [0, 0, 1]]),
used by compose_with/from_matrix for parent-child composition -
distinct from model, which builds a 4x4 matrix in the row-vector
convention the renderer expects.
Transform3(position, rotation, scale)
#
A 3D position/rotation/scale triple, with rotation a Vector3 of
Euler angles (degrees, applied Z then Y then X - see model).
position, rotation and scale are each coerced through
Vector3(...).
model
property
#
Builds this transform's 4x4 model matrix, as scale @ rotation @
translation (row-vector convention) so a locally-authored mesh is
scaled and rotated about its own origin before being placed in the
world - see the note below on why the factor order matters here.
position = Vector3(position)
instance-attribute
#
rotation = Vector3(rotation)
instance-attribute
#
scale = Vector3(scale)
instance-attribute
#
copy()
#
Returns an independent copy of this transform.
neg()
#
Returns a new transform with position, rotation and scale all negated.
Vector(x=0, y=None)
#
Vector()
Vector(x: float)
Vector(x: float, y: float)
Vector(x: Sequence[float])
Vector(x: Vector)
Bases: GenericVector
A 2D float vector, also used throughout the engine as a generic
(x, y) pair (e.g. sizes, UV coordinates). Constructible from separate
x/y values, a single scalar (broadcast to both axes), a 2-element
sequence, or another Vector - see the __init__ overloads.
Builds a vector from another Vector, a 2-element sequence, an
explicit (x, y) pair, or a single scalar broadcast to both axes
(Vector() defaults to (0, 0)).
magnitude
property
#
This vector's length.
normalized
property
#
This vector scaled to length 1, or (0, 0) if it's already the
zero vector (rather than raising a divide-by-zero error).
copy()
#
Returns an independent copy of this vector.
cross(other)
#
Returns the 2D cross product (the scalar z-component of the 3D
cross product), whose sign indicates whether other is clockwise
or counter-clockwise from this vector.
distance(to)
#
Returns the Euclidean distance between this point and to.
dot(other)
#
Returns the dot product of this vector and other.
from_angle(angle)
classmethod
#
Returns a unit vector pointing at angle radians.
perpendicular()
#
Returns this vector rotated 90 degrees counter-clockwise.
rotated(degrees)
#
Returns this vector rotated counter-clockwise by degrees around
the origin - for rotating a local offset (e.g. a joint anchor or a
polygon vertex) by a body's rotation into world space.
Vector3(x=0.0, y=None, z=None)
#
A 3D float vector.
Builds a vector from another Vector3, a 3-element list/tuple,
explicit (x, y, z) values, or a single scalar broadcast to all
three axes (Vector3() defaults to (0, 0, 0)).
magnitude
property
#
This vector's length.
normalized
property
#
This vector scaled to length 1, or (0, 0, 0) if it's already
the zero vector (rather than raising a divide-by-zero error).
x = x
instance-attribute
#
y = x
instance-attribute
#
z = x
instance-attribute
#
copy()
#
Returns an independent copy of this vector.
cross(other)
#
Returns the cross product of this vector and other.
dot(other)
#
Returns the dot product of this vector and other.
bezier_point(curve, t)
#
De Casteljau's algorithm to evaluate a Bezier curve.
clamp(min, value, max)
#
Restricts value to the [min, max] range.
clamp_vector(min, value, max)
#
Componentwise clamp(): clamps value's x and y independently
against min and max's corresponding components.
gaussian_random(rng, mean=0, standard_deveation=1)
#
Draws a single normally-distributed random value via the Box-Muller
transform, using rng instead of the random/numpy.random globals so
callers can get reproducible sequences from a seeded generator.
is_even(x)
#
Returns whether x is an even number.
simplify_fraction(numerator, denominator)
#
Reduces a fraction to lowest terms, normalizing the sign so a negative result always carries its sign on the numerator.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
vector_is_close(value1, value2, max)
#
Returns whether value1 and value2 are within max of each other
on both axes (math.isclose with abs_tol=max, applied per component).
vector_towards(start, to, magnitude)
#
Returns a vector pointing from start towards to, scaled to
magnitude rather than the actual distance between them.