ScriptGoal

From MyGamingTalk
Revision as of 08:02, 13 February 2023 by Palota (talk | contribs) (1 revision imported)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Script Reference Script Goal

ScriptGoal Properties

Name

The name of the script goal. Important for other scripts to refer to by name, and the name it is displayed under in the Debug Window 

this.Name = "MyGoalName";

Parent

The name of the parent goal. This should be set up once in the script and left alone. It controls where in the behavior tree the goal is inserted. The location of the goal in the state tree effects how it is evaluated.

Users should stick to one of the following 2 parents.

  • HighLevel - Puts the goal under the HighLevel parent. Because the goal is under the HighLevel state, only one state at a time can run. This is useful for goals that take control of the bot, that shouldn't be interrupted by other script goals or built in goals.
  • LowLevel - Puts the goal under the LowLevel parent. All states under the LowLevel state are run simultaneously, and so is a good location for scripts that control things that don't necessarily take total control over the bot, or don't wish to interrupt the execution of other goals. Some examples might be calling for medic, calling for ammo, most communication scripts.
this.Parent = "HighLevel";

InsertBefore

It controls where in the behavior tree the goal is inserted. InsertBefore property is ignored if Parent has been set.

InsertAfter

It controls where in the behavior tree the goal is inserted. InsertAfter property is ignored if Parent or InsertBefore has been set.

Disable

Enables/Disables the goal for consideration. The goal will no longer be considered for execution. Disabled goals have specific coloring in the Debug Window 

this.Disable = true;

AimVector

This Vector3 is used by any active aim request the script goal has registered. You usually do not need to use this property directly, because function AddAimRequest sets this property.

AlwaysRecieveEvents

Normally goals receive events only when active. Setting this to true will allow the goal to receive events even when it's not running. This is useful for when you want to have the goal sit idle and only activate when receiving a certain event, or you want to track and store information in the goal from events. 

this.AlwaysRecieveEvents = true;

Events

Accesses the Events table of the goal, in order to set up script functions that will be called when the bot receives events. By default, goals only receive events when they are active. This can be overridden with AlwaysRecieveEvents, which will allow goals to receive events even when not active. 

 this.Events[EVENT.FEEL_PAIN] = function(Inflictor, PreviousHealth, CurrentHealth)
 {
   whoDoneIt = GetEntName(Inflictor);
   print( format("%s: %s Hurt me: Was %d, now %d", 
    this.Bot.GetName(), whoDoneIt, PreviousHealth, CurrentHealth) );
 };

Bot

This provides an accessor to the bot that is running the goal. The 'this' within script goals is always the script goal itself, so in the frequent case of needing to access the bot, use this property. 

this.Bot.Say("Wassup");

Priority

Priority is a property rather than a return value of GetPriority in order to support the useful threading nature of script goals. It is possible to completely leave out a GetPriority function, and set the priority through this property somewhere else, such as in an event callback. This property will automatically be reset internally when the state exits, to prevent a script goal from activating in a loop from the user forgetting to reset the Priority. 

this.Priority = 1;

SkipGetPriorityWhenActive

Set SkipGetPriorityWhenActive to true if function GetPriority should not be called while the goal is active.

GetPriorityDelay

Delay in seconds between GetPriority calls. Default is 0.

MapGoal

Current MapGoal or null if the script goal is not active. This property is not set automatically. You must assign map goal to this property in GetPriority and clear it in Exit.

AutoReleaseAim

Function ReleaseAimRequest is automatically called in Exit. Default is true.

AutoReleaseWeapon

Function ReleaseWeaponRequest is automatically called in Exit. Default is true.

AutoReleaseTrackers

Function Trackers::Reset is automatically called in Exit. Default is true.

AutoFinishOnUnAvailable

The goal is automatically finished if current MapGoal is not available. Default is true.

AutoFinishOnNoProgressSlots

The goal is automatically finished if MarkInProgress has not been called yet and MapGoal has no TRACK_INPROGRESS slots available. Default is true.

AutoFinishOnNoUseSlots

The goal is automatically finished if MarkInUse has not been called yet and MapGoal has no TRACK_INUSE slots available. Default is true.

AutoAdd

Set AutoAdd to false if the script should not be loaded for every map, because it's deprecated or used only for debugging (RideTram, TestEvents, ...).

DebugString

