Agent Class Reference

#include <src/Agent.h>

Inheritance diagram for Agent:

[legend]Collaboration diagram for Agent:

[legend]List of all members.

---

Detailed Description

Simple vehicule model reusing ideas from Craig Reynolds GDC'99 presentation - http://www.red3d.com/cwr/steer/gdc99/ - http://opensteer.sourceforge.net/.

The main differences between this model and the OpenSteer library are:

• The AI rate, integration rate, and frame rate are separated. This allows batch computing overnight of large simulations, non-real-time rendering (slower or even faster if your system can do it) and also to apply AI at low frequency.
• Energy storage is taken into account. When there is no energy, the car stops and the prey halts...
• Attitude correction is user-defined by helper classes.

Integration update => at least once per frame in graphics mode, may be more often

• Automatic
• Sould ideally be as fast as possible
• Should at least update position & attitude
• In a scenario using energy, this is the granularity for energy consumption
• Is the mathematical integration step, which is especially significant for speed & position. A higher frequency gives a better approximation: Consequently, changing the frequency also changes these values, which may be surprising at first when running the same simulation with the same parameters. You've been warned!

AI update => From time to time

• Can take more time than integration step.
• Atomic with respect to integration update (if AI takes more than one frame, values are applied to the next frame).
• Allows to simulate more agents by spreading time-consuming agents AI updates in a time interval: Don't do all AI updates in one go, then wait next cycle, this would be a waste of resources! Ex: do half of them at t, half of them at t+cycle/2. (Or split in 1/3, 1/4...). You may also spread them randomly on the interval, using a random seed to keep the determinism, or uniformly with a predefined agent order.

Attitude correction:

• When mapping the old forward direction to the new forward, an infinity of rotations can do the job. We must choose one. By default this is the shortest angle rotation bewteen both vectors, thanks to quaternions. This should be equivalent to the default in the OpenSteer library, as the quaternion we use combines both rotations that are done there. See the ShortestAngleAttitudeCorrection class.
• Another policy is provided to force the agent to keep an "up" vector close to a target, which actually defines an horizontal plane. See the KeepUpAttitudeCorrection class.
• No policy was made for banking. Anyone please?

Physics:

• It is based on a point-mass model, as in the OpenSteer library. However, I've added in energy consumption, a drag effect, an energy footprint ratio, and a hack to simulate rotational momentum.
• In a scenario with energy, the energy footprint conversion ratio simulates the body mass necessary to hold this energy. necessary_mass = energy * ratio. See also AgentCore.h . Ex: prey/predator => this is the energy stored in stomach => more predator mass. . Ex2: car race => this is the weight of carburant... or nothing for solar cars . Set this to 0 to simulate an infinite amount of energy can be stored without mass increase (solar cars).
• There is no rotational momentum. An ad-hoc hack is used to simulate the fact more massive objects take longer to turn on themselves given the same force. It is not physically based, but adds some realism at very low cost!
• Don't take the physics in this class too seriously, it is certainly not realistic enough for an industrial material property simulation. However, as very often in games, we're not interested in perfect representation of reality (whatever this means, an equation is also only a representation!). What's interesting is a realistic enough simulation at a reasonable computational cost, which is this implementation intent.

Author:

Nicolas Brodu

Public Member Functions
virtual osg::Vec3d	steerForSeek (const osg::Vec3d &targetPosition)
	Return a force to apply to steer toward the given point.
virtual osg::Vec3d	steerForFlee (const osg::Vec3d &targetPosition)
	Return a force to apply to steer to the opposite direction of the given point Roughly equivalent to the experimental version of the OpenSteer Library.
virtual osg::Vec3d	steerToAvoid (Localized *object)
	Return a force to apply to steer to avoid collision with a given object.
virtual osg::Vec3d	steerForEvasion (Agent *menace)
	Not only do we seek to avoid the agent, but also try to escape it.
virtual osg::Vec3d	steerForPursuit (Agent *quarry)
	The opposite of evasion, try to follow the other agent.
virtual osg::Vec3d	steerForWander (double changeRate)
	Returns a "random" direction, based on the previous direction.
virtual osg::Vec3d	steerForTargetSpeed (double targetSpeed)
	Try to adjust speed to the desired speed.
virtual void	integrationStep ()
	Integration update: update position and attitude by taking into account forces set by AI.
