Vec3D

com.jsmacrosce.jsmacros.api.math.Vec3D

Since1.2.6

A 3D line segment with mutable endpoints. Length and angle measurements include z.
Inherited Vec2D overloads still operate in 2D: add(Vec2D) and multiply(Vec2D) return a plain Vec2D, while dotProduct(Vec2D) and compareTo(Vec2D) ignore z.
The 3D arithmetic overloads return new segments; normalize() divides both endpoints by the magnitude, moving the start unless it is at the origin.

// Player.getPlayer() is null outside a world, so there is nothing to aim there
const player = Player.getPlayer();  
if (player !== null) {
  // a unit length segment from the origin along the direction the player looks in
  const look = PositionCommon.createLookingVector(player.getYaw(), player.getPitch());  
  // the same angles again, read back off the segment itself
  Chat.log(`looking yaw ${look.getYaw()}, pitch ${look.getPitch()}`);  
  // push the end of it five blocks out to get a point in the world
  const far = look.getEnd().scale(5);  
  Chat.log(`which lands on ${far}`);  
}

Constructors

new Vec3D

new Vec3D(double x1, double y1, double z1, double x2, double y2, double z2)Since1.2.6#

makes a segment from the coordinates of its two ends.

Parameters:

x1: the x coordinate of the start
y1: the y coordinate of the start
z1: the z coordinate of the start
x2: the x coordinate of the end
y2: the y coordinate of the end
z2: the z coordinate of the end

new Vec3D(Pos3D start, Pos3D end)Since1.2.6#

makes a segment running from one position to another.

Parameters:

start: the position the segment starts at
end: the position the segment ends at

new Vec3D(Vec3D vec)Since1.2.6#

copies another vector. The result is a separate object, so writing to it afterwards does not touch vec.

Parameters:

vec: the vector to copy

Fields

z1

z1: double#

The z coordinate of the segment's start.

z2

z2: double#

The z coordinate of the segment's end.

Methods

add

add(Vec3D vec): Vec3DSince1.2.6#

Returns a new segment with each endpoint coordinate added to the corresponding coordinate of vec; this segment is unchanged. A Vec2D argument instead selects the inherited 2D overload, which returns a Vec2D and ignores z.

Parameters:

vec: the segment whose endpoints are added to this one's

Returns: a new segment with every endpoint coordinate added to its matching one

add(double x1, double y1, double z1, double x2, double y2, double z2): Vec3DSince1.6.3#

Returns a new segment with its start offset by the first three amounts and its end by the last three. Equal offsets translate the segment; this segment is unchanged.

Parameters:

x1: the amount to add to the start's x coordinate
y1: the amount to add to the start's y coordinate
z1: the amount to add to the start's z coordinate
x2: the amount to add to the end's x coordinate
y2: the amount to add to the end's y coordinate
z2: the amount to add to the end's z coordinate

Returns: a new segment offset endpoint for endpoint

add(Vec2D vec): Vec2DSince1.2.6#

Returns a new segment with each endpoint coordinate increased by the corresponding coordinate of vec; this segment is unchanged.

Parameters:

vec: the segment whose endpoints are added to this one's

Returns: a new segment with x1 + vec.x1, y1 + vec.y1, x2 + vec.x2, y2 + vec.y2

add(double x1, double y1, double x2, double y2): Vec2DSince1.6.3#

Returns a new segment with its start and end offset independently by the corresponding amounts; this segment is unchanged.

Parameters:

x1: the amount to add to the start's x coordinate
y1: the amount to add to the start's y coordinate
x2: the amount to add to the end's x coordinate
y2: the amount to add to the end's y coordinate

Returns: a new segment offset endpoint for endpoint

addEnd

addEnd(Pos3D pos): Vec3DSince1.6.4#

Returns a new segment with its end offset by pos and its start unchanged. This segment is not modified.

Parameters:

pos: the position to move the end by

Returns: a new segment ending at the moved point and starting where this one did

addEnd(double x, double y, double z): Vec3DSince1.6.4#

Returns a new segment with its end offset by the given amounts and its start unchanged; this segment is not modified.

Parameters:

x: the amount to add to the end's x coordinate
y: the amount to add to the end's y coordinate
z: the amount to add to the end's z coordinate

Returns: a new segment ending at the moved point and starting where this one did

addStart

addStart(Pos3D pos): Vec3DSince1.6.4#

Returns a new segment with its start offset by pos and its end unchanged. This segment is not modified.

Parameters:

pos: the position to move the start by

Returns: a new segment starting at the moved point and ending where this one did

addStart(double x, double y, double z): Vec3DSince1.6.4#

