Math Utilities Overview

Math Utilities Overview

The Math library provides vectors, matrices, shapes, and utilities for 3D game mathematics.

Package Location

com.hypixel.hytale.math

• Vectors: math.vector
• Matrices: math.matrix
• Shapes: math.shape
• Raycast: math.raycast
• Utilities: math.util
• Random: math.random
• Ranges: math.range
• Block math: math.block

Vector Classes

Vector3d (Double Precision)

The primary 3D vector class:

package com.hypixel.hytale.math.vector;

public class Vector3d {
    public double x, y, z;

    // Constructors
    public Vector3d();
    public Vector3d(double x, double y, double z);
    public Vector3d(Vector3d other);
    public Vector3d(Vector3i other);
    public Vector3d(float yaw, float pitch);  // From angles

    // Static constants
    public static final Vector3d ZERO;
    public static final Vector3d UP;
    public static final Vector3d DOWN;
    public static final Vector3d FORWARD;
    public static final Vector3d BACKWARD;
    public static final Vector3d LEFT;
    public static final Vector3d RIGHT;

    // Arithmetic (mutating)
    public Vector3d add(Vector3d other);
    public Vector3d add(double x, double y, double z);
    public Vector3d subtract(Vector3d other);
    public Vector3d scale(double scalar);
    public Vector3d negate();
    public Vector3d addScaled(Vector3d other, double scalar);

    // Vector operations
    public double dot(Vector3d other);
    public Vector3d cross(Vector3d other);
    public double length();
    public double squaredLength();
    public Vector3d normalize();
    public Vector3d setLength(double length);
    public Vector3d clampLength(double maxLength);

    // Distance
    public double distanceTo(Vector3d other);
    public double distanceSquaredTo(Vector3d other);

    // Rotation
    public Vector3d rotateX(double angle);
    public Vector3d rotateY(double angle);
    public Vector3d rotateZ(double angle);

    // Utilities
    public Vector3d floor();
    public Vector3d ceil();
    public boolean isFinite();

    // Static utilities
    public static Vector3d lerp(Vector3d from, Vector3d to, double t);
    public static Vector3d lerpUnclamped(Vector3d from, Vector3d to, double t);
    public static Vector3d directionTo(Vector3d from, Vector3d to);
    public static Vector3d max(Vector3d a, Vector3d b);
    public static Vector3d min(Vector3d a, Vector3d b);

    // Static distance (no object allocation)
    public static double distance(double x1, double y1, double z1, double x2, double y2, double z2);
    public static double distanceSquared(double x1, double y1, double z1, double x2, double y2, double z2);

    // Conversion
    public Vector3i toVector3i();
    public Vector3f toVector3f();
}

New in Update 3

Vector3d.distance() and Vector3d.distanceSquared() static methods were added for computing distances between two points without creating Vector3d objects. Box.ZERO was added as a convenience constant for a zero-sized box at the origin. Refer to the Update 3 changelog for the complete list of changes.

Vector3i (Integer)

Integer-precision 3D vector:

public class Vector3i {
    public int x, y, z;

    // Same operations as Vector3d but with integer precision

    public Vector3d toVector3d();
    public Vector3f toVector3f();
}

Vector3f (Float with Rotation)

Float-precision vector with rotation support:

public class Vector3f {
    public float x, y, z;

    // Rotation accessors (x=pitch, y=yaw, z=roll)
    public float getPitch();  // Returns x
    public float getYaw();    // Returns y
    public float getRoll();   // Returns z
    public void setPitch(float pitch);
    public void setYaw(float yaw);
    public void setRoll(float roll);

    // Rotation operations
    public Vector3f addRotationOnAxis(Axis axis, int angle);
    public Vector3f flipRotationOnAxis(Axis axis);
    public void lookAt(Vector3d direction);
    public static Vector3f lerpAngle(Vector3f from, Vector3f to, float t);

    public Vector3d toVector3d();
}

Vector2d / Vector2i

2D vector variants:

public class Vector2d {
    public double x, y;
    // Similar operations to Vector3d
}

public class Vector2i {
    public int x, y;
}

Vector4d (Homogeneous)

4D vector for matrix transforms:

public class Vector4d {
    public double x, y, z, w;

    // Factory methods
    public static Vector4d newPosition(double x, double y, double z);  // w=1
    public static Vector4d newDirection(double x, double y, double z); // w=0
}

Matrix Classes

Matrix4d (4x4 Matrix)

package com.hypixel.hytale.math.matrix;

public class Matrix4d {
    // Column-major storage (16 doubles)

