RaycastObstacleAvoidance (libGDX AI)

java.lang.Object
- com.badlogic.gdx.ai.steer.SteeringBehavior<T>
- - com.badlogic.gdx.ai.steer.behaviors.RaycastObstacleAvoidance<T>

Type Parameters:

T - Type of vector, either 2D or 3D, implementing the Vector interface
```
public class RaycastObstacleAvoidance<T extends com.badlogic.gdx.math.Vector<T>>
extends SteeringBehavior<T>
```
With the RaycastObstacleAvoidance the moving agent (the owner) casts one or more rays out in the direction of its motion. If these rays collide with an obstacle, then a target is created that will avoid the collision, and the owner does a basic seek on this target. Typically, the rays extend a short distance ahead of the character (usually a distance corresponding to a few seconds of movement).
This behavior is especially suitable for large-scale obstacles like walls.
You should use the RayConfiguration more suitable for your game environment. Some basic ray configurations are provided by the framework: SingleRayConfiguration, ParallelSideRayConfiguration and CentralRayWithWhiskersConfiguration. There are no hard and fast rules as to which configuration is better. Each has its own particular idiosyncrasies. A single ray with short whiskers is often the best initial configuration to try but can make it impossible for the character to move down tight passages. The single ray configuration is useful in concave environments but grazes convex obstacles. The parallel configuration works well in areas where corners are highly obtuse but is very susceptible to the corner trap.

The corner trap
All the basic configurations for multi-ray obstacle avoidance can suffer from a crippling problem with acute angled corners (any convex corner, in fact, but it is more prevalent with acute angles). Consider a character with two parallel rays that is going towards a corner. As soon as its left ray is colliding with the wall near the corner, the steering behavior will turn it to the left to avoid the collision. Immediately, the right ray will then be colliding the other side of the corner, and the steering behavior will turn the character to the right. The character will repeatedly collide both sides of the corner in rapid succession. It will appear to home into the corner directly, until it slams into the wall. It will be unable to free itself from the trap.
The fan structure, with a wide enough fan angle, alleviates this problem. Often, there is a trade-off, however, between avoiding the corner trap with a large fan angle and keeping the angle small to allow the character to access small passages. At worst, with a fan angle near PI radians, the character will not be able to respond quickly enough to collisions detected on its side rays and will still graze against walls. There are two approaches that work well and represent the most practical solutions to the problem:
- Adaptive fan angles: If the character is moving successfully without a collision, then the fan angle is narrowed. If a collision is detected, then the fan angle is widened. If the character detects many collisions on successive frames, then the fan angle will continue to widen, reducing the chance that the character is trapped in a corner.
- Winner ray: If a corner trap is detected, then one of the rays is considered to have won, and the collisions detected by other rays are ignored for a while.
It seems that the most practical solution is to use adaptive fan angles, with one long ray cast and two shorter whiskers.

Field Summary

Fields
Modifier and Type	Field and Description
`protected float`	`distanceFromBoundary` The minimum distance to a wall, i.e.
`protected RaycastCollisionDetector<T>`	`raycastCollisionDetector` The collision detector
`protected RayConfiguration<T>`	`rayConfiguration` The inputRay configuration

Fields inherited from class com.badlogic.gdx.ai.steer.SteeringBehavior
enabled, limiter, owner

Constructor Summary

