gmath

This package contains all of the most important math functions used for game development purposes. It provides a comprehensive library of mathematical primitives and utilities. Contains linear algebra, geometry and random number generation.

Features:

• Linear algebra: Robust support for vectors (Vector2/Int -> Vector4/Int) and matrices (Matrix4) including the most important operations like dot, normalize, direction.
• Geometry: Contains tools for manipulating shapes, including Rectangle and Circle. Allows to position, scale, pivot, and check collision between shapes.
• Randomness: Utilities for generating random numbers (randomRange), normalized floats (randomFloatNormalized) and picking random array elements via randomElement.
• Math utilities: Essential game math functions including lerp, ease, remap and clamp.
• Color handling: Helpers to convert hex strings or values into Color structs (hexToColor). Contains generic color constants in bonsai:core/gmath/colors.

Usage

update :: proc() {
  direction := gmath.direction(enemy.position, pot.position)
  enemy.position += direction * enemy.speed * deltaTime

  if gmath.rectangleIntersects(pot.collider, enemy.collider) {
    potDead()
  }

  spawnPosition := gmath.randomCircleNormalized() * spawnRange
  // ...
}

---

Circle

Circle :: struct  {
  position: Vector2,
  radius:   f32,
}

A Circle defined by a center position and a radius.

---

Color

Color :: Vector4

Color is an alias for a standard 4D Float Vector.

---

E

E :: math.E

Constant e value. Approximately 2.718281828.

---

Easing

Easing :: enum  {
  Linear,
  InSine,
  OutSine,
  InOutSine,
  InQuad,
  OutQuad,
  InOutQuad,
  InCubic,
  OutCubic,
  InOutCubic,
  InQuart,
  OutQuart,
  InOutQuart,
  InQuint,
  OutQuint,
  InOutQuint,
  InExpo,
  OutExpo,
  InOutExpo,
  InCirc,
  OutCirc,
  InOutCirc,
  InBack,
  OutBack,
  InOutBack,
  InElastic,
  OutElastic,
  InOutElastic,
  InBounce,
  OutBounce,
  InOutBounce,
}

Standard easing functions matching https://easings.net

---

Matrix4

Matrix4 :: linalg.Matrix4f32

4x4 Float Matrix (Column-Major).

---

PI

PI :: math.PI

Constant π value.

---

Pivot

Pivot :: enum  {
  bottomLeft,
  bottomCenter,
  bottomRight,
  centerLeft,
  centerCenter,
  centerRight,
  topLeft,
  topCenter,
  topRight,
}

Enum representing the 9 cardinal points of a rectangle.

Note

Used for anchoring UI and aligning sprites.

---

Rectangle

Rectangle :: Vector4

An Axis-Aligned Bounding Box (AABB) stored as a Vector4. Format: { minX, minY, maxX, maxY } This corresponds to (Left, Bottom, Right, Top).

---

TAU

TAU :: math.TAU

Constant τ value. Equal to 2π.

---

Vector2

Vector2 :: linalg.Vector2f32

Standard 2D Float Vector (compatible with Odin’s core:math/linalg package)

---

Vector2Int

Vector2Int :: [2]i32

2D Integer Vector (32-bit).

Tip

Useful for grid coordinates.

---

Vector3

Vector3 :: linalg.Vector3f32

Standard 3D Float Vector.

---

Vector3Int

Vector3Int :: [3]i32

3D Integer Vector (32-bit).

---

Vector4

Vector4 :: linalg.Vector4f32

Standard 4D Float Vector.

---

Vector4Int

Vector4Int :: [4]i32

4D Integer Vector (32-bit).

---

abs

abs :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the absolute value of input.

• For scalars: Returns the non-negative value.
• For vectors: Returns a new vector where every component is positive.

Example

direction := gmath.Vector2{-1, -1}
result := gmath.abs(direction) // result is gmath.Vector2{1, 1}

---

almostEquals

almostEquals :: proc (
  a, b: $T,
  epsilon: $E,
) -> bool where (intrinsics.type_is_float(T) || intrinsics.type_is_integer(T)) &&
  intrinsics.type_is_float(E)

Checks if two floats are equal within a small margin of error (epsilon).

---

angleToVector

angleToVector :: proc (
  radians: $T,
) -> Vector2 where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns a normalized direction vector from an angle (in radians).

---

atan2

atan2 :: proc (y, x: $T) -> T where intrinsics.type_is_float(T) || intrinsics.type_is_integer(T)

Returns the angle in radians between the x-axis and the ray from {0,0} to {y,x}.

Tip

Crucial for rotation: To make an object at position look at target, use:

angle := gmath.atan2(target.y - position.y, target.x - position.x)

