com.badlogic.gdx.ai.steer

Interface Proximity<T extends com.badlogic.gdx.math.Vector<T>>

Type Parameters:

T - Type of vector, either 2D or 3D, implementing the Vector interface

All Known Implementing Classes:

FieldOfViewProximity, InfiniteProximity, ProximityBase, RadiusProximity

public interface Proximity<T extends com.badlogic.gdx.math.Vector<T>>

A Proximity defines an area that is used by group behaviors to find and process the owner's neighbors.

Typically (but not necessarily) different group behaviors share the same Proximity for a given owner. This allows you to combine group behaviors so as to get a more complex behavior also known as emergent behavior. Emergent behavior is behavior that looks complex and/or purposeful to the observer but is actually derived spontaneously from fairly simple rules. The lower-level agents following the rules have no idea of the bigger picture; they are only aware of themselves and maybe a few of their neighbors. A typical example of emergence is flocking behavior which is a combination of three group behaviors: separation, alignment, and cohesion. The three behaviors are typically combined through a blended steering. This works okay but, because of the limited view distance of a character, it's possible for an agent to become isolated from its flock. If this happens, it will just sit still and do nothing. To prevent this from happening, you usually add in the wander behavior too. This way, all the agents keep moving all the time. Tweaking the magnitudes of each of the contributing behaviors will give you different effects such as shoals of fish, loose swirling flocks of birds, or bustling close-knit herds of sheep.

Before a steering acceleration can be calculated for a combination of group behaviors, the neighbors must be determined and processed. This is done by the findNeighbors(com.badlogic.gdx.ai.steer.Proximity.ProximityCallback<T>) method and its callback argument.

Notes:

• Sharing a Proximity instance among group behaviors having the same owner can save a little time determining the neighbors only once from inside the findNeighbors method. Especially, Proximity implementation classes can use GdxAI.getTimepiece().getTime() to calculate neighbors only once per frame (assuming delta time is always greater than 0, if time has changed the frame has changed too). This means that
  • if you forget to update the timepiece on each frame the proximity instance will be calculated only the very first time, which is not what you want of course.
  • ideally the timepiece should be updated before the proximity is updated by the findNeighbors(ProximityCallback) method.
• If you want to make sure a Proximity doesn't use as a neighbor a given agent from the list, for example the evader or the owner itself, you have to implement a callback that prevents it from being considered by returning false from the method reportNeighbor.
• If there is some efficient way of pruning potential neighbors before they are processed, the overall performance in time will improve. Spatial data structures such as multi-resolution maps, quad-trees, oct-trees, and binary space partition (BSP) trees can be used to get potential neighbors more efficiently. Spatial partitioning techniques are crucial when you have to deal with lots of agents. Especially, if you're using Bullet or Box2d in your game, it's recommended to implement proximities that exploit their methods to query the world. Both Bullet and Box2d internally use some kind of spatial partitioning.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Proximity.ProximityCallback<T extends com.badlogic.gdx.math.Vector<T>> The callback object used by a proximity to report the owner's neighbor.

Method Summary

Modifier and Type	Method and Description
int	findNeighbors(Proximity.ProximityCallback<T> callback) Finds the agents that are within the immediate area of the owner.
Steerable<T>	getOwner() Returns the owner of this proximity.
void	setOwner(Steerable<T> owner) Sets the owner of this proximity.

Method Detail

getOwner

Steerable<T> getOwner()

Returns the owner of this proximity.

setOwner

void setOwner(Steerable<T> owner)

Sets the owner of this proximity.

findNeighbors

int findNeighbors(Proximity.ProximityCallback<T> callback)

Finds the agents that are within the immediate area of the owner. Each of those agents is passed to the reportNeighbor method of the specified callback.

Returns:

the number of neighbors found.