Debug strings are displayed if you use command "/bot debugbot all fpinfo" and then spectate bots. If DebugString is null, MapGoal name is displayed.

Debug

Set this property at the beginning of gm file so that all your debug messages or debug drawing can be easily enabled or disabled.

Commands

Table of console commands which are executed on the script goal for every bot. 

 this.Commands["command_name"] = {
  Func = function( _params )
  { 
  },
  Help = { "description" },
 };

ScriptGoal Callbacks

These functions are available only in 0.7 and later.

Initialize

This function is called exactly once per bot, when the bot is added and initialized. It is typically used to perform one time initialization code.

Example: 

 this.Initialize() = function()
 {
 };

OnSpawn

This function is called every time the bot spawns. Spawning in Omni-bot means any time the bot re-enters his Main active state. This could mean an actual respawn, a revival from an incapacitated state, or something similar.

Example: 

 this.OnSpawn() = function()
 {
 };

GetPriority

This function is most often the place to evaluate whether you want the script goal to run. Take care in the complexity of the code here, as it is called pretty often, and can be a source of considerable performance overhead.

Example: 

 this.GetPriority() = function()
 {
 };

Enter

This function is called when a state is chosen to run, right before it begins running. This function is only called once when the state enters, and will not be called again until the state is exited.

Example: 

 this.Enter() = function()
 {
 };

See Also: Exit

Exit

This function is called when a state finishes running, or is overridden by a higher priority state. It is often used to release aim or weapon requests that were used by the goal.

Example: 

 this.Exit() = function()
 {
 };

See Also: Enter

Update

This function is the meat of a script goal. Once a goal is chosen to run, and Enter is called, the Update function begins getting called at frequent regular intervals. The state stays active until another goal overrides it, or until Finished is called, after which the Exit function is called.

Example: 

 this.Update() = function()
 {
   // do stuff
   this.Finished(); // when we're done running
 };

See Also: Enter, Exit

OnPathThrough

This function is called if bot comes to waypoint which has paththrough property set and its value is goalName:data. Paththrough is activated if OnPathThrough function returns true.

Example: 

 this.OnPathThrough = function(data)
 {
  navigation = Map.Navigation[data];
  if(navigation)
  {
   this.CurrentNavigation = data;
   return true;
  }
  this.CurrentNavigation = null;
  return false;
 };

ScriptGoal Functions

These functions are available only in 0.7 and later.

AddFinishCriteria

Finish Criteria are expressions set up from script that will be evaluated constantly in the code and when they are satisfied will cause the script goal to abort. These are useful when your script does alot of asynchronous operations(like Goto), but you want a way to abort the script goal, even if the main update script happens to be in an asynchronous or blocked call, sleep or yield.

Parameters: (subject, expression, value[optional])

Parameters: (expression, value[optional])

Subject

Subject must be an entity, if no entity is provided as the first parameter, it is assumed that the 2nd version of the function is called, which takes only and expression and an optional value. The need for a value is determined by what the expression actually is.

Expression

Expression is a string containing 1 or more keywords that use a natural syntax for defining the conditions of the criteria. Additionally, some keywords expect an operator to be defined

Keyword Operator Required Value
deleted No entity
health Yes health value to compare against(float or int)
hasentflag No entity flag to compare against. use not to negate test
weaponcharged No weapon Id(integer)
weaponequipped No weapon Id(integer)
weaponhasammo No weapon Id(integer)
velocity Yes vector3 velocity to compare against, OR float magnitude of velocity to compare against(speed)
Valid Operators
  • lessthan
  • <
  • greaterthan
  • >
  • equals
  • ==

In addition, some expressions can contain negation keywords in order to check for the negative of an expression, such as 

 this.AddFinishCriteria(this.TargetEntity,"not hasentflag",ENTFLAG.DEAD); // as soon as the entity does not have the dead flag

Returns: true if criteria was created, false if not

Example: 

 this.AddFinishCriteria(this.TargetEntity,"deleted"); // finish the goal of the target is deleted
 this.AddFinishCriteria(this.TargetEntity,"health lessthan",1); // or if they are dead(health <= 1)
 this.AddFinishCriteria(this.TargetEntity,"hasentflag",ENTFLAG.LIMBO); // or if they tap out

ClearFinishCriteria

Deletes finish criteria.

Parameters: (clearpersistent[optional, default false])

Returns: none

Finished