---

ceil

ceil :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the smallest whole number greater than or equal to the input. Accepts scalar and vector values as an argument.

---

clamp

clamp :: proc (
  input: $T,
  minimum, maximum: $E,
) -> T where (intrinsics.type_is_array(T) &&
    (intrinsics.type_is_array(E) ||
        intrinsics.type_is_float(E) ||
        intrinsics.type_is_integer(E))) ||
  ((intrinsics.type_is_float(T) || intrinsics.type_is_integer(T)) &&
      (intrinsics.type_is_float(E) || intrinsics.type_is_integer(E)))

Clamps input between minimum and maximum.

---

cos

cos :: proc (
  angle: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the cosine of angle (in radians).

• For scalars: Standard trigonometric cos function.
• For vectors: Component-wise cosine.

Example

wave := gmath.Vector2{ 0, gmath.PI / 2 }
result := gmath.cos(wave) // result is gmath.Vector2{ 1, 0 }

---

direction

direction :: proc (start, end: $T) -> T where intrinsics.type_is_array(T)

Returns a normalized direction vector pointing from start to end.

Example

start := gmath.Vector2{4, 0}
end := gmath.Vector2{4, -9}
dir := gmath.direction(start, end) // dir is gmath.Vector2{0, -1}

---

distance

distance :: proc (
  a, b: [$N]$T,
) -> T where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the distance between points a and b.

Example

pointA := gmath.Vector2{3, 0}
pointB := gmath.Vector2{3, 4}
dist := gmath.distance(pointA, pointB) // dist is 4

---

dot

dot :: proc (a, b: [$N]$T) -> T where intrinsics.type_is_float(T) || intrinsics.type_is_integer(T)

Returns the dot product between two vectors.

Example

directionA := gmath.Vector2{1, 1}
directionB := gmath.Vector2{-1, 1}
product := gmath.dot(directionA, directionB)

---

ease

ease :: proc (name: Easing, t: f32) -> f32

Applies the specified easing curve to a normalized value (0.0 to 1.0).

---

exp

exp :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns e raised to the power of input.

---

floor

floor :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the largest whole number less than or equal to the input. Accepts scalar and vector values as an argument.

---

getRandomSeed

getRandomSeed :: proc () -> u64

Returns the current seed used by the random number generator.

---

getRectangleCenter

getRectangleCenter :: proc (rectangle: Rectangle) -> Vector2

Returns the center point of the Rectangle.

---

getRectanglePivot

getRectanglePivot :: proc (rectangle: Rectangle, pivot: Pivot) -> Vector2

Helper to get a position within a Rectangle using a Pivot enum.

Tip

Especially useful when working with collisions and UI elements.

---

getRectangleSize

getRectangleSize :: proc (rectangle: Rectangle) -> Vector2

Returns the width and height of the Rectangle as a Vector2.

---

hexToColor

hexToColor :: proc (value: u32) -> Color

Converts a packed 32-bit integer (0xRRGGBBAA) into a normalized Color. Extracts bytes and divides by 255.0 to map to the 0.0-1.0 range.

---

length

length :: proc (
  input: [$N]$T,
) -> T where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the length (magnitude) of the vector input.

Example

point := gmath.Vector2{2, 2}
pointLength := gmath.length(point) // Returns distance from {0, 0} = 4√2

---

lengthSquared

lengthSquared :: proc (
  input: [$N]$T,
) -> T where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the squared length of the vector input. Faster than length because it doesn’t use the square root operation.

Tip

Useful for distance comparisons.

Example

pointA := gmath.Vector2{100, 100}
pointB := gmath.Vector2{5, 5}
result := gmath.lengthSquared(pointA) > gmath.lengthSquared(pointB) // result is true

---

lerp

lerp :: proc (a, b: $T, t: $E) -> T

Linearly interpolates between a and b by the fraction t. Useful for smooth transitions, animations, or mixing colors. Accepts scalar arguments, as well as Vector2, Vector3, Vector4 and Color.

Note

The value of t is not clamped to the 0-1 range.

Example

start := gmath.Vector2{4, 4}
finish := gmath.Vector2{16, 16}
result := gmath.lerp(start, finish, 0.5) // result is gmath.Vector2{10, 10}

---

ln

ln :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the natural logarithm (base e) of input.

• For scalars: Standard natural logarithm.
• For vectors: Component-wise natural logarithm.

---

log

log :: proc (
  base: $T,
  input: T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the logarithm of input in the specified base

---

log10

log10 :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the base-10 logarithm of input.

---

matrixInverse

matrixInverse :: proc (mat: Matrix4) -> Matrix4

Returns the inverse of the 4x4 matrix. Useful for creating view matrices and converting world space to screen space.

Note

Matrix inversion is computationally expensive.

---

matrixOrtho3d

matrixOrtho3d :: proc (
  left, right, bottom, top, near, far: $T,
) -> Matrix4 where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Creates an orthographic projection matrix. This defines the viewing volume as a rectangular box. Objects inside this box are visible, objects outside are clipped.

---

matrixRotate

matrixRotate :: proc (rotation: Vector3) -> Matrix4

Creates a rotation matrix from a rotation Vector3.

Note

This function applies the multiplication in the following order:

X (pitch) -> Y (yaw) -> Z (roll).

---

matrixRotateX

matrixRotateX :: proc (radians: f32) -> Matrix4

Creates a rotation matrix (X-axis) from an angle in radians.

---

matrixRotateY

matrixRotateY :: proc (radians: f32) -> Matrix4

Creates a rotation matrix (Y-axis) from an angle in radians.

---

matrixRotateZ

matrixRotateZ :: proc (radians: f32) -> Matrix4

Creates a rotation matrix (Z-axis) from an angle in radians.

---

matrixScale

matrixScale :: proc (scale: Vector2) -> Matrix4

Creates a scaling matrix. Z-scale is locked to 1.0.

---

matrixTranslate

matrixTranslate :: proc (position: Vector2) -> Matrix4

Creates a translation matrix from a 2D position (Z is assumed to be 0).

---

max

max :: proc (
  a, b: $T,
  rest: ..T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the largest value among all arguments. If arguments are vectors, returns a component-wise maximum vector. Accepts any number of arguments (minimum 2).

Example

maximum := gmath.max(10, 30, 20) // maximum is 30
vectorMaximum := gmath.max(vectorA, vectorB) // vectorMaximum is a component-wise maximum vector

---

min

min :: proc (
  a, b: $T,
  rest: ..T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the smallest value among all arguments. If arguments are vectors, returns a component-wise minimum vector. Accepts any number of arguments (minimum 2).

Example

minimum := gmath.min(10, 5, 20) // minimum is 5
vectorMinimum := gmath.min(vectorA, vectorB) // vectorMinimum is a component-wise minimum vector

---

normalize

normalize :: proc (input: $T) -> T where intrinsics.type_is_array(T)

Returns the normalized direction of the vector input (with length of 1).

Returns {0, 0} if the input vector is zero to prevent nil errors.

Example

direction := gmath.Vector2{100, 0}
directionNormalized := gmath.normalize(direction) // directionNormalized is gmath.Vector2{1, 0}

---

pow

pow :: proc (
  base: $B,
  power: $P,
) -> B where (intrinsics.type_is_array(B) &&
    (intrinsics.type_is_array(P) ||
        intrinsics.type_is_float(P) ||
        intrinsics.type_is_integer(P))) ||
  ((intrinsics.type_is_float(B) || intrinsics.type_is_integer(B)) &&
        intrinsics.type_is_float(P) ||
      intrinsics.type_is_integer(P))

Returns the value of base raised to power. Accepts scalars, Vectors, and Color as an argument.

---

randomCircleNormalized

randomCircleNormalized :: proc () -> Vector2

Returns a random Vector2 point in a circle of radius 1.0.

---

randomElement

randomElement :: proc (list: []$T) -> (T, bool)

Returns a random element from a slice. Returns false if the slice is empty.

---

randomFloatNormalized

randomFloatNormalized :: proc () -> f32

Returns a random float between 0.0 and 1.0.

---

randomRange

randomRange :: proc (min: f32, max: f32) -> f32

Returns a random float between min and max.

---

randomRangeInt

randomRangeInt :: proc (min: int, max: int) -> int

Returns a random integer between min (inclusive) and max (inclusive).

---

rectangleContains

rectangleContains :: proc (rectangle: Rectangle, point: Vector2) -> bool

Checks if a point lies inside the Rectangle. Returns true if it does.

---

rectangleExpand

rectangleExpand :: proc {
  _rectangleExpandScalar,
  _rectangleExpandVector2,
}

Expands the Rectangle boundaries outwards by amount on all sides. A negative amount shrinks the Rectangle.

Accepts a scalar or Vector2 as an amount by which the rectangle is expanded.

Example

rectangle := gmath.rectangleMake(gmath.Vector2{10, 10}) // size is gmath.Vector2{10, 10}
rectangle = gmath.rectangleExpand(rectangle, gmath.Vector2{5, 5}) // size is gmath.Vector2{20, 20}

---

rectangleIntersects

rectangleIntersects :: proc (a: Rectangle, b: Rectangle) -> bool

Checks if two Axis-Aligned Bounding Boxes (AABB) intersect. Returns true if they overlap.

---

rectangleMake

rectangleMake :: proc {
  _rectangleFromPositionSize,
  _rectangleFromSize,
}

Overload group for creating a Rectangle. Accepts arguments:

• position as Vector2 (optional, default: gmath.Vector2{0, 0}).
• size as Vector2.
• pivot as Pivot (optional, default: gmath.Pivot.bottomLeft).

Example

sizeRectangle := gmath.rectangleMake(gmath.Vector2{10, 15}) // returns gmath.Rectangle{0, 0, 10, 15}
sizeAndPositionRectangle := gmath.rectangleMake(gmath.Vector2{5, 5}, gmath.Vector2{5, 7}) // returns gmath.Rectangle{5, 5, 10, 12}
pivotedRectangle := gmath.rectangleMake(gmath.Vector2{3, 3}, gmath.Vector2{2, 2}, .centerCenter) // returns gmath.Rectangle{2, 2, 4, 4}

---

rectangleScale

rectangleScale :: proc {
  _rectangleScaleScalar,
  _rectangleScaleVector2,
}

Scales a Rectangle around its own center point.

Accepts a scalar or Vector2 as a scale.

---

remap

remap :: proc (
  input, inMin, inMax, outMin, outMax: $T,
) -> T where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Remaps input from the [inMin, inMax] range to the [outMin, outMax] range.

Example

remapped := gmath.remap(50.0, 0.0, 100.0, 0.0, 1.0) // remapped is 0.5

---

rotatePoint

rotatePoint :: proc (point, pivot: Vector2, radians: f32) -> Vector2

Rotates a point around a pivot point by radians.

---

round

round :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Rounds the value to the nearest whole number. Accepts scalar and vector values as an argument.

---

roundToInt

roundToInt :: proc (input: [$N]$T) -> [N]int where intrinsics.type_is_float(T)

Rounds the float input vector to the nearest integer vector, changing its type.

Example

value := gmath.Vector3{5.1, 7.6, 6.9}
roundedValue := gmath.roundToInt(value) // roundedValue is gmath.Vector3Int{5, 8, 7}

---

scaleFromPivot

scaleFromPivot :: proc (pivot: Pivot) -> Vector2

Returns a normalized Vector2 (0.0 -> +1.0) corresponding to the Pivot enum.

Example

// pivotOffset is equal to gmath.Vector2{0.5, 0.5}
pivotOffset := gmath.scaleFromPivot(gmath.Pivot.centerCenter)

---

setRandomSeed

setRandomSeed :: proc (seed: u64)

Initializes the random number generator with a specific seed.

---

shift

shift :: proc {
  _circleShift,
  _rectangleShift,
}

Moves Circle or Rectangle by the delta vector.

Example

rectangle := gmath.rectangleMake(gmath.Vector2{5, 5}, gmath.Vector2{10, 10}) // position is gmath.Vector2{5, 5}
rectangle = gmath.shift(rectangle, gmath.Vector2{10, 10}) // position is gmath.Vector2{15, 15}

---

sign

sign :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns:

• +1, if input is greater than zero.
• 0, if input is equal to zero.
• -1, if input is smaller than zero. For vectors returns a component-wise sign vector.

---

sin

sin :: proc (
  angle: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Retuns the sine of angle (in radians).

• For scalars: Standard trigonometric sin function.
• For vectors: Component-wise sine.

Example

wave := gmath.Vector2{ -gmath.PI / 2, gmath.PI / 2 }
result := gmath.sin(wave) // result is gmath.Vector2{ -1, 1 }

---

sqrt

sqrt :: proc (
  input: $T,
) -> T where intrinsics.type_is_array(T) ||
  intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Returns the square root of input value. Works with Vectors, Matrices and scalars. If an integer is passed as an argument, it’s rounded on return.

---

stringHexToColor

stringHexToColor :: proc (hexString: string) -> Color

Parses a hex string (e.g. “#FF0000” or “FF0000FF”) into a normalized Color. Supports both 6-digit (assumes alpha = 1.0) and 8-digit formats. Handles optional leading ’#‘.

---

toDegrees

toDegrees :: proc (
  radians: $T,
) -> T where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Converts radians to degrees.

---

toRadians

toRadians :: proc (
  degrees: $T,
) -> T where intrinsics.type_is_float(T) ||
  intrinsics.type_is_integer(T)

Converts degrees to radians.

---

transformPoint

transformPoint :: proc (mat: Matrix4, point: Vector2) -> Vector2

Multiplies a vector by a matrix, effectively transforming the point. Assumes z = 0 and w = 1.

---

vectorToAngle

vectorToAngle :: atan2

An alias for the atan2 function.

---