ScriptGoal
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
};
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.