Returns a new segment with its start offset by the given amounts and its end unchanged; this segment is not modified.

Parameters:

x: the amount to add to the start's x coordinate
y: the amount to add to the start's y coordinate
z: the amount to add to the start's z coordinate

Returns: a new segment starting at the moved point and ending where this one did

compareTo

compareTo(Vec3D o): intSince1.2.6#

Compares segments lexicographically by start position, then end position; each position is compared by x, y, then z using Pos3D.compareTo(Pos3D). This coordinate ordering does not compare segment lengths or whether they intersect.

Parameters:

o: the segment to compare this one against

Returns: a negative number, zero, or a positive number as this segment is before, the same as, or after o

compareTo(Vec2D other): intSince1.2.6#

Compares segments by start position, then by end position when their starts compare equal; each position is ordered by Pos2D.compareTo(Pos2D) (x, then y).

Parameters:

other: the segment to compare this one against

Returns: a negative number, zero, or a positive number as this segment is before, the same as, or after other

crossProduct

crossProduct(Vec3D vec): Vec3DSince1.2.6#

Returns the cross product of the endpoint differences as a segment from the origin. Its direction follows the right-hand rule from this segment toward vec; swapping the arguments negates it. Parallel directions produce a zero vector. The result is not normalized.

Parameters:

vec: the other segment to take the perpendicular to

Returns: a new vector from the origin to the vector perpendicular to both segments

dotProduct

dotProduct(Vec3D vec): doubleSince1.2.6#

Returns the dot product of the segments' endpoint differences. Its sign indicates whether their directions are less than, equal to, or greater than a right angle apart; it is zero if either segment has zero length. The result is not normalized, so its magnitude depends on both segment lengths. A Vec2D argument selects the inherited 2D overload, which ignores z.

Parameters:

vec: the segment to compare this one's direction against

Returns: the dot product of the two direction differences

dotProduct(Vec2D vec): doubleSince1.2.6#

Returns the dot product of this segment's displacement and vec's displacement. The result is not normalized, so its magnitude depends on both segment lengths. For a Vec3D, this Vec2D overload ignores z; its dotProduct(Vec3D) overload includes it.

Parameters:

vec: the segment to compare this one's direction against

Returns: the dot product of the endpoint displacements

equals

equals(Object o): boolean#

Compares this segment with another object by exact runtime class and all six ordered endpoint coordinates. Coordinates use Double.compare(double, double): NaN values compare equal, while positive and negative zero compare differently. This compares the segment's endpoints, not just its displacement or length.

Parameters:

o: the object to compare with this segment

Returns: true if o is this object or has the same runtime class and equal endpoint coordinates; false otherwise

getDeltaZ

getDeltaZ(): doubleSince1.2.6#

how far the segment runs along z, that is its end's z minus its start's z. It is positive when the end is to the south of the start and negative when it is to the north, in the same sense that a positive x difference points east.

Returns: the z distance covered by this segment

getEnd

getEnd(): Pos3DSince1.2.6#

Returns a copy of the segment's end position, including its z coordinate. Modifying the returned position does not change this segment.

Returns: a new Pos3D at the end of this segment

getMagnitude

getMagnitude(): doubleSince1.2.6#

Returns the Euclidean length across x, y, and z. Unlike Vec2D.getMagnitude(), this includes vertical displacement.

Returns: the length of this segment

getMagnitudeSq

getMagnitudeSq(): doubleSince1.6.5#

Returns the squared Euclidean length across x, y, and z.

Returns: the squared length of this segment

getPitch

getPitch(): floatSince1.2.6#

Returns the segment's pitch in degrees: 0 is level, negative is up, and positive is down. It uses the y difference and the combined horizontal distance across x and z; a zero-length segment returns 0.

Returns: the pitch of this segment's direction in degrees

getStart

getStart(): Pos3DSince1.2.6#

a new position at the start of the segment, with the z coordinate from z1 as well as the flat ones. This is a copy, so writing to it does not move the segment.

Returns: a new Pos3D at the start of this segment

getYaw

getYaw(): floatSince1.2.6#

Returns the segment's yaw in degrees, using the view convention: 0 is south, 90 is west, and -90 is east. Only x and z differences matter. The result is in (-180, 180]; exactly north returns 180. With no horizontal displacement, including a zero-length segment, the result is 0.

Returns: the yaw of this segment's direction in degrees, in (-180, 180]

getZ1

getZ1(): doubleSince1.2.6#

the z coordinate of the start of the segment, the same value as the z1 field.

Returns: the z coordinate of the start

getZ2

getZ2(): doubleSince1.2.6#