Notifies the goal that it is finished running. This function is normally called from the Update function when the goal is desired to finish.

Parameters: (none)

Returns: none

Example: 

 this.Finished();

LimitTo

This function limits script execution based on a true value being returned from a user defined function. This function is useful if scripts should only be run based on some external logic; like a Map variable setting.

Parameters: (function, delay, onlyactive[optional - default false])

Returns: none

LimitTo functions are script functions that are called at user defined intervals that can be used to update from script whether or not the script goal should be able to run or not. Returning false from this function effectively blocks the script goals ability to activate. It will remain in this state as long as the LimitTo function is defined. The 2nd parameter controls how often the callback is performed. Calling script functions too often can adversely effect performance, so it is recommended to choose a delay that is as infrequently as you can get away with. The 'onlyactive' parameter is optional and defaults to false. If this parameter is set to true, the LimitTo function callback will ONLY be performed when the script goal is active. By default the LimitTo function will be called whether the goal is active or not, and returning false will prevent the goal from being able to activate. Passing true as the 'onlyactive' flag means the goal can activate, and only then is the LimitTo function called. This is useful when you need to check more information regarding specific targets of the goal to validate whether the goal should continue running. This callback is effectively a way to define your own finish criteria. It is recommended that you only use LimitTo callbacks when FinishCriteria can't be used, since FinishCriteria are much faster and don't involve frequent calls into script. LimitTo functions might commonly be used to check the status of a map goal or some other world state that the goal relies on.

Example: 

 //This function is typically set up in this.Initialize()
 this.LimitTo(Map.SomeFunction, 1.0); //Call Map.SomeFunction every second
 this.LimitTo(NULL); //clear the function
  
 //The script goal object is referenced in the passed function as 'this'
 Map.SomeFunction = function()
 {
      if ( Map.SomeVariable == false )
          { this.Disable; } //disable the script
      else
          { return true; } //allow the script to run
 };

LimitToClass

This function will only allow the script goal to be created if the owning bot is one of the classes provided. This is much more efficient than checking class in script in common cases where a goal only applies to a certain class of bot.

Parameters: (classId, ...) Any number of class Ids

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToClass(CLASS.MEDIC);
 this.LimitToClass(CLASS.MEDIC, CLASS.ENGINEER);

LimitToNoClass

This function will only allow the script goal to be created if the owning bot is NOT one of the classes provided. This is much more efficient than checking class in script in common cases where a goal only applies to a certain class of bot.

Parameters: (classId, ...) Any number of class Ids

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToNoClass(CLASS.MEDIC);
 this.LimitToNoClass(CLASS.MEDIC, CLASS.ENGINEER);

LimitToTeam

This function will only allow the script goal to be created if the owning bot is one of the teams provided. This is much more efficient than checking team in script in common cases where a goal only applies to a certain team of bots.

Parameters: (teamId, ...) Any number of class Ids

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTeam(TEAM.BLUE);
 this.LimitToTeam(TEAM.BLUE, TEAM.RED);

LimitToEntityFlag

This function will only allow the script goal to be created if the owning bot has one or more entity flags set. This is much more efficient than checking entity flags in script in common cases where a goal only applies to specific cases where the bot has certain entity flags.

Parameters: (ent flag, ...) Any number of entity flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToEntityFlag(ENTFLAG.INWATER);
 this.LimitToEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);

LimitToNoEntityFlag

This function will only allow the script goal to be created if the owning bot does not have one or more entity flags set. This is much more efficient than checking entity flags in script in common cases where a goal only applies to specific cases where the bot does not have certain entity flags.

Parameters: (ent flag, ...) Any number of entity flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToNoEntityFlag(ENTFLAG.INWATER);
 this.LimitToNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);

LimitToNoPowerup

This function will only allow the script goal to be considered if the owning bot does not have the given powerups.

Parameters: (powerup flag, ...) Any number of power up flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE);
 this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);

LimitToNoTarget

This function will only allow the script goal to be considered if the owning bot does not have a target. This is much more efficient than checking for a target in the GetPriority function in script in cases where the bot should not have a target. The goal will not be evaluated unless the bot does not have a target.

Parameters: none

Returns: none

Example: 

 // This function takes no parameters.
 this.LimitToNoTarget();

LimitToPowerUp

