Difference between revisions of "Ambient behaviour"

Latest revision as of 00:16, 10 December 2013

Ambient behaviour begins when the player moves within 50m of a creature and ceases when the player remains more than 50m away for at least 40s. Ambient behaviour alternates between a movement phase and an animation phase, simulating a bubble of activity around the player. In a movement phase, the creature (optionally) moves to a new destination (typically a waypoint but it could be any object) and turns to face the same direction as the destination object. In an animation phase, the creature (optionally) performs one or more animations either in sequence or at random. Exact behaviour is controlled by local variables set on either the creature instance or template (see table below). All other local variables with the prefix AMBIENT_* are used internally by the ambient behaviour system (see script sys_ambient_h.nss) and should not be manually modified. Never directly modify AMBIENT_* local variables at run time using SetLocalInt - always use the functions Ambient_Start, Ambient_Stop, Ambient_OverrideBehaviour, and Ambient_RestoreBehaviour instead. Ambient behaviour is persisted when a game is saved and automatically resumes when a game is loaded.

Local Variables (var_creature)

ambient_anim_patterns 2da

The actions used in an animation phase are listed in the ambient_anim_patterns 2da. Each row defines an animation pattern, consisting of up to thirteen actions. Each action is composed of an animation (left of the decimal) and the number of loops it is played (right of decimal). For example, 619.02 will play a sleeping loop animation twice and 619.99 will play an infinitely looping sleeping animation. Non-looping animations require no loop-count (i.e. decimal) component. The list of all available animations is located in ANIM_ 2da.

sys_ambient_h

The script sys_ambient_h contains the implementation of the ambient behaviour system. The AMBIENT_* local variables should never be directly modified at run-time. Instead, use the following functions to customize a creature's ambient behaviour through script.

// Normally this function is called automatically to begin or resume  ambient behaviour when a 
// creature perceives the player. However, it can be called explicitly to force a creature to begin 
// performing ambient behaviour or, if nAmbientEnable is 1, to enable ambient behaviour on a creature. 
void Ambient_Start(object oCreature = OBJECT_SELF, int nAmbientEnable = 0, int nMovePattern = 0, string sMovePrefix = "");
 
// Normally this function is called automatically to pause ambient behaviour after the party has 
// been out of the creature's sight for a while. However, this function can be used to force a 
// creature to temporarily cease ambient behaviour. Note that the creature will automatically  
// resume ambient behaviour when it perceives the player again. 
void Ambient_Pause(object oCreature = OBJECT_SELF, int bCheckVisibility = TRUE);
 
// Turns off ambient behaviour on a creature. The creature will resume ambient behaviour only 
// after Ambient_Start() is called.
void Ambient_Stop(object oCreature = OBJECT_SELF);
 
// Overrides the ambient animation pattern and animation frequency defined by the creature's template. 
void Ambient_OverrideBehaviour(object oCreature, int nAnimPattern, float fAnimFreq);
 
// Restores a creature's ambient animation behaviour to that defined in the creature's template.
void Ambient_RestoreBehaviour(object oCreature);

Overriding Ambient Behaviour

Customising Ambient Behaviour

Animations

New ambient_anim_patterns can be added as an M2DA.

Provisionally, it seems that some animations are cutscene-only. They don't work when scripted. This requires further investigation and documentation, as there is a bug which may account for some or all of this.

Movement

The system doesn't provide an explicit hook for a user-defined movement pattern.

However, it does support walking once through a set of waypoints.

We can implement any custom movement pattern as several sets of waypoints (each with its own prefix).

For example, if we want to walk from A to B, then C or D and E depending on some condition, we might define the sets as ap1 (A, B), ap2 (C) and ap3 (D, E).

We tell Ambient AI to walk waypoints prefixed ap1. On completion, we tell it to walk ap2 or ap3, depending on the condition.

Intercepting the Ambient AI is tricky. By default, EVENT_TYPE_COMMAND_COMPLETE is handled directly by the rules_core script, which kicks off the next Ambient AI action before we can stop it. Presumably, this is for performance reasons.

Set the AI_CUSTOM_AI_ACTIVE variable (see Custom AI) on the creature template to generate a new event (EVENT_TYPE_CUSTOM_COMMAND_COMPLETE) which can be handled in the creature script. If the creature is a non-combatant, CAI_INACTIVE (1) works fine.

Using AMBIENT_MOVE_ONCE, when the final waypoint is reached, Ambient AI will reset the move pattern to AMBIENT_MOVE_NONE before this new event fires.

We can then trigger the next set of waypoints by including a snippet like this in our creature script:

        case EVENT_TYPE_CUSTOM_COMMAND_COMPLETE:
        {
         object oCreature = OBJECT_SELF;
 
         // Do nothing unless we have arrived at our destination 
 
         if (GetLocalInt(oCreature, AMBIENT_MOVE_PATTERN) == AMBIENT_MOVE_NONE)
            {     
              int    nLastCommandType = GetEventInteger(ev, 0);
              int    nCommandStatus   = GetEventInteger(ev, 1);
              int    nLastSubCommand  = GetEventInteger(ev, 2);
              object oLastTarget      = OBJECT_INVALID;
              object oBlockingObject  = GetEventObject(ev, 2);  
 
              // Check which path just finished
 
              if (GetLocalString(oCreature, AMBIENT_MOVE_PREFIX) != "ap1_<tag>") break;
 
              // Stop Ambient AI for good order
 
              Ambient_Stop(oCreature);
 
              // Fix bug in Ambient_Start
 
              SetLocalInt(oCreature, AMBIENT_MOVE_COUNT, AMBIENT_MOVE_COUNT_INVALID); 
              SetLocalInt(oCreature, AMBIENT_MOVE_STATE,  AMBIENT_MOVE_NEXT);   
 
              // Restart on new path           
 
              Ambient_Start(oCreature, AMBIENT_SYSTEM_ENABLED, AMBIENT_MOVE_ONCE, "ap2_<tag>");                
            }
 
          bEventHandled = TRUE;
          break;
        }

Note that when using any movement pattern other than AMBIENT_MOVE_ONCE, Ambient AI will issue the next movement command before EVENT_TYPE_CUSTOM_COMMAND_COMPLETE fires.

Bugs

Changing the movement path for a creature is bugged.