final class Vec3(x: int | float = 0, y: int | float = 0, z: int | float = 0)

Vec3 is an immutable 3-dimensional vector for representing x, y and z coordinates. As instances of this class are immutable, calculations yield new instances of Vec3 instead of changing the x, y and z values directly.

v = Vec3(1, 4, 8)
assert v.x == 1 and v.y == 4 and v.z == 8
# do NOT assign to x, y and z directly, Vec3 is immutable!
# instead use withX/withY/withZ or addX/east, addY/up and addZ/south or other methods to create new instances
assert v.east().south(5) == Vec3(2, 4, 13)
assert v.addX(-1).withY(0) - Vec3(z=8) == Vec3()  # Vec3() == Vec3(0, 0, 0)

ZEROS: Vec3 = Vec3(x=0, y=0, z=0)

Vec3(0, 0, 0)

ONES: Vec3 = Vec3(x=1, y=1, z=1)

Vec3(1, 1, 1)

ORIGIN: Vec3 = Vec3(x=0, y=0, z=0)

Vec3(0, 0, 0)

EAST: Vec3 = Vec3(x=1, y=0, z=0)

Vec3(1, 0, 0)

WEST: Vec3 = Vec3(x=-1, y=0, z=0)

Vec3(-1, 0, 0)

UP: Vec3 = Vec3(x=0, y=1, z=0)

Vec3(0, 1, 0)

DOWN: Vec3 = Vec3(x=0, y=-1, z=0)

Vec3(0, -1, 0)

SOUTH: Vec3 = Vec3(x=0, y=0, z=1)

Vec3(1, 0, 0)

NORTH: Vec3 = Vec3(x=0, y=0, z=-1)

Vec3(-1, 0, 0)

property x

property y

property z

classmethod from_yaw_pitch(yaw: int | float = 0, pitch: int | float = 0) → Vec3

Build direction unit-vector from yaw and pitch values. This translate the in-Minecraft yaw and pitch values of entities or players (in which direction they are looking) into directional unit-vectors.

• yaw: -180..179.99 (-180/180 north, -90 east, 0 south, 90 west)

• pitch: -90..90 (-90 up, 0 straight, 90 down)

yaw_pitch() → tuple[float, float]

The yaw and pitch values from self as directional vector. This translates directional unit-vectors into in-Minecraft yaw and pitch values used by entities or players (in which direction they are looking).

• yaw: -180..179.99 (-180 north, -90 east, 0 south, 90 west)

• pitch: -90..90 (-90 up, 0 straight, 90 down)

__add__(v: Vec3 | int | float) → Vec3

Vector addition or add scalar to x, y and z

__sub__(v: Vec3 | int | float) → Vec3

Vector subtraction or subtract scalar from x, y and z

__mul__(v: Vec3 | int | float) → Vec3

Scalar multiplication if v is a number or equivalent to multiply_elementwise() otherwise

__truediv__(v: int | float) → Vec3

Equivalent to multiplying x, y and z with 1.0 / v

distance(v: Vec3) → float

The distance between self and another point-vector v

length() → float

The length/magnitude of vector self, equivalent to abs(self)

norm() → Vec3

self as a normalized unit-vector with length 1

scale(factor: int | float) → Vec3

self scaled by factor factor, equivalent to self * factor

with_length(length: int | float) → Vec3

A vector with the same direction as self scaled to length length

angle(v: Vec3) → float

Get the angle between self and v in degrees (0 <= theta <= 180)

angle_rad(v: Vec3) → float

Get the angle between self and v in radians (0 <= theta <= pi)

dot(v: Vec3) → float

The dot product between self and v, equivalent to self ^ v

cross(v: Vec3) → Vec3

The cross product between self and v, equivalent to self @ v

multiply_elementwise(v: Vec3) → Vec3

The element-wise multiplicated vector of self and v, equivalent to self * v

map(func: Callable[[int | float], int | float]) → Vec3

A vector with func applied to x, y and z of self as arguments

map_pairwise(func: Callable[[int | float, int | float], int | float], v: Vec3) → Vec3

A vector with func applied to each x, y and z of both self and v as arguments

map_nwise(func: Callable[[...], int | float], *vectors: Vec3) → Vec3

