Math Utilities

Math Utilities

Butterfly API includes several small math helpers for common modding calculations.

The main utility classes are:

• Angles
• Vecs
• Boxes
• Motion
• Sampling
• Scalars
• YawPitch

Angles

Use Angles for common yaw, pitch, and look-direction calculations.

Angle Difference

double yawDelta =
        Angles.deltaDegrees(
                entity.getYaw(),
                targetYaw
        );

Look Direction

Vec3d direction =
        Angles.lookDirection(entity);

Look At a Position

YawPitch look =
        Angles.lookAt(
                entity.getEyePos(),
                target.getEyePos()
        );

lookAt(...) returns a YawPitch value describing the rotation needed to look from one position toward another.

Vectors

Use Vecs for reusable vector operations.

Direction Between Two Points

Vec3d from =
        new Vec3d(
                entity.getX(),
                entity.getY(),
                entity.getZ()
        );

Vec3d to =
        target.getEyePos();

Vec3d towardTarget =
        Vecs.direction(
                from,
                to,
                Vec3d.ZERO
        );

Limit Vector Length

Vec3d capped =
        Vecs.limitLength(
                entity.getVelocity(),
                0.5D
        );

Reflect a Vector

Vec3d reflected =
        Vecs.reflect(
                incoming,
                surfaceNormal
        );

Bounding Boxes

Use Boxes for common Box calculations.

Box Around a Position

Box searchArea =
        Boxes.around(
                entity.getEyePos(),
                8.0D
        );

Box Between Two Points

Box beamArea =
        Boxes.between(
                start,
                end,
                0.25D
        );

Box Center

Vec3d center =
        Boxes.center(searchArea);

Motion

Use Motion for common entity and projectile movement operations.

Push Away From a Source

Motion.pushFrom(
        target,
        source,
        0.8D,
        0.2D
);

Pull Toward a Target

Motion.pullToward(
        projectile,
        target,
        0.4D,
        0.0D
);

Set Velocity From Look Direction

Motion.setVelocityFromLook(
        projectile,
        1.5D
);

Add Velocity Toward a Target

Motion.addVelocityToward(
        projectile,
        target,
        0.25D
);

Sampling

Sampling can generate collections of positions for effects such as particles.

Example circle:

for (Vec3d point : Sampling.circle(
        center,
        new Vec3d(0.0D, 1.0D, 0.0D),
        2.0D,
        16
)) {
    world.addParticle(
            particle,
            point.x,
            point.y,
            point.z,
            0.0D,
            0.0D,
            0.0D
    );
}

Scalars

Use Scalars for common number operations.

Clamp to 0–1

double progress =
        Scalars.clamp01(
                Scalars.inverseLerp(
                        value,
                        min,
                        max
                )
        );

Map Between Ranges

double mapped =
        Scalars.mapClamped(
                distance,
                0.0D,
                32.0D,
                1.0D,
                0.0D
        );

Approach a Target Value

double eased =
        Scalars.approach(
                current,
                target,
                step
        );

Related Pages

• Bootstrap Helpers
• Quick Start