pocketpy/docs/modules/vmath.md

---

icon: package

label: vmath

vmath

Native vector, matrix, and color types for game scripts.

Type	Purpose
vec2(x, y), vec3(x, y, z)	Floating-point vectors.
vec2i(x, y), vec3i(x, y, z), vec4i(x, y, z, w)	Integer vectors.
mat3x3(...)	3 x 3 matrix, including 2D affine transforms.
color32(r, g, b, a)	Four 8-bit color channels, each from 0 to 255.

Vector components are read-only. Methods such as with_x() return a new value. Floating vectors use single-precision components, so allow for rounding when comparing calculated results.

Vector calculations

from vmath import vec2, vec2i

velocity = vec2(3, 4)
assert velocity.length() == 5.0
position = vec2(10, 20) + velocity * 2
assert position == vec2(16, 28)
assert velocity.with_x(0) == vec2(0, 4)

tile = vec2i(2, 3)
assert tile + vec2i(1, 0) == vec2i(3, 3)

Floating vectors provide dot(), length(), length_squared(), and normalize(). Multiplication by another vector is component-wise; use dot() for a dot product. Integer vectors provide integer arithmetic, dot products, and hashing. Vector components can be unpacked by iteration.

For 2D motion, vec2.rotate(radians), vec2.angle(from_vector, to_vector), and vec2.smooth_damp(...) are available. With a downward screen Y axis, positive rotation appears clockwise.

Matrices and colors

from vmath import mat3x3, vec2, color32

transform = mat3x3.trs(vec2(10, 20), 0.0, vec2(2, 2))
assert transform.transform_point(vec2(1, 1)) == vec2(12, 22)
assert transform.transform_vector(vec2(1, 1)) == vec2(2, 2)

red = color32(255, 0, 0, 255)
assert red.r == 255
assert red.with_a(128).a == 128

trs(translation, rotation, scale) constructs an affine transform. transform_point() includes translation; transform_vector() does not. Matrices support @, indexing by [row, column], determinant(), inverse(), copy(), and the in-place variants copy_/inverse_. A singular matrix has no inverse.

rgb(r, g, b) creates an opaque color. rgba(r, g, b, a) uses a float alpha in [0, 1], unlike color32's integer alpha. Colors also support hex conversion, RGB565 conversion, ANSI coloring, and alpha_blend().

Full signatures and type-specific methods: vmath.pyi.