    // Index constants: M00, M10, M20, M30, M01, M11...

    // Basic operations
    public double get(int index);
    public double get(int col, int row);
    public void set(int index, double value);
    public Matrix4d identity();
    public Matrix4d assign(Matrix4d other);

    // Transformations
    public Matrix4d translate(double x, double y, double z);
    public Matrix4d translate(Vector3d offset);
    public Matrix4d scale(double x, double y, double z);
    public Matrix4d rotateAxis(double angle, double x, double y, double z, Matrix4d tmp);
    public Matrix4d rotateEuler(double x, double y, double z, Matrix4d tmp);

    // Apply to vectors
    public Vector3d multiplyPosition(Vector3d position);  // With translation
    public Vector3d multiplyDirection(Vector3d direction); // Without translation
    public Vector4d multiply(Vector4d vector);
    public Matrix4d multiply(Matrix4d other);

    // Inversion
    public boolean invert();

    // Projection
    public Matrix4d projectionOrtho(double left, double right,
                                    double bottom, double top,
                                    double near, double far);
    public Matrix4d projectionFrustum(double left, double right,
                                      double bottom, double top,
                                      double near, double far);
    public Matrix4d projectionCone(double fov, double aspect,
                                   double near, double far);

    // View
    public Matrix4d viewTarget(double eyeX, double eyeY, double eyeZ,
                               double centerX, double centerY, double centerZ,
                               double upX, double upY, double upZ);
    public Matrix4d viewDirection(double eyeX, double eyeY, double eyeZ,
                                  double dirX, double dirY, double dirZ,
                                  double upX, double upY, double upZ);

    // Conversion
    public double[] getData();
    public float[] asFloatData();
}

Location and Transform

Location

Position + rotation + world:

package com.hypixel.hytale.math.vector;

public class Location {
    public Location(Vector3d position, Vector3f rotation, String worldName);

    public Vector3d getPosition();
    public void setPosition(Vector3d position);
    public Vector3f getRotation();
    public void setRotation(Vector3f rotation);
    public String getWorldName();

    public Vector3d getDirection();     // Direction from rotation
    public Vector3i getAxisDirection(); // Rounded direction
    public Axis getAxis();              // Cardinal axis

    public Transform toTransform();
}

Transform

Position + rotation (no world):

public class Transform {
    // Relative transform flags
    public static final int X_IS_RELATIVE;
    public static final int Y_IS_RELATIVE;
    public static final int Z_IS_RELATIVE;
    public static final int YAW_IS_RELATIVE;
    public static final int PITCH_IS_RELATIVE;
    public static final int ROLL_IS_RELATIVE;
    public static final int RELATIVE_TO_BLOCK;

    public Vector3d getPosition();
    public void setPosition(Vector3d position);
    public Vector3f getRotation();
    public void setRotation(Vector3f rotation);

    public static Vector3d getDirection(float pitch, float yaw);

    public void applyMaskedRelativeTransform(Transform base, int mask);
    public Transform clone();
}

Shape Classes

Box (AABB)

Axis-aligned bounding box:

package com.hypixel.hytale.math.shape;

public class Box {
    public static final Box ZERO = new Box(Vector3d.ZERO, Vector3d.ZERO);

    public Vector3d min;
    public Vector3d max;

    // Factory methods
    public static Box horizontallyCentered(double width, double height, double depth);
    public static Box cube(Vector3d min, double side);
    public static Box centeredCube(Vector3d center, double inradius);

    // Dimensions
    public double width();   // maxX - minX
    public double height();  // maxY - minY
    public double depth();   // maxZ - minZ

    // Operations
    public void setMinMax(Vector3d min, Vector3d max);
    public void setEmpty();

    public boolean intersects(Box other);
    public boolean contains(Vector3d point);
    public boolean contains(Box other);

    public Box expand(double x, double y, double z);
    public Box shrink(double x, double y, double z);
    public Box offset(double x, double y, double z);
    public Box offset(Vector3d offset);

    public Vector3d getCenter();
    public Vector3d getSize();
}

Other Shapes

Class	Description
Box2D	2D bounding box
Rectangle	2D rectangle
Cylinder	3D cylinder
Ellipsoid	3D ellipsoid
Triangle2d	2D triangle
Quad2d	2D quad

Raycast

RaycastAABB

package com.hypixel.hytale.math.raycast;

public class RaycastAABB {
    // Returns t parameter of intersection (negative if no hit)
    public static double intersect(
        double minX, double minY, double minZ,
        double maxX, double maxY, double maxZ,
        double originX, double originY, double originZ,
        double dirX, double dirY, double dirZ
    );