virtual void	aiStep ()
	Public AI step.
virtual void	destroy ()
	Destroys the agent.
virtual void	clampToMaxForce ()
virtual void	findNeighbors (double radius)
	Find all neighbors of this object within a sphere of the given radius.
Public Attributes
double	speed
	Speed of the agent, along its forward direction, expressed in OSG space unit / simulator time unit.
osg::Vec3d	forward
	Current forward vector in world coordinates: initialized to Y in local space to begin with, so orient your models accordingly at load time (or override this in your constructor).
osg::Vec3d	steeringForce
	Current steering force set by AI, in world coordinates.
AttitudeCorrection *	attitudeCorrection
	Attitude correction policy for this agent.
Static Public Attributes
static std::list< Agent * >	allAgents
	A list containing all objects of this class Subset of Localized, useful for faster algorithms.
Protected Member Functions
virtual void	updateAI (double elapsedTime, double currentTime)
	Subclasses should override the updateAI method to implement an AI.
virtual void	updateIntegration (double elapsedTime, double currentTime)
	Subclasses should override the updateStep method to modify the position and attitude _before_ the locality database is updated! They can also modify newPosition and newAttitude directly in this method: the update consistency lock in done only once in the integrationStep method, after this call.
virtual double	predictNearestApproachTime (Agent *agent)
	Directly stolen from OpenSteer Library and adapted to this framework.
Protected Attributes
osg::Vec3d	newPosition
	new Position usable in the updateStep method, set by integrationStep.
osg::Quat	newAttitude
	new Attitude usable in the updateStep method, set by integrationStep.
osg::Vec3d	newForward
	new Forward vector usable in the updateStep method, set by integrationStep.
double	newSpeed
	new Speed usable in the updateStep method, set by integrationStep.
double	steeringForceLen
	Pre-compute force len at AI frequency, not integration step frequency...
double	forwardRadius
	Ad-hoc hack to avoid instantaneous rotation on place due to point-mass model. While this is no substitute for a proper rotational momentum, it still allows agents with more mass to turn more slowly on themselves, adding realism.
double	lastIntegrationStepTime
	step control variable: explicit name
double	lastAIStepTime
	step control variable: explicit name
Static Protected Attributes
static ShortestAngleAttitudeCorrection	shortestAngleAttitudeCorrection
	Shared class variable. The shortest angle policy is stateless, which makes this possible.

---

Member Function Documentation

void Agent::aiStep (   )  [virtual]

Public AI step. This is the method that should be scheduled, subclasses should override the updateAI protected method which is given time information. Note: The very first call to this method actually sets the starting point in time for the first cycle. It returns immediately. Subsequent calls can then use the (simulation) time delta for integration. Reimplemented in CrogaiAgent.

void Agent::destroy (   )  [virtual]

Destroys the agent. Really, don't use delete.... Reimplemented from Localized.

void Agent::findNeighbors (  double  radius  )  [virtual]

Find all neighbors of this object within a sphere of the given radius. Agents are returned classified by distance order, in a multimap whose pair values are: square of the distance and agent pointer. See neighbors field Note: This function should not be protected with neighborsAccessLock(); Indded, it already uses it internally. Besides which, we need to keep allObjectAccess mutex around the neighbors, and not the opposite, so this is the only choice. Note that it doesn't matter if the updated neighbor list is modified before you re-acquire the mutex. Reimplemented from Localized. Reimplemented in CrogaiAgent.

void Agent::integrationStep (   )  [virtual]

Integration update: update position and attitude by taking into account forces set by AI. This is the method that should be scheduled, subclasses should override the updateStep method to modify the position and attitude _before_ the locality database is updated! Note: The very first call to this method actually sets the starting point in time for the first cycle. It returns immediately. Subsequent calls can then use the (simulation) time delta for integration.

osg::Vec3d Agent::steerForEvasion (  Agent *  menace  )  [virtual]

Not only do we seek to avoid the agent, but also try to escape it. This is exactly the same algorithm as in the OpenSteer Library without maximum prediction time, and adapted to this framework. We don't include a maximum for prediction time because that's one more parameter we don't have a clear default value for, and because anyway this function will usually be called for neighbors, with the intent to evade NOW!!!

osg::Vec3d Agent::steerForPursuit (  Agent *  quarry  )  [virtual]