This function will only allow the script goal to be created if the owning bot has one or more power up flags set. This is much more efficient than checking power up flags in script in common cases where a goal only applies to specific cases where the bot has certain power up flags.

Parameters: (powerup flag, ...) Any number of power up flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToPowerUp(ENTFLAG.INVINCIBLE);
 this.LimitToPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);

LimitToWeapon

This function will only allow the script goal to be created if the owning bot has one or more weapons set by this function. This is much more efficient than checking the bots weapons in script in common cases where a goal only applies to specific cases where the bot has a certain weapon.

Parameters: (weapon Id, ...) Any number of weapon Ids

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToWeapon(WEAPON.MOBILE_MG42);
 this.LimitToWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);

LimitToTargetClass

This function will only allow the script goal to be considered if the owning bot has a target of a specified class. This is much more efficient than checking class in the GetPriority function in script in cases where a goal only applies to specific cases where the bots target is a specific class. The goal will not be evaluated unless the bot has a target and the target is on one of the provided classes.

Parameters: (classId, ...) Any number of target classes

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTargetClass(CLASS.ANYPLAYER); // don't run unless we have any player class
 this.LimitToTargetClass(CLASS.ENGINEER, CLASS.MEDIC); // look for specific classes

LimitToTargetTeam

This function will only allow the script goal to be considered if the owning bot has a target on a specified team. This is much more efficient than checking team in the GetPriority function in script in cases where a goal only applies to specific cases where the bots target is on a specific team. The goal will not be evaluated unless the bot has a target and the target is on one of the provided teams.

Parameters: (teamId, ...) Any number of teams

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTargetTeam(TEAM.RED); // don't run unless our target is on red team

LimitToTargetPowerUp

This function will only allow the script goal to be considered if the owning bot has a target with one or more powerups. This is much more efficient than checking powerups in the GetPriority function in script in cases where a goal only applies to specific cases where the bots target has a powerup. The goal will not be evaluated unless the bot has a target and the target is on one of the provided powerups.

Parameters: (powerup id, ...) Any number of power up flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTargetPowerUp(POWERUP.QUADDAMAGE); // don't run unless our target has quad damage
 this.LimitToTargetPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);

LimitToTargetNoPowerUp

This function will only allow the script goal to be considered if the owning bot has a target without one or more powerups. This is much more efficient than checking powerups in the GetPriority function in script in cases where a goal only applies to specific cases where the bot's target hasn't a powerup. The goal will not be evaluated unless the bot has a target and the target doesn't have one of the provided powerups.

Parameters: (powerup id, ...) Any number of power up flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTargetNoPowerUp(POWERUP.QUADDAMAGE); // don't run if our target has quad damage
 this.LimitToTargetNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);

LimitToTargetEntityFlag

This function will only allow the script goal to be created if the target bot has one or more of the entity flags set. This is much more efficient than checking entity flags in script in common cases where a goal only applies to specific cases where the bot has certain entity flags.

Parameters: (ent flag, ...) Any number of entity flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTargetEntityFlag(ENTFLAG.INWATER);
 this.LimitToTargetEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);

LimitToTargetNoEntityFlag

This function will only allow the script goal to be created if the target bot does not have one or more of the entity flags set. This is much more efficient than checking entity flags in script in common cases where a goal only applies to specific cases where the bot does not have certain entity flags.

Parameters: (ent flag, ...) Any number of entity flags

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER);
 this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);

LimitToTargetWeapon

This function will only allow the script goal to be created if the bots has one or more weapons set by this function. This is much more efficient than checking the bots weapons in script in common cases where a goal only applies to specific cases where the bot's target has a certain weapon.

Parameters: (weapon Id, ...) Any number of weapon Ids

Returns: none

Example: 

 // This function can take any number of parameters.
 this.LimitToTargetWeapon(WEAPON.MOBILE_MG42);
 this.LimitToTargetWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);

LimitToRole

This function will only allow the script goal to be created if the owning bot has one of the roles provided.

Parameters: (roleId, ...) Any number of role Ids

Returns: none

Example: 

 this.LimitToRole(ROLE.DEFENDER);

IsActive

Checks if the script goal is currently active. An active script goal means it is currently running. This check is useful mostly in cases where you want an active script goal to remain active and not necessarily keep performing complex checks in its GetPriority function.

Parameters: (none)

Returns: true if active, false if not