the z coordinate of the end of the segment, the same value as the z2 field.

Returns: the z coordinate of the end

hashCode

hashCode(): int#

Computes a hash code from the current ordered endpoint coordinates, including both z coordinates. Because this segment is mutable, its hash may change when its coordinates change; avoid using it as a hash key while mutating it.

Returns: the hash code for the current coordinates

multiply

multiply(Vec3D vec): Vec3DSince1.2.6#

Returns a new segment whose endpoint coordinates are multiplied componentwise by those of vec; this is not a uniform scale, and this segment is unchanged. A Vec2D argument instead selects the inherited 2D overload, which returns a Vec2D and ignores z.

Parameters:

vec: the segment whose endpoint coordinates are the factors

Returns: a new segment with every endpoint coordinate multiplied by its matching one

multiply(double x1, double y1, double z1, double x2, double y2, double z2): Vec3DSince1.6.3#

Returns a new segment with each endpoint coordinate multiplied by its corresponding factor; the start and end can therefore be scaled independently. This segment is unchanged. For one factor applied to all coordinates, use scale(double).

Parameters:

x1: the factor for the start's x coordinate
y1: the factor for the start's y coordinate
z1: the factor for the start's z coordinate
x2: the factor for the end's x coordinate
y2: the factor for the end's y coordinate
z2: the factor for the end's z coordinate

Returns: a new segment with each endpoint coordinate multiplied by its factor

multiply(Vec2D vec): Vec2DSince1.2.6#

Returns a new segment with each endpoint coordinate multiplied by the corresponding coordinate of vec; this is componentwise multiplication, not a uniform scale.

Parameters:

vec: supplies the four coordinate factors

Returns: a new segment with x1 * vec.x1, y1 * vec.y1, x2 * vec.x2, y2 * vec.y2

multiply(double x1, double y1, double x2, double y2): Vec2DSince1.6.3#

Returns a new segment with each endpoint coordinate multiplied by its corresponding factor; the four coordinates can be scaled independently.

Parameters:

x1: the factor for the start's x coordinate
y1: the factor for the start's y coordinate
x2: the factor for the end's x coordinate
y2: the factor for the end's y coordinate

Returns: a new segment with each endpoint coordinate multiplied by its factor

normalize

normalize(): Vec3DSince1.6.5#

Returns a new segment with both endpoints divided by this segment's length. The resulting segment has length one, but its start is also scaled and is preserved only if it is the origin. If the segment has zero length, division produces NaN coordinates.

Returns: a new segment with the same direction but a length of 1

reverse

reverse(): Vec3DSince1.2.6#

Returns a new segment with its endpoints swapped; this segment is unchanged.

Returns: a new segment from the end of this one to its start

scale

scale(double scale): Vec3DSince1.6.3#

Returns a new segment with all six endpoint coordinates multiplied by scale. This scales both endpoints about the origin; this segment is unchanged.

Parameters:

scale: the factor to multiply all six endpoint coordinates by

Returns: a new segment with all six endpoint coordinates scaled

to3D

to3D(): Vec3D#

Returns a copy of this segment, including both z coordinates.

Returns: a new Vec3D containing all six endpoint coordinates

toMojangFloatVector

toMojangFloatVector(): Vector3fSince1.6.5#

Returns the endpoint difference (x2 - x1, y2 - y1, z2 - z1) as a float vector, not a position. Each component is narrowed from double to float and may lose precision.

Returns: a new Vector3f holding the coordinate differences of this segment

toString

toString(): String#

Formats the ordered start and end coordinates in x, y, z order. Finite coordinates have six fractional digits; formatting uses the default locale, so this text is not a stable serialization.

Returns: the formatted endpoint coordinates

Vec3D ​

Constructors ​

new Vec3D ​

Fields ​

z1 ​

z2 ​

Methods ​

add ​

addEnd ​

addStart ​

compareTo ​

crossProduct ​

dotProduct ​

equals ​

getDeltaZ ​

getEnd ​

getMagnitude ​

getMagnitudeSq ​

getPitch ​

getStart ​

getYaw ​

getZ1 ​

getZ2 ​

hashCode ​

multiply ​

normalize ​

reverse ​

scale ​

to3D ​

toMojangFloatVector ​

toString ​

Vec3D

Constructors

new Vec3D

Fields

z1

z2

Methods

add

addEnd

addStart

compareTo

crossProduct

dotProduct

equals

getDeltaZ

getEnd

getMagnitude

getMagnitudeSq

getPitch

getStart

getYaw

getZ1

getZ2

hashCode

multiply

normalize

reverse

scale

to3D

toMojangFloatVector

toString