    // With callback for hit info
    public static double intersect(
        double minX, double minY, double minZ,
        double maxX, double maxY, double maxZ,
        double originX, double originY, double originZ,
        double dirX, double dirY, double dirZ,
        RaycastConsumer consumer
    );
}

public interface RaycastConsumer {
    void accept(boolean hit,
                double ox, double oy, double oz,  // Origin
                double dx, double dy, double dz,  // Direction
                double t,                          // Parameter
                double nx, double ny, double nz); // Normal
}

Utilities

MathUtil

package com.hypixel.hytale.math.util;

public class MathUtil {
    public static final double EPSILON_DOUBLE;
    public static final float EPSILON_FLOAT;

    // fast math
    public static int abs(int value);       // branchless
    public static int floor(double value);
    public static int ceil(double value);
    public static int fastFloor(float value);
    public static long fastFloor(double value);
    public static int fastCeil(float value);
    public static long fastCeil(double value);
    public static int fastRound(float value);
    public static long fastRound(double value);

    // clamping
    public static double clamp(double value, double min, double max);
    public static float clamp(float value, float min, float max);
    public static int clamp(int value, int min, int max);
    public static long clamp(long value, long min, long max);

    // range checking
    public static boolean within(double value, double min, double max);
    public static boolean closeToZero(double value);
    public static boolean closeToZero(float value);
    public static double clipToZero(double value);
    public static float clipToZero(float value);

    // interpolation
    public static double lerp(double from, double to, double t);
    public static float lerp(float from, float to, float t);
    public static double lerpUnclamped(double from, double to, double t);
    public static float lerpUnclamped(float from, float to, float t);
    public static float lerpAngle(float from, float to, float t);

    // angle utilities
    public static float wrapAngle(float angle);

    // rounding
    public static double round(double value, int precision);

    // vector length
    public static double length(double x, double y, double z);
    public static double length(double x, double y);
    public static double lengthSquared(double x, double y, double z);
    public static double lengthSquared(double x, double y);

    // int packing
    public static int packInt(int x, int z);
    public static int unpackLeft(int packed);
    public static int unpackRight(int packed);
    public static long packLong(int left, int right);

    // rotation
    public static Vector3i rotateVectorYAxis(Vector3i vector, int angle, boolean clockwise);
    public static Vector3d rotateVectorYAxis(Vector3d vector, int angle, boolean clockwise);

    // mapping
    public static float mapToRange(float value, float valueMin, float valueMax,
                                   float rangeMin, float rangeMax);
}

TrigMathUtil

Optimized trigonometry:

package com.hypixel.hytale.math.util;

public class TrigMathUtil {
    public static final float PI;
    public static final float PI_HALF;
    public static final float PI_QUARTER;
    public static final float PI2;
    public static final float PI4;
    public static final float radToDeg;
    public static final float degToRad;

    // lookup table trigonometry (fast, uses Riven's tables)
    public static float sin(float radians);
    public static float cos(float radians);
    public static float sin(double radians);   // casts to float internally
    public static float cos(double radians);   // casts to float internally

    // inverse trig (uses Icecore's lookup table)
    public static float atan2(float y, float x);
    public static float atan2(double y, double x);
    public static float atan(double value);
    public static float asin(double value);
}

RandomExtra

All methods use ThreadLocalRandom internally — no Random parameter needed.

package com.hypixel.hytale.math.random;

public final class RandomExtra {
    // basic random
    public static double randomBinomial();                          // [-1, 1]
    public static boolean randomBoolean();

    // range overloads
    public static double randomRange(double from, double to);
    public static double randomRange(double[] range);               // [0]=from, [1]=to
    public static float randomRange(float from, float to);
    public static float randomRange(float[] range);
    public static int randomRange(int bound);                       // [0, bound)
    public static int randomRange(int from, int to);                // inclusive
    public static int randomRange(int[] range);
    public static long randomRange(long from, long to);

    // collections
    public static <T> T randomElement(List<T> list);
    public static Duration randomDuration(Duration from, Duration to);
    public static Vector3d jitter(Vector3d vec, double maxRange);   // mutates and returns

    // weighted selection
    public static <T> T randomWeightedElement(Collection<T> elements,
                                              ToDoubleFunction<T> weight);
    public static <T> T randomIntWeightedElement(Collection<T> elements,
                                                 ToIntFunction<T> weight);
    public static int pickWeightedIndex(double[] weights);

    // reservoir sampling
    public static <T> void reservoirSample(List<T> input, Predicate<T> matcher,
                                           int count, List<T> picked);
}

Ranges

