Package org.spongepowered.api.util.blockray

Interface RayTrace<T extends Locatable>

  • Type Parameters:
    T - The type of Locatable that this ray trace will attempt to select
    public interface RayTrace<T extends Locatable>
    Builds a set of parameters to define a ray trace that traces from a source position to a target position (or in a specified direction), subject to the supplied constraints.

    A ray trace will check supplied predicates in the following order in the case where multiple predicates should be checked:

    1. continueWhileLocation(Predicate) -- called when the boundary between two blocks is crossed, checking if the ServerLocation the ray is crossing in to is valid, regardless of what the ray has otherwise hit.
    2. select(Predicate) -- called when the AABB of T is crossed by the ray trace, for LocatableBlocks this is called directly after continueWhileLocation(Predicate). This is the only predicate that can return a result, any .
    3. continueWhileBlock(Predicate) -- called if no selection was returned (if appropriate), checks the LocatableBlock the ray is entering. All predicates should return true if the ray should continue to trace through the block.
    4. continueWhileEntity(Predicate) -- called if no selection was returned (if appropriate), checks the Entity the ray has struck. All predicates should return true if the ray should continue to trace through the entity.

    • Method Detail

      • sourcePosition

        RayTrace<T> sourcePosition​(Vector3d sourcePosition)
        Sets the Vector3d position to trace from.
        Parameters:
        sourcePosition - The Vector3d
        Returns:
        This, for chaining

      • limit

        RayTrace<T> limit​(int distance)
        Sets how far this trace will look to find a match, passing all other constraints, before returning no results.

        This defaults to a distance of 30. This will be ignored if a specific position is set via continueUntil(Vector3d).

        Parameters:
        distance - The distance
        Returns:
        This, for chaining

      • continueWhileLocation

        RayTrace<T> continueWhileLocation​(Predicate<ServerLocation> predicate)
        Provides a Predicate that allows a consumer to determine whether a given ServerLocation should allow the trace to succeed. The predicate should return true if the trace should proceed.

        This predicate will be checked when the boundary between two LocatableBlocks is crossed.

        Parameters:
        predicate - The predicate to check
        Returns:
        This, for chaining

      • continueWhileBlock

        RayTrace<T> continueWhileBlock​(Predicate<LocatableBlock> predicate)
        Provides a Predicate that allows a consumer to determine whether a given LocatableBlock (which has not been selected by the predicate provided in select(Predicate) should allow the trace to proceed.

        For example, if a trace is for LocatableBlocks, you may only want to continue the trace if it travels through air (generally used for line of sight purposes). In this case, the predicate may look like this: 

         
 block -> {
   final BlockType type = block.blockState().type();
   return type == BlockTypes.AIR.get() ||
          type == BlockTypes.CAVE_AIR.get() ||
          type == BlockTypes.VOID_AIR.get();
 }

        If this is not supplied, this defaults to always returning true.

        Parameters:
        predicate - The predicate to check
        Returns:
        This, for chaining

      • continueWhileEntity

        RayTrace<T> continueWhileEntity​(Predicate<Entity> predicate)
        Provides a Predicate that allows a consumer to determine whether a given Entity (which has not been selected by the predicate provided in select(Predicate) should allow the trace to proceed.

        If this is not supplied, this will default to true, and if this is not an Entity based ray trace, no entity ray trace calculations will be performed.

        Parameters:
        predicate - The predicate
        Returns:
        This, for chaining

      • select

        RayTrace<T> select​(Predicate<T> filter)
        Determines the condition in which a Locatable hit will be considered successful.

        For example, if this ray trace is LocatableBlock specific and you want to obtain the first non-air block, the predicate might look something like this:

         
 block -> {
   final BlockType type = block.blockState().type();
   return !(type == BlockTypes.AIR.get() &&
          type == BlockTypes.CAVE_AIR.get() &&
          type == BlockTypes.VOID_AIR.get());
 }

        Given the other supplied conditions, if this supplied predicate returns true, the first hit will be returned as a Locatable.

        If multiple predicates are provided, they will be combined using Predicate.or(Predicate).

        A selection will happen before any predicate supplied to continueWhileBlock(Predicate), but after any continueWhileLocation(Predicate) is processed.

        Parameters:
        filter - The filter to use to determine whether to return a RayTraceResult
        Returns:
        This, for chaining.

      • reset

        RayTrace<T> reset()
        Resets this object to its original state.
        Returns:
        This, for chaining.