The opposite of evasion, try to follow the other agent. This is exactly the same algorithm as in the OpenSteer Library without maximum prediction time, and adapted to this framework. We don't include a maximum for prediction time because that's one more parameter we don't have a clear default value for, and because anyway this function will usually be called for neighbors, with the intent to pursue them so long as they are visible.

osg::Vec3d Agent::steerForSeek (  const osg::Vec3d &  targetPosition  )  [virtual]

Return a force to apply to steer toward the given point. Roughly equivalent to the experimental version of the OpenSteer Library

osg::Vec3d Agent::steerForTargetSpeed (  double  targetSpeed  )  [virtual]

Try to adjust speed to the desired speed. Do not change direction, useful for breaking. The implementation in the OpenSteer library uses the speed delta as a force. This implementation use numerical integration to predict the effect of the returned force, such that if applied the alone target speed would be reached at next AI step. It's not clamped to max force at this point. Parameters: targetSpeed  the desired speed to reach

osg::Vec3d Agent::steerForWander (  double  changeRate  )  [virtual]

Returns a "random" direction, based on the previous direction. The idea is the same as in the OpenSteer library in the sense that there is no abrupt change in direction, allowing consistent turns. But this implementation does not constrain the new force on a sphere. Instead of the sphere radius, a new parameter is introduced to quantify the "smoothness" of the changes. Note: The standard Utility::Random() function is used, you may control the seed. Parameters: changeRate  how much change is allowed to the previous direction. A value of 0.0 indicates no change is allowed, useless. A value of 1.0 indicates the new force can potentially be in any direction (the old direction is still the prefered on average).

osg::Vec3d Agent::steerToAvoid (  Localized *  object  )  [virtual]

Return a force to apply to steer to avoid collision with a given object. Then: No collision in view: return 0 vector Collision in view: returns a tangential vector (from current forward), in a direction maximizing separation with object. Notes: This algorithm makes the distinction between Agents, obstacles, and anything else. Agents future position is estimated based on their visible current speed & direction. Agents & Obstacles radius add to our own to compute the minimum safe distance passage. This is not at all the same algorithm as in the OpenSteer Library

void Agent::updateAI (  double  elapsedTime, double  currentTime )  [protected, virtual]

Subclasses should override the updateAI method to implement an AI. At least, a new steering force should be given. All steerForXXX methods are available. Reimplemented in ExplicitAIAgent, NeuronalAgent, TerrainAgent, and ExplicitAIAgent.

---

Member Data Documentation

AttitudeCorrection* Agent::attitudeCorrection

Attitude correction policy for this agent. By default, all agents use a ShortestAngle attitude correction, which has the nice advantage of being stateless so it can be shared among agents. This field is not deleted in the destructor (the shared ShortestAngle is handled separately). So if you change the default policy, it's your responsability to manage this field.

osg::Vec3d Agent::forward

Current forward vector in world coordinates: initialized to Y in local space to begin with, so orient your models accordingly at load time (or override this in your constructor). You should not normally need to change this value directly, but rather set a steering force. Of course, if your particular environment has special zones (water swirl?) then maybe...

osg::Quat Agent::newAttitude [protected]

new Attitude usable in the updateStep method, set by integrationStep. This will be the new attitude of this agent, so it can be modified in the updateStep method

osg::Vec3d Agent::newForward [protected]

new Forward vector usable in the updateStep method, set by integrationStep. This will be the new forward vector of this agent, so it can be modified in the updateStep method

osg::Vec3d Agent::newPosition [protected]

new Position usable in the updateStep method, set by integrationStep. This will be the new position of this agent, so it can be modified in the updateStep method

double Agent::newSpeed [protected]

new Speed usable in the updateStep method, set by integrationStep. This will be the new speed of this agent, so it can be modified in the updateStep method

double Agent::speed

Speed of the agent, along its forward direction, expressed in OSG space unit / simulator time unit. You should not normally need to change this value directly, but rather set a steering force. Of course, if your particular environment has slow-down zones (water?) then maybe...

osg::Vec3d Agent::steeringForce

Current steering force set by AI, in world coordinates. Apply this force to the current agent at each integration update, so long as it can (so song as energy remains), till next AI update. One very important goal of the updateAI overload is to update this variable. Note: It is clamped to maxForce at the end of the AI step, after updateAI is called.

---

The documentation for this class was generated from the following files:

• Agent.h
• Agent.cpp

---