A vector with func applied to each x, y and z of self and all other vectors as arguments

max(*vectors: Vec3) → Vec3

A vector that is the component-wise maximum of self and the other vectors

min(*vectors: Vec3) → Vec3

A vector that is the component-wise minimum of self and the other vectors

rotate(v: Vec3, degree: float) → Vec3

Rotate self around vector v by degree degrees

rotate_rad(v: Vec3, phi: float) → Vec3

Rotate self around vector v by phi degree radians - Rodrigues rotation

round(ndigits: int = 0) → Vec3

Round x, y and z to the ndigits comma digit

floor() → Vec3

Round x, y and z down to the nearest integer

ceil() → Vec3

Round x, y and z up to the nearest integer

trunc() → Vec3

Leave only the integer part of x, y and z

asdict() → dict[str, int | float]

Deprecated: Use to_dict() instead

to_dict() → dict[str, int | float]

x, y and z in a dictionary

to_tuple() → tuple[int | float]

x, y and z in a tuple

is_close(v: Vec3, *, rel_tol: float = 1e-09, abs_tol: float = 0.0) → bool

Whether all components of self and v are approximately equal

closest_axis() → Vec3

A vector with only the longest (most significant) axis remaining

direction_label() → Literal['east', 'south', 'west', 'north', 'up', 'down']

The direction of the longest (most significant) axis

cardinal_label() → Literal['east', 'south', 'west', 'north']

The direction of the longest (most significant) cardinal axis

clamp(min_v: Vec3, max_v: Vec3) → Vec3

The vector self with clamped x, y and z between the corresponding components of min_val and max_val

in_box(corner1: Vec3, corner2: Vec3) → bool

Whether self is enclosed in the bounding box/cube spanned between corner1 and corner2, both corners inclusive

east(n: int | float = 1) → Vec3

Equivalent to self.addX(n)

west(n: int | float = 1) → Vec3

Equivalent to self.addX(-n)

up(n: int | float = 1) → Vec3

Equivalent to self.addY(n)

down(n: int | float = 1) → Vec3

Equivalent to self.addY(-n)

south(n: int | float = 1) → Vec3

Equivalent to self.addZ(n)

north(n: int | float = 1) → Vec3

Equivalent to self.addZ(-n)

add() → Vec3

add(scalar: int | float) → Vec3

add(vector: Vec3) → Vec3

add(x: int | float, y: int | float, z: int | float) → Vec3

add(*, x: int | float | None = None, y: int | float | None = None, z: int | float | None = None) → Vec3

self with added scalar, another vector, or explicit component-wise values. Supports: * add() will add 1 to all components * add(scalar) will add scalar to all components * add(Vec3) * add(x, y, z) * add(x=1, y=2, z=3) with optional partials (missing parts default to 0)

addX(n: int | float = 1) → Vec3

self with n added to x, equivalent to self + Vec3(n, 0, 0)

addY(n: int | float = 1) → Vec3

self with n added to y, equivalent to self + Vec3(0, n, 0)

addZ(n: int | float = 1) → Vec3

self with n added to z, equivalent to self + Vec3(0, 0, n)

addXY(n: int | float = 1) → Vec3

self with n added to x and y, equivalent to self + Vec3(n, n, 0)

addXZ(n: int | float = 1) → Vec3

self with n added to x and z, equivalent to self + Vec3(n, 0, n)

addYZ(n: int | float = 1) → Vec3

self with n added to y and z, equivalent to self + Vec3(0, n, n)

withX(n: int | float) → Vec3

self with x replaced with n, equivalent to Vec3(n, self.y, self.z)

withY(n: int | float) → Vec3

self with y replaced with n, equivalent to Vec3(self.x, n, self.z)

withZ(n: int | float) → Vec3

self with z replaced with n, equivalent to Vec3(self.x, self.y, n)

withXY(n: int | float) → Vec3

self with x and y replaced with n, equivalent to Vec3(n, n, self.z)

withXZ(n: int | float) → Vec3

self with x and z replaced with n, equivalent to Vec3(n, self.y, n)

withYZ(n: int | float) → Vec3

self with y and z replaced with n, equivalent to Vec3(self.x, n, n)