Constructors
Constructor and Description
`RaycastObstacleAvoidance(Steerable<T> owner)` Creates a `RaycastObstacleAvoidance` behavior.
`RaycastObstacleAvoidance(Steerable<T> owner, RayConfiguration<T> rayConfiguration)` Creates a `RaycastObstacleAvoidance` behavior.
`RaycastObstacleAvoidance(Steerable<T> owner, RayConfiguration<T> rayConfiguration, RaycastCollisionDetector<T> raycastCollisionDetector)` Creates a `RaycastObstacleAvoidance` behavior.
`RaycastObstacleAvoidance(Steerable<T> owner, RayConfiguration<T> rayConfiguration, RaycastCollisionDetector<T> raycastCollisionDetector, float distanceFromBoundary)` Creates a `RaycastObstacleAvoidance` behavior.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected SteeringAcceleration<T>`	`calculateRealSteering(SteeringAcceleration<T> steering)` Calculates the steering acceleration produced by this behavior and writes it to the given steering output.
`float`	`getDistanceFromBoundary()` Returns the distance from boundary, i.e.
`RaycastCollisionDetector<T>`	`getRaycastCollisionDetector()` Returns the raycast collision detector of this behavior.
`RayConfiguration<T>`	`getRayConfiguration()` Returns the ray configuration of this behavior.
`RaycastObstacleAvoidance<T>`	`setDistanceFromBoundary(float distanceFromBoundary)` Sets the distance from boundary, i.e.
`RaycastObstacleAvoidance<T>`	`setEnabled(boolean enabled)` Sets this steering behavior on/off.
`RaycastObstacleAvoidance<T>`	`setLimiter(Limiter limiter)` Sets the limiter of this steering behavior.
`RaycastObstacleAvoidance<T>`	`setOwner(Steerable<T> owner)` Sets the owner of this steering behavior.
`RaycastObstacleAvoidance<T>`	`setRaycastCollisionDetector(RaycastCollisionDetector<T> raycastCollisionDetector)` Sets the raycast collision detector of this behavior.
`RaycastObstacleAvoidance<T>`	`setRayConfiguration(RayConfiguration<T> rayConfiguration)` Sets the ray configuration of this behavior.

Methods inherited from class com.badlogic.gdx.ai.steer.SteeringBehavior
calculateSteering, getActualLimiter, getLimiter, getOwner, isEnabled, newVector

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

- Field Detail
  - rayConfiguration
```
protected RayConfiguration<T extends com.badlogic.gdx.math.Vector<T>> rayConfiguration
```
    The inputRay configuration
  - raycastCollisionDetector
```
protected RaycastCollisionDetector<T extends com.badlogic.gdx.math.Vector<T>> raycastCollisionDetector
```
    The collision detector
  - distanceFromBoundary
```
protected float distanceFromBoundary
```
    The minimum distance to a wall, i.e. how far to avoid collision.
- Constructor Detail
  - RaycastObstacleAvoidance
```
public RaycastObstacleAvoidance(Steerable<T> owner)
```
    Creates a RaycastObstacleAvoidance behavior.
    
    Parameters:
    
    owner - the owner of this behavior
  - RaycastObstacleAvoidance
```
public RaycastObstacleAvoidance(Steerable<T> owner,
                                RayConfiguration<T> rayConfiguration)
```
    Creates a RaycastObstacleAvoidance behavior.
    
    Parameters:
    
    owner - the owner of this behavior
    
    rayConfiguration - the ray configuration
  - RaycastObstacleAvoidance
```
public RaycastObstacleAvoidance(Steerable<T> owner,
                                RayConfiguration<T> rayConfiguration,
                                RaycastCollisionDetector<T> raycastCollisionDetector)
```
    Creates a RaycastObstacleAvoidance behavior.
    
    Parameters:
    
    owner - the owner of this behavior
    
    rayConfiguration - the ray configuration
    
    raycastCollisionDetector - the collision detector
  - RaycastObstacleAvoidance
```
public RaycastObstacleAvoidance(Steerable<T> owner,
                                RayConfiguration<T> rayConfiguration,
                                RaycastCollisionDetector<T> raycastCollisionDetector,
                                float distanceFromBoundary)
