Intro    Entity    Trait    Action

Entity structure  - "LifeAI_Entity.h"

    Constructor
        Entity

    Static
        getCount
        getEntity (by number)
        getEntity (by name)

    General
        setName
        getName

    Trait
        setTrait
        setValue
        getTrait
        getValue

    Entity
        setParent
        setChild
        getParent
        getChild

    Action
        setParent
        setChild
        setMemberParent
        setBasic
        getParent
        getChild
        getMemberParent
        getBasic
        getAverage
        getCorrelationCount
        getCorrelation
        getCorrelationMember
        getCorrelationTrait
        getRecordCount
        getRecord
        getRecordEntity

    Logic
        plan
        startAction
        endAction
        getPlanCount
        getPlan
        getPlanEntity
        getPlanValue
        getStartAction
        getStartEntity


Constructor


LifeAI::Entity( std::string name = LAI_DEF_ENTITY_NAME )


When creating an entity, can optionally store a name string for it.


Static


int LifeAI::Entity::getCount()


Returns the total number of entities that have been created.  Can be useful if you need to iterate through all entities with getEntity()


Entity* LifeAI::Entity::getEntity( int number )


Returns an entity address, according to the number you specify in the parameter.  The "number" refers to the order of the entity in the main entity list.  For example, if you need to reference the first entity created, the "number" should be 0.  For the second entity, the "number" should be 1.  Can be useful if you need to iterate through all entities.


Entity* LifeAI::Entity::getEntity( std::string name )


Returns an entity address, according to the string you specify in the "name" parameter.  Looks through the main Entity list and returns the first entity that has that name.


General


void setName( std::string name )


Specify a optional name string for an entity.  can be useful if you need to output entity names in a program.


std::string getName()


Returns the name string stored for the entity.


Trait


void setTrait( Entity* entity, Trait* trait, float amount, bool offset = false )


Set a trait amount for the entity and trait specified.  For example:
    Joe.setTrait(&Joe, &energy, 10);
The "offset" parameter allows the amount to be added to the existing amount instead of replacing it. If the current trait amount in this example is 10, offseting it by 10 would make the trait amount 20.


void setValue( Entity* entity, Trait* trait, float value, float standard = LAI_DEF_STANDARD )

void setValue( Entity* entity, Entity* traitOwner, Trait* trait, float value, float standard = LAI_DEF_STANDARD )

Set an entity's value toward a particular trait, which represents the importance of the trait to the entity.  The first variation assumes that the trait belongs to the same entity specified.  The second variation has an additional "traitOwner" parameter that allows the valued trait to belong to a different entity.  For example:
    Joe.setValue(&Joe, &energy, 1)   // sets Joe's energy value toward his own energy trait
    Joe.setValue(&Joe. &Martha, &energy, 1)  // // sets Joe's energy value toward Martha's energy trait

The "standard" parameter allows specifying a standard for the value.  By default, it is set as "1".   Represents how many units of the trait the value is applied to.  For example, a regular sized human may value a "strength" trait 1, with a standard of 1.  A giant may value its "strength" trait the same amount, 1, but it takes a much larger quantity of strength to be significant to the giant.  The giant's standard could be 100, for example.


float getTrait( Entity* entity, Trait* trait )


Returns the trait amount for the entity and trait specified


float getValue( Entity* entity, Trait* trait, bool standard = false )

float getValue( Entity* entity, Entity* traitOwner, Trait* trait, bool standard = false )

Returns the trait value for the entity specified.  If the "standard" is set as true, instead returns the value standard.  The first variation assumes that the entity who values is also the owner of the trait.  The second variation includes an additional "traitOwner" parameter to specify who the trait owner is if different from the entity who values.


Entity


void setParent( Entity* entity, Entity* parent, bool isParent = true )


Set if an entity has a "parent" entity.  Setting parent/child relationships for entities allows you to organize them in groups.  Doing so can help control the scope of action planning considerations.  For example:
    Joe.setParent(&Joe, &Human);
In this example, "Human" is added to Joe's parent list and "Joe" is added to Human's child list.


void setChild( Entity* entity, Entity* child, bool isChild = true )


Set if an entity has a "child" entity.  Setting parent/child relationships for entities allows you to organize them in groups.  Doing so can help control the scope of action planning considerations.
For example:
    Joe.setChild(&Human, &Joe)
