JsMacrosCE

Appearance

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.

js
// 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