```
    Creates a RaycastObstacleAvoidance behavior.
    
    Parameters:
    
    owner - the owner of this behavior
    
    rayConfiguration - the ray configuration
    
    raycastCollisionDetector - the collision detector
    
    distanceFromBoundary - the minimum distance to a wall (i.e., how far to avoid collision).
- Method Detail
  - calculateRealSteering
```
protected SteeringAcceleration<T> calculateRealSteering(SteeringAcceleration<T> steering)
```
    Description copied from class: SteeringBehavior
    
    Calculates the steering acceleration produced by this behavior and writes it to the given steering output.
    This method is called by SteeringBehavior.calculateSteering(SteeringAcceleration) when this steering behavior is enabled.
    
    Specified by:
    
    calculateRealSteering in class SteeringBehavior<T extends com.badlogic.gdx.math.Vector<T>>
    
    Parameters:
    
    steering - the steering acceleration to be calculated.
    
    Returns:
    
    the calculated steering acceleration for chaining.
  - getRayConfiguration
```
public RayConfiguration<T> getRayConfiguration()
```
    Returns the ray configuration of this behavior.
  - setRayConfiguration
```
public RaycastObstacleAvoidance<T> setRayConfiguration(RayConfiguration<T> rayConfiguration)
```
    Sets the ray configuration of this behavior.
    
    Parameters:
    
    rayConfiguration - the ray configuration to set
    
    Returns:
    
    this behavior for chaining.
  - getRaycastCollisionDetector
```
public RaycastCollisionDetector<T> getRaycastCollisionDetector()
```
    Returns the raycast collision detector of this behavior.
  - setRaycastCollisionDetector
```
public RaycastObstacleAvoidance<T> setRaycastCollisionDetector(RaycastCollisionDetector<T> raycastCollisionDetector)
```
    Sets the raycast collision detector of this behavior.
    
    Parameters:
    
    raycastCollisionDetector - the raycast collision detector to set
    
    Returns:
    
    this behavior for chaining.
  - getDistanceFromBoundary
```
public float getDistanceFromBoundary()
```
    Returns the distance from boundary, i.e. the minimum distance to an obstacle.
  - setDistanceFromBoundary
```
public RaycastObstacleAvoidance<T> setDistanceFromBoundary(float distanceFromBoundary)
```
    Sets the distance from boundary, i.e. the minimum distance to an obstacle.
    
    Parameters:
    
    distanceFromBoundary - the distanceFromBoundary to set
    
    Returns:
    
    this behavior for chaining.
  - setOwner
```
public RaycastObstacleAvoidance<T> setOwner(Steerable<T> owner)
```
    Description copied from class: SteeringBehavior
    
    Sets the owner of this steering behavior.
    
    Overrides:
    
    setOwner in class SteeringBehavior<T extends com.badlogic.gdx.math.Vector<T>>
    
    Returns:
    
    this behavior for chaining.
  - setEnabled
```
public RaycastObstacleAvoidance<T> setEnabled(boolean enabled)
```
    Description copied from class: SteeringBehavior
    
    Sets this steering behavior on/off.
    
    Overrides:
    
    setEnabled in class SteeringBehavior<T extends com.badlogic.gdx.math.Vector<T>>
    
    Returns:
    
    this behavior for chaining.
  - setLimiter
```
public RaycastObstacleAvoidance<T> setLimiter(Limiter limiter)
```
    Sets the limiter of this steering behavior. The given limiter must at least take care of the maximum linear acceleration.
    
    Overrides:
    
    setLimiter in class SteeringBehavior<T extends com.badlogic.gdx.math.Vector<T>>
    
    Returns:
    
    this behavior for chaining.

Class RaycastObstacleAvoidance<T extends com.badlogic.gdx.math.Vector<T>>

The corner trap

Field Summary

Fields inherited from class com.badlogic.gdx.ai.steer.SteeringBehavior

Constructor Summary

Method Summary

Methods inherited from class com.badlogic.gdx.ai.steer.SteeringBehavior

Methods inherited from class java.lang.Object

Field Detail

rayConfiguration

raycastCollisionDetector

distanceFromBoundary

Constructor Detail

RaycastObstacleAvoidance

RaycastObstacleAvoidance

RaycastObstacleAvoidance

RaycastObstacleAvoidance

Method Detail

calculateRealSteering

getRayConfiguration

setRayConfiguration

getRaycastCollisionDetector

setRaycastCollisionDetector

getDistanceFromBoundary

setDistanceFromBoundary

setOwner

setEnabled

setLimiter