gale.ai.agent module

This file contains the implementation of the class Agent, a modular and reusable base to build autonomous characters (vehicles, people, animals, or any kind of creature) by composing a Kinematic body with steering behaviors, a behavior tree, and/or a decision tree.

Author: Alejandro Mujica (aledrums@gmail.com)

class gale.ai.agent.Agent(x=0, y=0, orientation=0, max_speed=200, max_acceleration=200, max_rotation=6.283185307179586, max_angular_acceleration=12.566370614359172, face_movement_direction=True, steering_behavior=None, brain=None, blackboard=None)[source]

Bases: object

Base class for an autonomous character.

An agent is a Kinematic body (position, orientation, velocity, and rotation) driven by up to two independent, swappable pieces:

  • A steering behavior that produces the linear and angular acceleration used to move and orientate the agent on every update.

  • A “brain” (a BehaviorTree or a DecisionTree) that decides which steering behavior, or any other property, the agent should be using at any given moment.

It also owns a Blackboard (see gale.ai.blackboard), a shared key-value store its brain’s nodes, its steering behaviors, and any external system can read and write without needing direct references to one another.

Both the steering behavior and the brain are optional and can be replaced at any time through set_steering_behavior and set_brain. That keeps agents personalizable and reusable: the same Agent (or a subclass of it) can drive a chaser, a wanderer, or a guard just by plugging different steering behaviors and/or brains, and it plays nicely with gale.factory.Factory since its constructor accepts x and y as its first two parameters.

Usage example:

agent = Agent(x=10, y=10, max_speed=150) target = Kinematic(x=200, y=80) agent.set_steering_behavior(Seek(agent.kinematic, target))

# In the game loop: agent.update(dt)

Parameters:

  • x (float)

  • y (float)

  • orientation (float)

  • max_speed (float)

  • max_acceleration (float)

  • max_rotation (float)

  • max_angular_acceleration (float)

  • face_movement_direction (bool)

  • steering_behavior (SteeringBehavior | None)

  • brain (Any | None)

  • blackboard (Blackboard | None)

property position: Vector2
property orientation: float
property velocity: Vector2
set_steering_behavior(steering_behavior)[source]

Replace the steering behavior driving this agent’s movement.

Parameters:

steering_behavior (SteeringBehavior | None) – The new steering behavior. Use None to stop applying acceleration (the agent keeps moving with its current velocity).

Return type:

None

set_brain(brain)[source]

Replace the brain deciding this agent’s behavior.

Parameters:

brain (Any | None) – A BehaviorTree, a DecisionTree, or any other object exposing a compatible tick(agent, dt) method. Use None to disable decision making.

Return type:

None

think(dt)[source]

Run the agent’s brain, if any, typically to update its steering behavior and/or any other of its properties.

Parameters:

dt (float) – Time elapsed (in seconds) since the last update.

Raises:

TypeError – If brain is set and it does not expose a tick(agent, dt) method.

Return type:

None

update(dt)[source]

Update the agent for one time step: run its brain, compute its steering, and integrate its movement.

Parameters:

dt (float) – Time elapsed (in seconds) since the last update.

Return type:

None