BlockRay (SpongeAPI 7.2.0 API)

java.lang.Object
- org.spongepowered.api.util.blockray.BlockRay<E>

Type Parameters:

E - The extent in which this ray is being cast

All Implemented Interfaces:

Iterator<BlockRayHit<E>>
```
public class BlockRay<E extends Extent>
extends Object
implements Iterator<BlockRayHit<E>>
```
A block ray which traces a line and returns all block boundaries intersected in order, starting from the start location. If the ray starts in a block, that block is never returned because it is never entered (the ray is already inside).
This class implements the Iterator interface with the exception of Iterator.remove().

Filters determine what blocks the BlockRay should accept. First the stop filter is called. If it returns false then the iterator ends there. Otherwise the skip filter is called. If it returns false then the iterator proceeds to the next block and it is never returned. Otherwise the block is returned. If the distance limit is enabled then it is applied before both filters and acts like the stop filter.

Any one instance of a Predicate should only be run on one path. It is not specified that Predicates have to be stateless, pure functions. They are allowed to keep state along an individual path, based on the assertion that a single instance is only called on one path.

Filters are most useful for limiting the target block a player is looking at based on some metric, like transparency, block model, or even distance. The standard Bukkit-like behavior for finding the target block can be achieved with using ONLY_AIR_FILTER as the stopFilter, combined with continueAfterFilter(Predicate, int) with a second argument of 1, to obtain the block just after the last air.

To get a block ray for an entities' line of sight, use
```
 BlockRay.from(entity);
```
See Also:

BlockRayHit

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`BlockRay.BlockRayBuilder<E extends Extent>` A builder for block ray, which also implements `Iterable`, making it useful for 'advanced for loops'.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`allFilter()` A filter that accepts all blocks.
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`blockTypeFilter(BlockType type)` A filter that only allows blocks of a certain type.
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`continueAfterFilter(Predicate<BlockRayHit<E>> filter, int numberOfBlocks)` Extends a filter by a number of blocks, regardless of what the extended filter does.
`Optional<BlockRayHit<E>>`	`end()` Traces the block ray to the end and returns the last block accepted by the filter, or none if the extent or block limit was reached.
`static BlockRay.BlockRayBuilder<World>`	`from(Entity entity)` Initializes a block ray builder for the entity's eye.
`static <E extends Extent> BlockRay.BlockRayBuilder<E>`	`from(E extent, com.flowpowered.math.vector.Vector3d start)` Initializes a block ray builder with the given starting location.
`static <E extends Extent> BlockRay.BlockRayBuilder<E>`	`from(Location<E> start)` Initializes a block ray builder with the given starting location.
`boolean`	`hasNext()`
`BlockRayHit<E>`	`next()`
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`onlyAirFilter()` A block type filter that only permits air as a transparent block.
`void`	`reset()` Resets the iterator; it will iterate from the starting location again.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator
forEachRemaining, remove

- Method Detail
  - reset
```
public final void reset()
```
    Resets the iterator; it will iterate from the starting location again.
  - hasNext
```
public boolean hasNext()
```
    Specified by:
    
    hasNext in interface Iterator<BlockRayHit<E extends Extent>>
  - next
```
public BlockRayHit<E> next()
```
    Specified by:
    
    next in interface Iterator<BlockRayHit<E extends Extent>>
  - end
```
public Optional<BlockRayHit<E>> end()
```
    Traces the block ray to the end and returns the last block accepted by the filter, or none if the extent or block limit was reached. This advances the iterator.
    
    Returns:
    
    The last block of the ray, if any
  - from
```
public static <E extends Extent> BlockRay.BlockRayBuilder<E> from(Location<E> start)
```
    Initializes a block ray builder with the given starting location.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Parameters:
    
    start - The starting location
    
    Returns:
    
    A new block ray builder
  - from
```
public static <E extends Extent> BlockRay.BlockRayBuilder<E> from(E extent,
                                                                  com.flowpowered.math.vector.Vector3d start)
```
    Initializes a block ray builder with the given starting location.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Parameters:
    
    extent - The extent in which to trace the ray
    
    start - The starting position
    
    Returns:
    
    A new block ray builder
  - from
```
public static BlockRay.BlockRayBuilder<World> from(Entity entity)
```
    Initializes a block ray builder for the entity's eye. If the eye location isn't defined for the entity, the regular location is used. This sets both the starting point and direction.
    
    Parameters:
    
    entity - The entity
    
    Returns:
    
    A new block ray builder
  - allFilter
```
public static <E extends Extent> Predicate<BlockRayHit<E>> allFilter()
```
    A filter that accepts all blocks. A BlockRay combined with no other filter than this one could run endlessly.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Returns:
    
    A filter that accepts all blocks
  - onlyAirFilter
```
public static <E extends Extent> Predicate<BlockRayHit<E>> onlyAirFilter()
```
    A block type filter that only permits air as a transparent block.
    This is provided for convenience, as the default behavior in previous systems was to pass through air blocks only until a non-air block was hit.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Returns:
    
    A filter that only accepts air blocks
  - blockTypeFilter
```
public static <E extends Extent> Predicate<BlockRayHit<E>> blockTypeFilter(BlockType type)
```
    A filter that only allows blocks of a certain type.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Parameters:
    
    type - The type of blocks to allow
    
    Returns:
    
    The filter instance
  - continueAfterFilter
```
public static <E extends Extent> Predicate<BlockRayHit<E>> continueAfterFilter(Predicate<BlockRayHit<E>> filter,
                                                                               int numberOfBlocks)
```
    Extends a filter by a number of blocks, regardless of what the extended filter does.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Parameters:
    
    filter - The filter to extend
    
    numberOfBlocks - The number of blocks to extend it by
    
    Returns:
    
    The extended block filter

Class BlockRay<E extends Extent>

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Method Detail

reset

hasNext

next

end

from

from

from

allFilter

onlyAirFilter

blockTypeFilter

continueAfterFilter