In this example, "Joe" is added to Human's child list and "Human" is added to Joe's parent list.


bool getParent( Entity* entity, Entity* parent )


Returns if the entity specified in the "parent" parameter is a part of the first entity's parent list.


bool getChild( Entity* entity, Entity* child )


Returns if the entity specified in the "child" parameter is a part of the first entity's parent list.


Action


void setParent( Action* action, Action* parent, bool isParent = true )


Set if an action has a "parent" action.  Setting parent/child relationships for actions allows you to organize them in groups.  Doing so can help control the scope of action planning considerations.
For example:
    Joe.setParent(&Talk, &SocialAction)
In this example, "SocialAction" is added to Talk's parent list and "Talk" is added to SocialAction's parent list.


void setChild( Action* action, Action* child, bool isChild = true )

Set if an action has a "child" action.  Setting parent/child relationships for actions allows you to organize them in groups.  Doing so can help control the scope of action planning considerations.
For example:
    Joe.setChild(&SocialAction, &Talk)
In this example, "Talk" is added to SocialAction's child list and "SocialAction" is added to Talk's parent list.
     

void setMemberParent( Action* action, int member, Entity* parent = NULL )


Set an optional parent entity for a member of the action specified.  Can help control the scope of entities considered for the various members.  For example, in a "talk" action, you wouldn't want the actor entity to consider talking to a rock.  You could specify the "member parent" of member 1 as "Sentient".
    Joe.setMemberParent(&Talk, 1, &Sentient);


void setBasic( Action* action, int member, Trait* trait, float modify = LAI_DEF_SHIFT )


Can set basic information about what traits are modified by an action.  An entity has no awareness of the purpose of an action if it has not observed any records for it yet, so this permits a basic level of understanding.  For example, a "Rest" action may provide an increase of an "energy" trait.
    Joe.setBasic(&Rest, 0, &energy, 1)   // increases "energy" trait by 1
    Joe.setBasic(&Rest, 0, &stress, -1)   // decreases "stress" trait by -1


bool getParent( Action* action, Action* parent )


Returns if the action specified in the "parent" parameter is a part of the first action's parent list.


bool getChild( Action* action, Action* child )


Returns if the action specified in the "parent" parameter is a part of the first action's parent list.


bool getMemberParent( Action* action, int member, Entity* parent )


Returns the parent entity that an action member is set to, if there is one.


float getBasic( Action* action, int member, Trait* trait )


Returns basic trait modification information, how much a trait changes from the action.


float getAverage( Action* action, int member, Trait* trait )


Returns the average amount that a trait changes during an action, based on action records.


int getCorrelationCount( Action* action, int member, Trait* trait )


Returns the number of correlations that have been learned for an action based on action records
      

float getCorrelation( Action* action, int member, Trait* trait, int correlationNumber = 0, bool slope = false, bool intercept = false )


Returns information for a correlation that has been learned by action records.  By default, returns the correlation coefficient.  Slope and intercept flags allow optionally return slope or intercept instead.


int getCorrelationMember( Action* action, int member, Trait* trait, int correlationNumber = 0 )


Returns the action member that owns the trait that has a correlation with the trait that is modified by the action.


Trait* getCorrelationTrait( Action* action, int member, Trait* trait, int correlationNumber = 0 )


Returns the trait that has a correlation with the trait that is modified by the action.


int getRecordCount( Action* action )


Returns the number of records that have been observed and stored for the action.  Records are used to generate average and correlation data.


float getRecord( Action* action, int recordNumber, int memberNumber, Trait* trait, bool startAmount = false, bool endAmount = false )


Returns the amount a trait changes in an action record for the specified action member.  Can optionally specify "startAmount" or "endAmount" flags to instead return the start amount or end amount of the trait in the record.


Entity* getRecordEntity( Action* action, int recordNumber, int memberNumber )


Returns the entity that served as the action member for a particular record.


Logic


plan
( int steps = LAI_DEF_STEPS, int reactSteps = LAI_DEF_REACT_STEPS, Action* parentAction = NULL,
Entity* reactParentEntity = NULL, float minimumValue = LAI_MIN_ACTION_VALUE )

