gale.ai.steering module

This file contains steering behaviors to compute the linear and angular acceleration that autonomous characters (vehicles, people, animals, or any kind of creature) need to move and orientate themselves, following the classic formulation described by Ian Millington in “Artificial Intelligence for Games”.

Author: Alejandro Mujica (aledrums@gmail.com)

class gale.ai.steering.SteeringOutput(linear=None, angular=0)[source]

Bases: object

Groups the linear and angular acceleration produced by a steering behavior.

Parameters:

linear (Vector2 | None)
angular (float)

is_zero()[source]

Returns:: Whether this steering does not produce any acceleration.
Return type:: bool

class gale.ai.steering.Kinematic(x=0, y=0, orientation=0, max_speed=200, max_acceleration=200, max_rotation=6.283185307179586, max_angular_acceleration=12.566370614359172)[source]

Bases: object

Groups the physical state of a moving character: its position and orientation (in radians), together with their first derivatives, velocity and rotation (angular speed).

Parameters:

x (float)
y (float)
orientation (float)
max_speed (float)
max_acceleration (float)
max_rotation (float)
max_angular_acceleration (float)

property x: float

property y: float

orientation_as_vector()[source]

Returns:: A unit vector pointing towards the current orientation.
Return type:: Vector2

static vector_to_orientation(vector)[source]

Parameters:: vector (Vector2) – The vector to get the orientation from.
Returns:: The orientation, in radians, represented by the given vector. Zero if the vector has no length.
Return type:: float

update(steering, dt)[source]

Integrate this kinematic one time step forward by using the given steering output.

Parameters:

steering (SteeringOutput) – The linear and angular acceleration to apply.
dt (float) – Time elapsed (in seconds) since the last update.

Return type:

None

class gale.ai.steering.SteeringBehavior[source]

Bases: object

Base class for any steering behavior. A steering behavior computes the linear and angular acceleration that a character should have to fulfil a movement goal, for instance, reaching a target, avoiding an obstacle, or wandering around.

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Seek(character, target)[source]

Bases: SteeringBehavior

Steers the character to move towards the target as fast as possible.

Parameters:

character (Kinematic)
target (Kinematic)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Flee(character, target)[source]

Bases: Seek

Steers the character to move away from the target as fast as possible.

Parameters:

character (Kinematic)
target (Kinematic)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Arrive(character, target, target_radius=5, slow_radius=100, time_to_target=0.1)[source]

Bases: SteeringBehavior

Steers the character to reach the target and stop right there, slowing down as it approaches to avoid overshooting it.

Parameters:

character (Kinematic)
target (Kinematic)
target_radius (float)
slow_radius (float)
time_to_target (float)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Align(character, target, target_radius=0.05, slow_radius=0.5, time_to_target=0.1)[source]

Bases: SteeringBehavior

Steers the character to match its orientation with the target’s orientation, slowing down its rotation as it gets close.

Parameters:

character (Kinematic)
target (Kinematic)
target_radius (float)
slow_radius (float)
time_to_target (float)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Face(character, target, target_radius=0.05, slow_radius=0.5, time_to_target=0.1)[source]

Bases: Align

Steers the character to face towards the target’s position, by reusing Align with a virtual target that has the required orientation.

Parameters:

character (Kinematic)
target (Kinematic)
target_radius (float)
slow_radius (float)
time_to_target (float)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.VelocityMatch(character, target, time_to_target=0.1)[source]

Bases: SteeringBehavior

Steers the character to match the target’s velocity.

Parameters:

character (Kinematic)
target (Kinematic)
time_to_target (float)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Pursue(character, target, max_prediction=1)[source]

Bases: Seek

Steers the character to intercept the target by seeking its predicted future position instead of its current one.

Parameters:

character (Kinematic)
target (Kinematic)
max_prediction (float)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Evade(character, target, max_prediction=1)[source]

Bases: Flee

Steers the character away from the predicted future position of the target, instead of its current one.

Parameters:

character (Kinematic)
target (Kinematic)
max_prediction (float)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Wander(character, offset=50, radius=30, rate=3.141592653589793, max_acceleration=None)[source]

Bases: SteeringBehavior

Steers the character to wander around by continuously seeking a moving target placed a fixed distance ahead of it that randomly drifts around a circle.

Parameters:

character (Kinematic)
offset (float)
radius (float)
rate (float)
max_acceleration (float | None)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Separation(character, targets, threshold=50, max_acceleration=None)[source]

Bases: SteeringBehavior

Steers the character away from a group of nearby targets. Useful to implement flocking or crowd behaviors together with VelocityMatch and a cohesion-like Seek towards the group’s center.

Parameters:

character (Kinematic)
targets (Sequence[Kinematic])
threshold (float)
max_acceleration (float | None)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.Obstacle(x, y, radius)[source]

Bases: object

A simple circular obstacle to be used with ObstacleAvoidance.

Parameters:

x (float)
y (float)
radius (float)

class gale.ai.steering.ObstacleAvoidance(character, obstacles, avoid_margin=20, lookahead=100, max_acceleration=None)[source]

Bases: SteeringBehavior

Steers the character away from the nearest obstacle that lies ahead of it, based on a simple lookahead check along its current velocity.

Parameters:

character (Kinematic)
obstacles (Sequence[Obstacle])
avoid_margin (float)
lookahead (float)
max_acceleration (float | None)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.BlendedSteering(character, behaviors)[source]

Bases: SteeringBehavior

Combines several steering behaviors by adding their weighted outputs together, then clamping the result to the character’s limits.

Parameters:

character (Kinematic)
behaviors (Sequence[Tuple[SteeringBehavior, float]])

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput

class gale.ai.steering.PrioritySteering(character, groups, epsilon=0.001)[source]

Bases: SteeringBehavior

Tries each group of behaviors (blended together) in order and returns the first one that produces a meaningful steering output. Useful to make urgent behaviors, such as obstacle avoidance, override lower priority ones, such as seeking a target.

Parameters:

character (Kinematic)
groups (Sequence[Sequence[Tuple[SteeringBehavior, float]]])
epsilon (float)

get_steering(dt=0)[source]

Compute the steering output of this behavior.

Parameters:: dt (float) – Time elapsed (in seconds) since the last call. Only used by time-dependent behaviors, such as Wander.
Returns:: The computed steering output.
Return type:: SteeringOutput