RayTrace helper

Make RayTrace really easy!

About RayTrace in Bukkit

RayTrace is not usually used on servers, and if it is, it's mostly for creating weapons or checking the environment. RayTrace Helper makes this process very easy and you just need to specify the settings for this process and the helper will do everything for you and return the results.

Creating Instance of RayTace Helper

In order to commit our coveted RayTrace we must create an instance of the RayTrace Helper object. It is created simply.

You need the following: The initial position of the ray, the number of blocks that will be subjected to RayTrace (aka distance), the size of the ray, the world in which the actions will take place (Location#getWorld) and the direction.

I think each component is self-explanatory and not difficult to obtain. For those who forgot how to get the ray direction use new Vector(x,y,z).normalize() (For example: new Vector(1, 0, 0, 0).normalize() for the forward direction).

Example:

Location start = player.getEyeLocation(); // Player eyes

/*
We are making clone of the start position here because eye location can be changed
while we doing things, so we need to be sure that eye location will be fixed.

I don't know if it fixed on newer versions but i want to be sure
that our eye location is fixed and can't be changed.
*/
Vector direction = start.clone().getDirection().normalize();
double distance = 30; // Distance in blocks
int raySize = 1; // 1 - 1x1, 2 - 3x3 and etc.
World world = start.getWorld(); // Yea...

RayTrace rayTrace = new RayTrace(distance, raySize, start, direction, world);

Done!

Callng our RayTrace

After creating an instance, we need to call it. The helper already provides methods for RayTrace, taking into account effects like red dust.

All methods speak for themselves, but they need an additional dataclass to work. Specifically for each type of RayTrace we need its own data class that will additionally set the settings.

Why didn't I just do it through arguments? Well first of all it looked very huge for one method with overloading, and secondly you can just put all settings in one variable, which will allow you to call RayTrace methods faster.

RayTraceEntitiySettings

Contains a single field and it is a list of creatures that RayTrace will ignore. This list is of type Entity.

RayTraceBlocksSettings

It's a pretty self-explanatory date class, too. Contains 2 fields that let you know if you need to trace blocks of water with lava and blocks that can be passed through (Spider web, grass, flowers, etc.).

RayTraceParticleSettings

Pretty straightforward here too, but dustOptions field can be a bit confusing. DustOptions are used to set the color and size of the particles. Use the amount field to determine how many particles there should be per call.

It should be noted here that the particles will only appear after the RayTrace itself and if it fails, there will be no particles. By failure we mean that RayTrace will generate an error during tracing.

Finally lets call our RayTrace!

// Ignoring the shooter.
RayTraceEntitySettings settings = new RayTraceEntitySettings(List.of(player));

// Calling RayTrace for entities only.
RayTraceResult results = rayTrace.rayTraceEntity(settings);

Getting results

The result of RayTrace comes in the form of RayTraceResult which can be just null if you didn't come across anything.

if (results == null) {
    // If we didn't hit anything.
    player.sendMessgae("Miss!");
    return;
}

Entity hit = results.getHitEntity(); // Get hit entity
// Do something with it.

And done. That all you need to know to start with RayTrace Helper!