A key function in LifeAI.   Allows an entity to select a sequence of actions that would have the greatest utility to initiate.
Factors in current trait amounts, predicts changes that will occur to them, and weighs the outcome based on its value toward those traits.

By default, considers all possible actions on a step.  If actions have additional members, considers all possible entities that could fulfill that member role. 
For example, in a Talk action, will consider all possible entities that can talk to.

The parameters give greater control over the scope of this function.

The "steps" parameter specifies how many action steps need to be considered.  For example, on the first step an entity may choose a Rest action.  On the second step, the entity plans to do a Talk action or the Rest action again.  The trait changes of a step are factored in for the next step, so each step builds from each other, allowing strategic thinking. 
For example, by choosing Rest as the first action, an entity's "energy" trait is increased, which may help it perform better in the second step with a Talk action.

Notes:
- each additional step adds significantly more performance overhead.
- additional steps may add to intelligence, but only if the trait, entity, and action information available in the present are accurate.  Too many steps could result in plan choices that look too far out to the future with inaccurate or incomplete data.
- If no trait correlations exist for actions, there is no point doing more than 1 step, because the actor entity will repeatedly choose the same action for each step.

At the end of a step, and before the next step is considered, an entity can consider the "reactions" of other entities to the action it considered for the step.   This allows the ability to consider how action choices will influence the action choices of other entities.  Can specify how many action steps those reacting entities will consider with the "reactSteps" parameter.  If set to 0, no reaction consideration occurs.

Notes:
- Reacting entities consider all possible actions
- Since LifeAI does not yet have a dimension of "time", it assumes that actions take roughly the same amount of time to complete.  To emulate this time progression, LifeAI interleaves action steps with reaction steps.  Though more than one reaction step can be considered, the original actor entity only factors in the first reaction step's consequences as relevant before moving on to its next action step.

The "parentAction" parameter allows you to limit the scope of actions considered.  For example, if there is a parent action called "SocialAction", can put this in the parameter.  The acting entity will then only consider child actions to SocialAction, such as "Greet", "Talk", "PlayTogether", etc...

The "reactParentEntity" parameter allows you to limit the scope of entities considered for reactions.  For example, if multiple locations exist, may want to limit reaction entities to a "SameArea" parent entity.  It will then only consider the reactions of child entities that reside in the same same area.

The "minimumValue" parameter allows you to set a bare minimum value that plan options much meet to be accepted.  Ideally, it is only rational to plan on actions that have an end net positive value outcome.  However, consider a scenario where an entity is forced to choose between two bad actions, and must choose the "lesser of two evils".  You can force this by setting the "minimumValue" parameter to a negative number.


void startAction( Entity* entity = NULL, Action* action = NULL, Entity* member1 = NULL,
Entity* member2 = NULL, Entity* member3 = NULL )

This function is central to the learning system used by LifeAI, that leads to averages and correlations.  Represents an observation of an entity initiating an action.  Captures the trait information of the entities involved at the start of the action, to later be inserted in an action record.
Parameters specify the entity initiating the action, as well as other entities that may be involved as members.

If no parameters are specified, defaults to starting the action that is in the entity's plan.  For example:
    Joe.startAction() will start Joe's plan action for his first step, if he has one.

An entity can only start one action at a time.  Can not initiate multiple simultaneous actions.  Calling "startAction" twice over-writes the previous start action information.


void endAction( Entity* entity = NULL )


After an action observation is initiated with "startAction", "endAction" completes the observation.  Start and end trait data is compared and stored as an action record, to be used in the LifeAI learning system.  Only processes if a start action was initiated.


int getPlanCount()


Returns the number of plan steps that were determined by the "plan" function.  Each step represents a sequential action preference.


Action* getPlan( int step = 0 )


Returns the action selected for a specified plan step.  Step numbers start at 0.


Entity* getPlanEntity( int step = 0, int member = 0 )


Returns the entity selected for a specified plan step, for a specified action member.


float getPlanValue( int step = 0, bool total = false )


Returns the overall value calculated for the specified plan step.  If "total" parameter is set to true, returns the accumulated value from the previous steps to this step.


Action* getStartAction( Entity* entity = NULL )


Returns the action that was set with "startAction" for an entity.


Entity* getStartEntity( Entity* entity, int member = 0 )


Returns the entity that was set with "startAction" for a specified action member.