Example: 

 this.GetPriority = function()
 {
   if(this.IsActive())
   {
     return 1.0;
   }
   else
   {
     // do some other check
   }
 };

Goto

Tells the bot to go to a specific location, planning and running a path if necessary. This function is synchronous.

The first parameter can be a table of positions, bot will choose destination which has the shortest path.

Bot will walk if the last parameter is {MoveMode = MoveMode.Walk}.

Parameters: (Vector3 position, tolerance, options[optional])

Parameters: (table of Vector3 positions, tolerance, options[optional])

Returns: EVENT.PATH_SUCCESS or EVENT.PATH_FAILED

Example: 

 wpinfo = table();
 wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
 if( this.Goto(wpinfo.position, wpinfo.radius) == EVENT.PATH_SUCCESS )
 {
     print("Made it!");
 }

GotoAsync

Tells the bot to go to a specific location, planning and running a path if necessary. This function is asynchronous. Typically a script would block after calling this to wait for a success or failure message.

Parameters: (Vector3 position, tolerance, options[optional])

Returns: none

Example: 

 wpinfo = table();
 wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
 this.GotoAsync(wpinfo.position, wpinfo.radius);
 if( block(EVENT.PATH_SUCCESS, EVENT.PATH_FAILED) == EVENT.PATH_SUCCESS )
 {
     print("Made it!");
 }

GotoRandom

Goto random destination.

Parameters: (tolerance, options[optional])

Returns: EVENT.PATH_SUCCESS or EVENT.PATH_FAILED

GotoRandomAsync

Goto random destination (asynchronous).

Parameters: (tolerance, options[optional])

Returns: none

RouteTo

RouteTo is similar to Goto, but bots use routes which are defined for map goal. Routes are used only if bot is within radius of any ROUTE goal.

Parameters: (mapGoal, tolerance, options[optional])

Returns: EVENT.PATH_SUCCESS or EVENT.PATH_FAILED

Stop

Interrupts any active Goto and signals PATH_FAILED.

Parameters: none

Returns: none

DidPathSucceed

Checks if the last Goto command succeeded. Success means the bot has reached the end of the desired path. Typically a goal will block on EVENT.PATH_SUCCESS or EVENT.PATH_FAILED events. DidPathSucceed and DidPathFail are included for cases where the script wishes to remain active and doing something during the path traversal, and it can poll the path success/failure during. If neither function returns true, then the bot should be moving along the path normally.

Parameters: none

Returns: true if path succeeded, false if not

Example: 

 if(this.DidPathSucceed())
 {
 }

See Also: Goto, DidPathSucceed

DidPathFail

Checks if the last Goto command failed. Failure means the path was either blocked(no path exists), or the bot has gotten stuck on the way. Typically a goal will block on EVENT.PATH_SUCCESS or EVENT.PATH_FAILED events. DidPathSucceed and DidPathFail are included for cases where the script wishes to remain active and doing something during the path traversal, and it can poll the path success/failure during. If neither function returns true, then the bot should be moving along the path normally.

Parameters: none

Returns: true if path failed, false if not

Example: 

 if(this.DidPathFail())
 {
 }

See Also: Goto, DidPathSucceed

AddAimRequest

Adds a priority based aim request into the bots aiming system. Aim requests are favored based on their priority, with the highest priority aim request chosen at any given point. It is a much simpler and easier to manage setup in the cases of many competing goals that wish to control the bots aim. Each goal can add an aim request and will recieve notifications when the bot chooses and executes their request. This functions works together with the AimVector property to allow setting the aim type at any point. The script can recieve notification of a successful aiming by blocking on the EVENT.AIM_SUCCESS event.

Aim requests can be viewed in the Debug Window under the Aimer state. They will take on the name of the script goal they were added in.

Parameters: (priority, aim type<optional, default position>, aim position<optional>)

Priority

Most normal goals use a Priority.High priority, which leaves 2 higher levels of priority usable by scripts or important goals.

Priority determines how to select a request when there are multiple requests active. Higher priorities are selected over lower priorities.

  • Priority.Zero
  • Priority.Min
  • Priority.Idle - FollowPath
  • Priority.VeryLow
  • Priority.Low - CAMP, ESCORT, RIDE, MOUNT, LookAround, ...
  • Priority.LowMed - AttackTarget
  • Priority.Medium - CALLARTILLERY, MOBILEMORTAR, ...
  • Priority.High - BUILD, DEFUSE, GRENADE, REVIVE, SWITCH, ...
  • Priority.VeryHigh
  • Priority.Override

