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 Details

    • block

      static RayTrace<LocatableBlock> block()
      Creates a RayTrace that will attempt to select a LocatableBlock.
      Returns:
      The ray trace builder.

    • entity

      static RayTrace<Entity> entity()
      Creates a RayTrace that will attempt to select an Entity.
      Returns:
      The ray trace builder.

    • onlyAir

      static Predicate<LocatableBlock> onlyAir()
      Returns a Predicate for use in continueWhileLocation(Predicate) that only allows a trace to continue if the LocatableBlock at the given position is air.
      Returns:
      The predicate

    • nonAir

      static Predicate<LocatableBlock> nonAir()
      Returns a Predicate for use in select(Predicate) that selects non-air blocks.
      Returns:
      The predicate

    • world

      RayTrace<T> world(ServerWorld serverWorld)
      Sets the ServerWorld to perform the ray trace in.
      Parameters:
      serverWorld - The ServerWorld
      Returns:
      This, for chaining

    • sourcePosition

      default RayTrace<T> sourcePosition(Entity entity)
      Sets the position to trace from, based on the supplied Entity's position.

      This will use Entity.position() to determine the entity position. This may be unexpected if you wish to ray trace along the line of sight of the entity. In this scenario, use sourceEyePosition(Living) instead.

      Parameters:
      entity - The Entity
      Returns:
      This, for chaining

    • sourceEyePosition

      RayTrace<T> sourceEyePosition(Living entity)
      Sets the position to trace from, based on the supplied Entity's eye position.

      If Keys.EYE_POSITION does not exist, this will throw an IllegalArgumentException instead.

      Parameters:
      entity - The Living
      Returns:
      This, for chaining

    • sourcePosition

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

    • direction

      RayTrace<T> direction(Vector3d direction)
      Sets the direction to trace in.

      If continueUntil(Vector3d) is set, this will be unset.

      Parameters:
      direction - The Vector3d
      Returns:
      This, for chaining

    • direction

      default RayTrace<T> direction(Living entity)
      Sets the direction to trace in, based on the direction the direction the supplied Living is currently looking.

      If continueUntil(Vector3d) is set, this will be unset.

      Parameters:
      entity - The Living
      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

    • continueUntil

      RayTrace<T> continueUntil(Vector3d endPosition)
      Sets the Vector3d position where a ray trace should end.

      If direction(Living) or direction(Vector3d) is set, this will be unset and any limit set via limit(int) will be ignored.

      Parameters:
      endPosition - The position
      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.

    • execute

      Optional<RayTraceResult<T>> execute()
      Executes this ray trace and returns a RayTraceResult containing the Locatable if successful.
      Returns:
      The RayTraceResult, if any.

    • reset

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