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

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);

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

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);
    public Matrix4d rotateEuler(double x, double y, double z);

    // 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 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
Cone	3D cone
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); // Fast floor
    public static int ceil(double value);  // Fast ceil
    public static int fastFloor(double value);
    public static int fastCeil(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);

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

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

    // Angle utilities
    public static double wrapAngle(double angle); // Normalize to [-π, π]

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

    // Vector length
    public static double length(double x, double y, double z);
}

TrigMathUtil

Optimized trigonometry:

package com.hypixel.hytale.math.util;

public class TrigMathUtil {
    public static final double PI;
    public static final double PI_HALF;
    public static final double PI2;
    public static final double radToDeg;
    public static final double degToRad;

    // Lookup table trigonometry (fast)
    public static float sin(float angle);
    public static float cos(float angle);
    public static double sin(double angle);
    public static double cos(double angle);

    // Inverse trig
    public static float atan2(float y, float x);
    public static double atan2(double y, double x);
    public static double atan(double value);
    public static double asin(double value);
}

RandomExtra

package com.hypixel.hytale.math.random;

public class RandomExtra {
    public static double randomBinomial(Random random);  // [-1, 1]
    public static float randomRange(Random random, float min, float max);
    public static int randomRange(Random random, int min, int max);
    public static boolean randomBoolean(Random random);
    public static <T> T randomElement(Random random, List<T> list);
    public static Duration randomDuration(Random random, Duration min, Duration max);
    public static void jitter(Random random, Vector3d vector, double maxRange);
}

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 { }

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.rotateY(Math.PI / 4);
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