Aim Types

  • movedirection - Face in the direction of movement. Useful if you want to override the bots normal combat aiming, as in for a disguise goal where you don't want them to engage the target.
  • facing - Face a given facing (direction) vector. In this case AimVector represents a facing vector.
    • (1,0,0) - east, (-1,0,0) - west
    • (0,1,0) - north, (0,-1,0) - south
    • (0,0,1) - up, (0,0,-1) - down
  • position - Face a given position vector. In this case AimVector represents a point in the 3D map space.

If one of the above is not specified, the aim request is a positional request, and the AimVector of the script goal will be used as a raw position to aim at.

Returns: none

Example: 

 aimPos = someAimPosition;
 aimPos2 = someAimPosition2;

 this.AddAimRequest(Priority.High, "movedirection"); // requests the bot to face along its move direction at a 0.8 priority
 // OR
 this.AddAimRequest(Priority.High); // leave off optional parameters, defaults to AimPosition, so set it
 this.AimVector = aimPos; // this can be called at any time in the script goal

 if(block(EVENT.AIM_SUCCESS) == EVENT.AIM_SUCCESS)
 {
    // we're on target, do something cool
 }

See Also: ReleaseAimRequest

ReleaseAimRequest

This function will release the Aim Request within the script goal; allowing other potential aim requests to have control.

Parameters: none

Returns: none

Example: 

 this.ReleaseAimRequest();

See Also: AddAimRequest

AddWeaponRequest

Adds a priority based weapon equip request into the bots weapon system. Weapon requests are favored based on their priority, with the highest priority request chosen as the desired weapon. It is a much simpler and easier to manage setup in the cases of many competing goals that wish to control the bots equipped weapon. Each goal can add an weapon request and will receive notifications when the bot chooses and executes their request.

Weapon requests can be view in the Debug Window under the WeaponSystem state. They will take on the name of the script goal they were added in.

Parameters: (priority, weapon Id)

Priority

Most normal goals use a Priority.High priority, which leaves 2 higher levels of priority usable by scripts or important goals.

Priority determines how to select a request when there are multiple requests active. Higher priorities are selected over lower priorities.

  • Priority.Min
  • Priority.Idle
  • Priority.VeryLow
  • Priority.Low
  • Priority.Medium
  • Priority.High
  • Priority.VeryHigh
  • Priority.Override

Returns: none

Example: 

 this.AddWeaponRequest(Priority.High, WEAPON.MEDKIT);

See Also: ReleaseWeaponRequest

ReleaseWeaponRequest

This function will release the weapon request within the script goal; allowing other potential weapon requests to have control.

Parameters: none

Returns: none

Example: 

 this.ReleaseWeaponRequest();

See Also: AddWeaponRequest

BlockForWeaponChange

This function provides specialized script thread blocking functionality to wait for a weapon change to a certain weapon. This function takes the place of a call to block in the case you want to wait until the bot switches to a specific weapon.

Parameters: (weaponId)

Returns: none

Example: 

 this.BlockForWeaponChange(WEAPON.MEDKIT);
 this.Say("Medkit Equipped!");

BlockForWeaponFire

BlockForVoiceMacro

QueryGoals

Finds goals available for this bot and stores them in the first table parameter. The previous table content is cleared since omni-bot 0.84.

The last optional parameter is table of parameters to filter result (NoFilters, Group, Role, Team, SkipDelayed, SkipNoInProgress, SkipNoInUse, SkipInUse) or sort result (parameter Sort, values are "none", "priority", "name", "random", default is "priority").

Parameters: (table, goal type hash, params[optional])

Parameters: (table, table of goal type hashes, params[optional])

Parameters: (table, expression, params[optional])

Returns: count of goals returned in table

Example: 

 count = this.QueryGoals(this.Bot.QueryGoalsTable, 0xc9326a43);
 count = this.QueryGoals(this.Bot.QueryGoalsTable, "BUILD_.*");

BlackboardDelay

Parameters: (time, mapGoal or serialNumber[optional])

Returns: none

Example: 

 this.BlackboardDelay(10);

BlackboardIsDelayed

Parameters: (mapGoal or serialNumber)

