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.LookWhereYoureGoing(character, target_radius=0.05, slow_radius=0.5, time_to_target=0.1)[source]

Bases: Align

Steers the character to face the direction it is currently moving in, by reusing Align with a virtual target oriented towards the character’s own velocity. Complements Face (which orients towards a target’s position instead) and is typically combined with Arrive/Seek/Wander, all of which only steer the linear motion and leave orientation to whatever else is driving it.

Parameters:

character (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.CollisionAvoidance(character, targets, collision_radius=20, max_prediction=2, max_acceleration=None)[source]

Bases: SteeringBehavior

Steers the character away from other moving characters it is on a collision course with, by predicting the time of closest approach to each and, for whichever is soonest and close enough, steering away from its predicted position at that time. Complements Separation (which only reacts to how close targets already are, ignoring where they’re headed) and ObstacleAvoidance/WallAvoidance (which are for static geometry, not other moving characters).

Parameters:

character (Kinematic)
targets (Sequence[Kinematic])
collision_radius (float)
max_prediction (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.Wall(start, end)[source]

Bases: object

A straight wall segment to be used with WallAvoidance.

Parameters:

start (Tuple[float, float])
end (Tuple[float, float])

normal()[source]

Returns:: A unit vector perpendicular to this wall.
Return type:: Vector2

class gale.ai.steering.WallAvoidance(character, walls, whisker_length=40, max_acceleration=None)[source]

Bases: SteeringBehavior

Steers the character away from walls by casting a short whisker ahead of it (along its current velocity) and, if the whisker crosses a wall, steering along that wall’s normal – the classic whisker-based avoidance for straight geometry, as opposed to the circular obstacles ObstacleAvoidance handles.

Parameters:

character (Kinematic)
walls (Sequence[Wall])
whisker_length (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.PathFollow(character, path, path_offset=30, prediction_time=0.2)[source]

Bases: SteeringBehavior

Steers the character to follow a path (an ordered sequence of points, such as one obtained from gale.ai.search over a gale.ai.graph.NavGraph) by predicting the character’s future position, finding the closest point on the path to it, and Seeking a target a fixed distance further along the path – so the character cuts corners smoothly instead of visiting every point exactly.

Parameters:

character (Kinematic)
path (Sequence[Tuple[float, float]])
path_offset (float)
prediction_time (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.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

class gale.ai.steering.CooperativeArbitration(character, groups, score=<function _default_score>)[source]

Bases: SteeringBehavior

Blends each group of behaviors independently (like PrioritySteering does), but – unlike it – evaluates every group instead of stopping at the first meaningful one, and returns whichever scores highest under score. Useful when the “best” behavior isn’t simply the highest-priority one that happens to produce output, but whichever actually addresses the situation the most (for instance, preferring a strong flanking maneuver over a weak direct approach even though both fire at once).

Parameters:

character (Kinematic)
groups (Sequence[Sequence[Tuple[SteeringBehavior, float]]])
score (Callable[[SteeringOutput], 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.OutputFilter(behavior, smoothing=0.2)[source]

Bases: SteeringBehavior

Wraps another steering behavior and smooths its output over time (exponential smoothing) instead of applying it outright, to avoid jittery, frame-to-frame-inconsistent motor output from a noisy underlying behavior.

Parameters:

behavior (SteeringBehavior)
smoothing (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.CapabilityFilter(behavior, max_acceleration, max_angular_acceleration)[source]

Bases: SteeringBehavior

Wraps another steering behavior and clamps its output to a set of capabilities that may be more restrictive than the character’s own Kinematic limits – for instance, reusing the same targeting logic across a fast scout and a slow, heavy tank sharing the same character.max_acceleration, but where the tank’s turret should still turn slower than its chassis’s own limits allow.

Parameters:

behavior (SteeringBehavior)
max_acceleration (float)
max_angular_acceleration (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