BlockRay (SpongeAPI 7.3.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 continuation filter(s) (provided by BlockRay.BlockRayBuilder.whilst(Predicate)) are checked. If any of the provided filters return false then the iterator ends there - no more matches may be made by this ray.

If this ray has not been stopped, the selection filter(s) (provided by BlockRay.BlockRayBuilder.select(Predicate)) are called. If any of the provided filters returns false then the iterator proceeds to the next block and it is never returned as a BlockRayHit. Otherwise the block is returned and the iterator is paused, awaiting a next() call to resume tracing. If the distance limit is enabled then it is applied before both continuation and select checks and acts like the a false result has been returned by a continuation 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 continue filter, combined with continueAfterFilter(Predicate, int) with a second argument of 1, to enable the ray to iterate such that it can select the block just after the last air. A notAirFilter() can then be used as the select filter to select the non-air block. Thus:
```
 BlockRay.from(fromLocation)
     .to(toLocation)
     .select(BlockRay.notAirFilter())
     .whilst(BlockRay.continueAfterFilter(BlockRay.onlyAirFilter(), 1))
     .build();
 
```
will scan the blocks between the two specified locations to locate the first non-air block along the line from the fromLocation to the toLocation.

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 returns `true` for any input.
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`blockTypeFilter(BlockType... types)` A filter that will return `true` when the `BlockRayHit` represents any of the supplied `BlockType`s.
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`blockTypeFilter(BlockType type)` A filter that will only return `true` when the `BlockRayHit` represents the supplied `BlockType`.
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`continueAfterFilter(Predicate<BlockRayHit<E>> filter, int numberOfBlocks)` Creates a filter that displaces a `false` result from the wrapped `Predicate` by the provided `numberOfBlocks`, if this number is positive.
`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>>`	`notAirFilter()` A filter that will return `true` when the `BlockRayHit` does not represent `BlockTypes.AIR`.
`static <E extends Extent> Predicate<BlockRayHit<E>>`	`onlyAirFilter()` A filter that will only return `true` when the `BlockRayHit` represents `BlockTypes.AIR`.
`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 returns true for any input.
    In the absence of any other filter, this is the default filter applied to:
    - BlockRay.BlockRayBuilder.whilst(Predicate)
    - BlockRay.BlockRayBuilder.select(Predicate)
    Be careful: if no other constraints are placed on BlockRay.BlockRayBuilder.whilst(Predicate) and BlockRay.BlockRayBuilder.select(Predicate) is given a Predicate that has a narrower focus, a ray may never find a match and therefore continue 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 filter that will only return true when the BlockRayHit represents BlockTypes.AIR.
    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
  - notAirFilter
```
public static <E extends Extent> Predicate<BlockRayHit<E>> notAirFilter()
```
    A filter that will return true when the BlockRayHit does not represent BlockTypes.AIR.
    
    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 will only return true when the BlockRayHit represents the supplied BlockType.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Parameters:
    
    type - The type of block to allow
    
    Returns:
    
    The filter instance
  - blockTypeFilter
```
public static <E extends Extent> Predicate<BlockRayHit<E>> blockTypeFilter(BlockType... types)
```
    A filter that will return true when the BlockRayHit represents any of the supplied BlockTypes.
    
    Type Parameters:
    
    E - The extent to be applied in
    
    Parameters:
    
    types - The type of block to allow
    
    Returns:
    
    The filter instance
  - continueAfterFilter
```
public static <E extends Extent> Predicate<BlockRayHit<E>> continueAfterFilter(Predicate<BlockRayHit<E>> filter,
                                                                               int numberOfBlocks)
```
    Creates a filter that displaces a false result from the wrapped Predicate by the provided numberOfBlocks, if this number is positive.
    If numberOfBlocks is non-positive, this filter will mirror the behavior of the provided filter.
    
    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

notAirFilter

blockTypeFilter

blockTypeFilter

continueAfterFilter