Ships Core Vector and Position

Vector

The Vector API within Ships Core is designed to be easy to adapt and use. It is not limited to XYZ, however the Vector API supports the XZ combo as well as the XYZ.

Vectors are immutable meaning they do not change at all after creation of the object. This is great for reuse of the Vector after doing some maths on it.

Where is the Vector API used with Ships Core?

The Vector API is used in many parts of Ships Core, from the location of blocks, to the location of entities, to the velocity of entities and even chunk positions.

Example of use

Vector3<Double> threeDVector = Vector3.valueOf(1.0, 4.3, 5.0); //holds 3 double values in XYZ
Vector3<Integer> threeIVector = Vector3.valueOf(1, 4, 5); //holds 3 integer values in XYZ
Vector2<Double> twoDVector = Vector2.valueOf(1.0, 5.1); //holds 2 double values in XZ

Converting Vectors

Sometimes you have a Vector3<Integer> and require a Vector3<Double> for something, then you can do the following.

Vector3<Integer> vector3Int = Vector3.valueOf(1, 6, 5);
Vector3<Double> vector3Double = vector3Int.toVector(num -> num.toDouble());

While this works great if your just converting the datatype, sometimes you need to convert a Vector3 to a Vector2 or the other way around, well we have you covered. Any value that was not included in the original but is now will automaticly have the value of 0.

Vector2<Double> vector2Double = Vector2.valueOf(1, 6);
Vector3<Double> vector3Double = vector3Int.toVector(Vector3.DOUBLE_CONVERTER); //now has the value of 1, 6, 0

Position

Now you understand the basics of Vectors we can move onto the main reason for Vectors which is Positions.

Currently there are two main types of Positions. ExactPositions and BlockPositions, however later there will be asynced versions of both of these (some functions on the synced versions can only be used on the main thread, the async versions remove these functions.

Base Position

The base position class is the common class which allows you to do pretty much anything that you would want to do with a position including changing the block at the position, getting the Vector for distance checking, etc.

The position will store the XYZ of the position as well as the World which makes it great for location based calculations within the Minecraft Server

Example of use

Checking distance between two positions

Position<Double> position1;
Position<Double> position2;
float distance = position1.getPostion().distance(position2.getPosition());

Getting the TileEntity at the position

Position<Double> position;`
Optional<TileEntity<?>> opTileEntity = position.getTileEntity();

Creating a instance of Position

WorldExtent world;
BlockPosition bPos = world.getPosition(1, 5, 1);
ExactPosition ePos = world.getPosition(1.0, 5.0, 1.0);

Note that you are required to specify at least one double value within the getPosition to make it return the Exact Position varient of the location.

BlockPosition

Block position is used for, you guessed it, the Position of Blocks. Within Bukkit and Sponge this is equivalent to Block and Location respectivly. This means that the position will always be a Position<Integer> at heart as blocks can only have whole numbers as their position.

ExactPosition

Exact postition is used mainly for entity positions however you may find it in other places within the API. As you may have guessed by the "exact" part of the name, it is always a Position<Double> at the heart.

Converting between Exact and Block

Majority of the time code does not care if the position is a Block or Exact as both share majority of the functions between the common class (even equals(Object) does not care) however in some cases, it is required to have a BlockPosition or ExactPosition however you only have the opposite type. In this case, while you can convert the vector holding the XYZ as shown above, its a lot simpler to do the following.

BlockPosition original;
ExactPosition exactPosition = original.toExact();
BlockPosition backToBlockPostion = exactPosition.toBlock();