Useful for data-driven configs where you want a min/max pair.

IntRange

package com.hypixel.hytale.math.range;

public class IntRange {
    public IntRange(int inclusiveMin, int inclusiveMax);

    public int getInclusiveMin();
    public int getInclusiveMax();
    public void setInclusiveMin(int inclusiveMin);
    public void setInclusiveMax(int inclusiveMax);

    public int getInt(float factor);    // map [0,1] factor to range
    public int getInt(double factor);
    public boolean includes(int value);
}

FloatRange

package com.hypixel.hytale.math.range;

public class FloatRange {
    public FloatRange(float inclusiveMin, float inclusiveMax);

    public float getInclusiveMin();
    public float getInclusiveMax();
    public void setInclusiveMin(float inclusiveMin);
    public void setInclusiveMax(float inclusiveMax);

    public float getFloat(float factor);
    public float getFloat(double factor);
    public boolean includes(float value);
}

Block Utilities

BlockUtil

Packs/unpacks block positions into a single long. Useful for storing block coordinates in maps or sets without allocating Vector3i objects.

package com.hypixel.hytale.math.block;

public class BlockUtil {
    public static final long MAX_Y = 512L;
    public static final long MIN_Y = -513L;
    public static final long MAX = 67108864L;
    public static final long MIN = -67108865L;

    public static long pack(Vector3i val);
    public static long pack(int x, int y, int z);
    public static long packUnchecked(int x, int y, int z);

    public static int unpackX(long packed);
    public static int unpackY(long packed);
    public static int unpackZ(long packed);
    public static Vector3i unpack(long packed);
}

Block Shape Utilities

The math.block package has helpers that iterate blocks in geometric shapes. Each takes an origin, dimensions, and a TriIntObjPredicate<T> consumer that receives (x, y, z, context) and returns false to stop early.

Class	Description
BlockSphereUtil	Iterate blocks in a sphere (supports per-axis radii and shell thickness)
BlockCubeUtil	Iterate blocks in a cube
BlockCylinderUtil	Iterate blocks in a cylinder
BlockConeUtil	Iterate blocks in a cone
BlockDomeUtil	Iterate blocks in a dome
BlockInvertedDomeUtil	Iterate blocks in an inverted dome
BlockDiamondUtil	Iterate blocks in a diamond shape
BlockPyramidUtil	Iterate blocks in a pyramid
BlockTorusUtil	Iterate blocks in a torus

Block Iterators

package com.hypixel.hytale.math.iterator;

// Iterate blocks along a line
public class LineIterator { }

// Iterate blocks in a circle
public class CircleIterator { }

// Spiral iteration pattern
public class SpiralIterator { }

// Iterate blocks in a box
public class BoxBlockIterator { }

FastRandom

A lightweight Random subclass that skips synchronization for better performance. Does not support nextGaussian().

package com.hypixel.hytale.math.util;

public class FastRandom extends Random {
    public FastRandom();
    public FastRandom(long seed);
    public void setSeed(long seed);
}

Usage Examples

Basic Vector Operations

import com.hypixel.hytale.math.vector.Vector3d;

// Create vectors
Vector3d position = new Vector3d(10, 5, 20);
Vector3d direction = new Vector3d(1, 0, 0);

// Arithmetic
Vector3d moved = position.add(direction.scale(5));

// Distance
double dist = position.distanceTo(moved);

// Normalize
Vector3d normalized = direction.normalize();

// Interpolation
Vector3d midpoint = Vector3d.lerp(position, moved, 0.5);

Matrix Transformations

import com.hypixel.hytale.math.matrix.Matrix4d;
import com.hypixel.hytale.math.vector.Vector3d;

// Create transformation matrix
Matrix4d transform = new Matrix4d();
transform.identity();
transform.translate(10, 0, 0);
transform.rotateAxis(Math.PI / 4, 0, 1, 0, new Matrix4d());
transform.scale(2, 2, 2);

// Apply to position
Vector3d position = new Vector3d(0, 0, 0);
Vector3d transformed = transform.multiplyPosition(position);

Raycast

import com.hypixel.hytale.math.raycast.RaycastAABB;

// Check ray-box intersection
double t = RaycastAABB.intersect(
    0, 0, 0,    // Box min
    1, 1, 1,    // Box max
    -2, 0.5, 0.5, // Ray origin
    1, 0, 0     // Ray direction
);

if (t >= 0) {
    // Hit at distance t
    Vector3d hitPoint = origin.add(direction.scale(t));
}

Related

• Physics System - Uses math for physics
• Collision System - Box collision
• Entity System - Transform components