Returns: true if goal has been found on blackboard

Example: 

 if (this.BlackboardIsDelayed(serial))

MarkInProgress

Parameters: (mapGoal[optional])

Returns: true if empty slot has been found and marked

Example: 

 if (!this.MarkInProgress()) {
   this.BlackboardDelay(5);
   this.Finished();
 }

MarkInUse

Parameters: (mapGoal[optional])

Returns: true if empty slot has been found and marked

Example: 

 if (!this.MarkInUse()) {
   this.BlackboardDelay(5);
   this.Finished();
 }

WatchForMapGoalsInRadius

ClearWatchForMapGoalsInRadius

WatchForEntityCategory

Parameters: ( { Radius, Category, RequireLOS[optional, default 0] } )

Returns: none

Example: 

 this.WatchForEntityCategory({
   Radius = 350,
   Category = CAT.PROJECTILE,
   RequireLOS = TRACE.VISIBLE
 });

DelayGetPriority

ForkThread

KillThread

Signal

Script Goal Threading

Script goals have been designed to be friendly to script threading, by providing some built in functionality to make it easier to manage multiple threads to be associated with the script goal.

The script goal keeps track of the thread created when calling all the following functions.

  • Initialize
  • OnSpawn
  • GetPriority
  • Enter
  • Exit
  • Update

You may use thread functions (block, yield, sleep), in any of the script goal functions, though you must understand that for efficiency, and to prevent runaway threads, the script goal will internally kill the threads associated with the function callbacks at certain times.

Currently

  • All threads will be killed when the state exits.
  • All threads will be killed when the state is disabled. See Disable
  • All threads will be killed when the state becomes unselectable. This is normally due to the limit functions.

Note that this only applies to the thread that is created for the function calls themselves. If you really need a thread to run longer than these specifications allow, you can create your own thread normally with the thread() function. It is highly recommended that you script your goal within these functions, as it is easy to leak threads when creating them arbitrarily.

Script Goal Performance

Executing script is much much slower than executing native code, so you should be aware that a script can have significant adverse effects on the performance of the bot as a whole. Here are some tips to keep performance as high as possible with script goals.

  • Only define what you need - None of the callback functions are required, so if you don't use them, don't define them. It is wasteful to have an empty function defined. If you don't need an Enter function, leave it out, if you don't need an Update function, leave it out. Same for Exit, GetPriority, Initialize.
  • Use limit functions as much as possible - If the goal should only be considered for certain player classes, or for bots with certain powerups or entity flags, or for when the bot has a target that matches similar specific flags, use the Limit functions to set that up. They are much much faster than checking those properties in the GetPriority function. If the limit functions fail, the script will never be called, which is a huge optimization.
  • Use thread functions - Normally, GetPriority is called often. You can control this behavior by using thread functions to keep a thread running, and delay priority evaluations with a loop and calls to sleep. GetPriority will not be called if there is still an active GetPriority thread.
  • Keep your GetPriority function as lightweight as possible - The less work it does the better, because GetPriority is called frequently by the bot. This is especially important if the goal is placed under the LowLevel parent because all child states under LowLevel are evaluated and allowed to run simultaneously.
  • Ditto for the Update function - The same applies to the Update function especially. Keep it as simple as possible to achieve the desired behavior, and use thread functions.
  • Cache as much as possible - Take advantage of the fact that Initialize is called only once when the bot is added. Use this function to cache values the script goal might need. For example, if the script goal does things based on specific waypoints, it would be expensive to call functions like Wp.GetWaypointByName() in the priority or update functions. Instead collect all you might need up front in the Initialize function and store them in a table on the script goal so you have faster access to them later.
  • Use events, and block() as much as possible - Most common operations that previously required expensive loops to perform have been converted to events. Choosing a weapon, aiming a weapon, going to some location, etc. Most can be followed by a call to block() which will suspend the execution of the script until the event is recieved. This is the single easiest to use and most useful for performance features available. See BlockForWeaponChange, Goto, AddAimRequest.
  • Beware of loops - Be careful when looping, as they can silently cause large performance drains. Be wary of how much work is being done in a loop, and on how many elements. Expensive functionality can be updated less often, or split up over time. Use yield() or sleep(x) within loops to spread out the calculations over time.
Retrieved from "http://mygamingtalk.com/wiki/index.php?title=ScriptGoal&oldid=1495"