QuarterBukkit

# Shape API

The shape api allows to use shapes of different forms that contain some blocks. In order to be able to work with shapes, the Shape interface specifies some methods each shape implementation must provide.

## Shape Interface

The center of the shape (in a sphere it would be the origin, for example) can be retrieved with the two following methods. The second one actually rounds the center vector to a block location.

```public Vector getCenter()
public Vector getBlockCenter()
```

The axis aligned bounding box (AABB) can be retrieved with the following method. An AABB is a new not rotated cuboid shape the shape exactly fits into while no spare space is allowed to be left on any side.

```public Shape getAxisAlignedBoundingBox()
```

The following method allows to collect a list of vectors that completely fill in the shape. The distance parameter controls how far away the vectors are from each other. For example, the distance 1 represents one vector for each block inside the shape. By making the distance smaller, the resolution becomes higher and more vectors are returned.

```public Collection<Vector> getContent(double distance)
```

For example, the blocks inside the shape could be retrieved as follows:

```for (Vector vector : shape.getBlocks()) {
Block block = vector.toLocation(world).getBlock();
...
}
```

Finally, the following methods check whether a given vector is located inside the shape:

```public boolean intersects(double x, double y, double z)
public boolean intersects(Vector vector)
public boolean intersects(Location location)
```

## Cuboid

An (axis aligned) cuboid is represented two different vectors that define its outer corners. Everything between those two points counts as inside.

All input coordinates are converted to a minimum vector and a maximum vector. This conversion will lose the original vectors, but you can work better with the data later on. Here's an example on how the sorting works: There are two vectors with the coordinates `5, 10, 7` and `12, 6, 18`. After the sorting, the two vectors will be `5, 6, 7` (the small one) and `12, 10, 18` (the large one). Those two vectors now define the corners of the cuboid.

A new cuboid can be created and filled with data using the following constructors:

```public Cuboid(double x1, double y1, double z1, double x2, double y2, double z2)
public Cuboid(Vector vector1, Vector vector2)
public Cuboid(Location location1, Location location2)
```

The minimum and maximum vectors can be retrieved with the following methods:

```public Vector getMinVector()
public Vector getMaxVector()
```

The distance between two minimum and maximum coordinates can also be calculated with the following methods. They can be used to get the distance between the two walls of the cuboid on one axis. Note that there are also methods that allow to retrieve the distance between the two rounded block coordinates.

```public double getXDistance()
public double getYDistance()
public double getZDistance()

public double getBlockXDistance()
public double getBlockYDistance()
public double getBlockZDistance()
```

## Sphere

A sphere is represented by an origin vector and a radius, which defines the distance from the origin to any point on the surface.

A new sphere can be created and filled with data using the following constructors:

```public Sphere(double originX, double originY, double originZ, double radius)
```

The origin and the radius can be retrieved and replaced with the following methods. Since all shapes are immutable, a new sphere is created and returned when one of the replacement methods is called.

```public Vector getOrigin()

public Sphere withOrigin(double originX, double originY, double originZ)
public Sphere withOrigin(Vector origin)
public Sphere withOrigin(Location origin)
```

## Cylinder

A cylinder is represented by confining vectors and a radius. The two vectors define the origins of the top and bottom circles of the cylinder, while the radius defines the shortest distance from the line between the two vectors to any point on the mantle.

A new cylinder can be created and filled with data using the following constructors. The two origins are automatically sorted to top and bottom ones (the y coordinate of the top origin is larger than the one of bottom origin).

```public Cylinder(double circle1OriginX, double circle1OriginY, double circle1OriginZ, double circle2OriginX, double circle2OriginY, double circle2OriginZ, double radius)
public Cylinder(Vector circle1Origin, Vector circle2Origin, double radius)
public Cylinder(Location circle1Origin, Location circle2Origin, double radius)
```

The top and bottom origins and the radius can be retrieved and replaced with the following methods. Since all shapes are immutable, a new cylinder is created and returned when one of the replacement methods is called. In case of an origin replacement, the two new origins are automatically sorted to top and bottom ones (the y coordinate of the top origin is larger than the one of bottom origin).

```public Vector getTopCircleOrigin()
public Vector getBottomCircleOrigin()
```public double getLength()