MyGamingTalk - User contributions [en]

Waypoint Library

2026-04-24T15:43:56Z

Palota: connections

{{process header
| title = Waypoint Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
== AddWaypoint ==
Creates a new waypoint at a specified location.

'''Parameters'''

<nowiki><Vector3></nowiki> The position to add waypoint.

<nowiki><optional Vector3></nowiki> The facing for the waypoint.

'''Returns'''

int Waypoint Id if successful OR null if there was an error adding waypoint.

'''Example'''
<syntaxhighlight lang="java">
Wp.AddWaypoint(Vector3(1000,2000,1000))</syntaxhighlight>

== CheckBlockable ==
Verifies all red blockable connections and changes them to green immediately if they are not blocked anymore. This function should be used in triggers of destroyable walls or constructible bridges. It prevents a lot of path failed errors. Objects destroyed by a dynamite usually also require sleep(0.1) before CheckBlockable.

'''Parameters'''

None

'''Returns'''

Count of changed connections, but the number is unreliable and can be zero.

== Connect ==
Connects two waypoints

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint.

<nowiki><int></nowiki> Guid of another waypoint.

'''Returns'''

true if successful, false if not

== DeleteWaypoint ==
Delete a waypoint from a specified location.

'''Parameters'''

<nowiki><Vector3></nowiki> <nowiki>The <Vector3> position to delete waypoint from.</nowiki>

'''Returns'''

true if successful, false if not

'''Example'''
<syntaxhighlight lang="java">
Wp.DeleteWaypoint(Vector3(1000,2000,1000))</syntaxhighlight>

== Disconnect ==
Disconnects two waypoints.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint.

<nowiki><int></nowiki> Guid of another waypoint.

'''Returns'''

true if successful, false if not

== GetAllWaypoints ==
Gets all waypoints.

'''Parameters'''

<nowiki><table></nowiki> An empty table, the function will fill tables of position, facing, guid, radius, name, flags, property, connections.

'''Returns'''

None

'''Example'''
<syntaxhighlight lang="java">
wpTable = {};
Wp.GetAllWaypoints( wpTable );
foreach( waypoint in wpTable ) {
if( waypoint.name ) {
print(waypoint.name, "-", waypoint.position);
}
}

</syntaxhighlight>

== GetClosestWaypoint ==
Gets waypoint near position.

'''Parameters'''

<Vector3> position

<optional int> team

<optional options> 1=don't skip closed waypoints, 2=ignore waypoints without connections

'''Returns'''

<nowiki><table></nowiki>

'''Example'''
<syntaxhighlight lang="java">
w = Wp.GetClosestWaypoint( Vec3(100,200,0) );
if(w) {
print("waypoint UID ", w.guid);
}
</syntaxhighlight>

== GetAllSelectedWaypoints ==
Gets selected waypoints.

'''Parameters'''

<nowiki><table></nowiki> An empty table, the function will fill tables of position, facing, guid, radius, name, flags, property, connections.

'''Returns'''

None

== GetWaypointByGUID ==
Gets a waypoint information by its guid.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint.

<nowiki><table></nowiki> An empty table, the function will fill in position, facing, guid, radius, name, flags, property, connections.

'''Returns'''

true if successful, false if not

== GetWaypointByName ==
Gets a waypoint's information by its name.

'''Parameters'''

<nowiki><string></nowiki> The name of the waypoint to get the info of.

<nowiki><table></nowiki> An empty table, the function will fill in position, facing, guid, radius, name, flags, property, connections.

'''Returns'''

true if successful, false if not

== IsWaypointViewOn ==
Checks if waypoint view is on.

'''Parameters'''

None

'''Returns'''

int true if waypoint_view is on, false if not

'''Example'''
<syntaxhighlight lang="java">
Wp.IsWaypointViewOn()</syntaxhighlight>

== Load ==
Loads waypoints from nav folder.

'''Parameters'''

<nowiki><optional string></nowiki> File name.

'''Returns'''

true if successful, false if not

== Save ==
Saves waypoints to nav folder.

'''Parameters'''

<nowiki><optional string></nowiki> File name.

'''Returns'''

true if successful, false if not

== SetRadius ==
Sets a wapoint radius.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint

<nowiki><int></nowiki> Radius.

'''Returns'''

true if successful, false if not

== SetWaypointFlag ==
Sets the [[Waypoint_Flags|flag]] on a waypoint by name.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint '''OR'''<nowiki> <string></nowiki> Name of the waypoint or a regular expression.

<nowiki><string></nowiki> The name of the flag to set '''OR''' <nowiki><table></nowiki> Multiple flags to set.

<nowiki><int></nowiki> True to set, false to clear.

'''Returns'''

None

'''Example'''
<syntaxhighlight lang="java">
Wp.SetWaypointFlag("waypointname", "closed", false);
Wp.SetWaypointFlag("bridge_.*", "crouch", true);
Wp.SetWaypointFlag("main_entrance", { "axis", "door" }, true );</syntaxhighlight>

== SetWaypointName ==
Assigns a name to a waypoint.

'''Parameters'''

<nowiki><int></nowiki> The id of the waypoint to set the name of.

<nowiki><string></nowiki> The name to assign to the waypoint.

'''Returns'''

true if successful, false if not

== SetWaypointProperty ==
Sets the waypoint property.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint '''OR'''<nowiki> <string></nowiki> Name of the waypoint.

<nowiki><string></nowiki> The name of the property to set.

<nowiki><string></nowiki> Property value to set.

'''Returns'''

None

== WaypointColor ==
Customize the color of various types of waypoints, paths, etc... See [[Waypoint_Commands#waypoint_color|waypoint_color]] command for help.

'''Parameters'''

<nowiki><string></nowiki> The name of the category to set a color for.

<nowiki><int></nowiki> The color to use for this type.

'''Returns'''

None

=Properties=

== BlockablePathOffset ==
the offset for blockable paths for drawing purposes.

== BottomPathOffset ==
the offset for path bottom for drawing purposes.

== BottomWaypointOffset ==
the offset for waypoint bottom for drawing purposes.

== FacingOffset ==
the offset for drawing the facing indicator.

== PathLevelOffset ==
relative offset for path finding, default is 0.5

== TextDuration ==
drawing duration for texts, default is 2 seconds

== TextOffset ==
the offset for drawing waypoint name, UID, radius, flags.

== TopPathOffset ==
the offset for path top for drawing purposes.

== TopWaypointOffset ==
the offset for waypoint top for drawing purposes.

System Library

2026-04-24T15:40:33Z

Palota: CopyToClipboard

{{process header
| title = System Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Global FileSystem Functions==
----

===CopyToClipboard===
Copies a text to the Windows clipboard. Does not work on Linux or Mac.

'''Parameters:''' string

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">System.CopyToClipboard("Hello");</syntaxhighlight>
----

===FileDelete===
Deletes a file by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
System.FileDelete("myfile.txt");</syntaxhighlight>
----

===FileEnumerate===
Enumerates over all files in a directory. This function is restricted to files under the user folder. This function will call the provided script function with all files enumerated.

'''Parameters:''' (folder name, script function)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
myfunc = function(filename)
{
}
System.FileEnumerate("myfolder", myfunc);</syntaxhighlight>
----
===FileExists===
Checks if a file exists by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if exists, false if not

'''Example:''' <syntaxhighlight lang="java">
if(System.FileExists("myfile.txt"))
{
}</syntaxhighlight>
----
===Newline===
Returns a NewLine custom type. Used for writing newlines in text formatted files. It was a function in Omni-bot 0.71, but now it is a variable in Omni-bot 0.8.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
f.Write("Some test data", System.NewLine);
}
f.Close();</syntaxhighlight>
----

==File==
Creates a new File Object.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();</syntaxhighlight>

----
===Close===
Closes the file object and commits changes to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Close();</syntaxhighlight>

----

===EndOfFile===
Checks if the File Object is at the end of the file. Useful for read operations.

'''Parameters:''' none

'''Returns:''' true if end of file, false if not.

'''Example:''' <syntaxhighlight lang="java">
eof = f.EndOfFile();</syntaxhighlight>

----

===FileSize===
Gets the file size of the file, in bytes.

'''Parameters:''' none

'''Returns:''' size of file in bytes

'''Example:''' <syntaxhighlight lang="java">
size = f.FileSize();</syntaxhighlight>

----

===Flush===
Flushes the file buffer to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Flush();</syntaxhighlight>

----

===IsOpen===
Checks if the file is currently open. Usually used after a call to Open.

'''Parameters:''' none

'''Returns:''' true if file is open, false if not

'''Example:''' <syntaxhighlight lang="java">
if(f.IsOpen())
{
}</syntaxhighlight>

----

===Open===
Creates a new File Object.

'''Parameters:''' (filename, "text"/"binary", readonly<optional>, append<optional>)

'''Returns:''' true if success, false if failed.

'''Example:''' <syntaxhighlight lang="java">
if(f.Open("myfile.txt", "text", false))
{
}</syntaxhighlight>

----

===ReadFloat===
Reads a float from the file.

'''Parameters:''' none

'''Returns:''' float read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadFloat();</syntaxhighlight>

----

===ReadInt===
Reads an integer from the file.

'''Parameters:''' none

'''Returns:''' integer read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadInt();</syntaxhighlight>

----

===ReadLine===
Reads a string from a file until a newline or end of file is encountered.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadLine();</syntaxhighlight>

----

===ReadString===
Reads a string from a file.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadString();</syntaxhighlight>

----

===Seek===
Seeks the read/write position to a specified offset.

'''Parameters:''' (byte offset to seek to)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Seek(100); // seek 100 bytes into file</syntaxhighlight>

----

===Tell===
Returns the current offset of the read/write position in the file.

'''Parameters:''' none

'''Returns:''' byte position in file

'''Example:''' <syntaxhighlight lang="java">
t = f.Tell();</syntaxhighlight>

----

===Write===
Writes a value of varying types to the file, in whatever file mode was used to open the file.

'''Parameters:''' (...)

This function can take any number of parameters, of types integer, float, string, or System.NewLine.

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
assert( f.Write("Some test data", System.NewLine) );
}
f.Close();</syntaxhighlight>

----

===WriteLine===
Write with a new line.

----

System Library

2026-04-24T15:34:31Z

Palota:

{{process header
| title = System Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Global FileSystem Functions==
----
===FileDelete===
Deletes a file by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
System.FileDelete("myfile.txt");</syntaxhighlight>
----

===FileEnumerate===
Enumerates over all files in a directory. This function is restricted to files under the user folder. This function will call the provided script function with all files enumerated.

'''Parameters:''' (folder name, script function)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
myfunc = function(filename)
{
}
System.FileEnumerate("myfolder", myfunc);</syntaxhighlight>
----
===FileExists===
Checks if a file exists by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if exists, false if not

'''Example:''' <syntaxhighlight lang="java">
if(System.FileExists("myfile.txt"))
{
}</syntaxhighlight>
----
===Newline===
Returns a NewLine custom type. Used for writing newlines in text formatted files. It was a function in Omni-bot 0.71, but now it is a variable in Omni-bot 0.8.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
f.Write("Some test data", System.NewLine);
}
f.Close();</syntaxhighlight>
----

==File==
Creates a new File Object.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();</syntaxhighlight>

----
===Close===
Closes the file object and commits changes to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Close();</syntaxhighlight>

----

===EndOfFile===
Checks if the File Object is at the end of the file. Useful for read operations.

'''Parameters:''' none

'''Returns:''' true if end of file, false if not.

'''Example:''' <syntaxhighlight lang="java">
eof = f.EndOfFile();</syntaxhighlight>

----

===FileSize===
Gets the file size of the file, in bytes.

'''Parameters:''' none

'''Returns:''' size of file in bytes

'''Example:''' <syntaxhighlight lang="java">
size = f.FileSize();</syntaxhighlight>

----

===Flush===
Flushes the file buffer to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Flush();</syntaxhighlight>

----

===IsOpen===
Checks if the file is currently open. Usually used after a call to Open.

'''Parameters:''' none

'''Returns:''' true if file is open, false if not

'''Example:''' <syntaxhighlight lang="java">
if(f.IsOpen())
{
}</syntaxhighlight>

----

===Open===
Creates a new File Object.

'''Parameters:''' (filename, "text"/"binary", readonly<optional>, append<optional>)

'''Returns:''' true if success, false if failed.

'''Example:''' <syntaxhighlight lang="java">
if(f.Open("myfile.txt", "text", false))
{
}</syntaxhighlight>

----

===ReadFloat===
Reads a float from the file.

'''Parameters:''' none

'''Returns:''' float read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadFloat();</syntaxhighlight>

----

===ReadInt===
Reads an integer from the file.

'''Parameters:''' none

'''Returns:''' integer read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadInt();</syntaxhighlight>

----

===ReadLine===
Reads a string from a file until a newline or end of file is encountered.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadLine();</syntaxhighlight>

----

===ReadString===
Reads a string from a file.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadString();</syntaxhighlight>

----

===Seek===
Seeks the read/write position to a specified offset.

'''Parameters:''' (byte offset to seek to)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Seek(100); // seek 100 bytes into file</syntaxhighlight>

----

===Tell===
Returns the current offset of the read/write position in the file.

'''Parameters:''' none

'''Returns:''' byte position in file

'''Example:''' <syntaxhighlight lang="java">
t = f.Tell();</syntaxhighlight>

----

===Write===
Writes a value of varying types to the file, in whatever file mode was used to open the file.

'''Parameters:''' (...)

This function can take any number of parameters, of types integer, float, string, or System.NewLine.

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
assert( f.Write("Some test data", System.NewLine) );
}
f.Close();</syntaxhighlight>

----

===WriteLine===
Write with a new line.

----

Template:Configuration

2026-02-22T09:43:11Z

Palota: /* Log files */

== Number of bots ==

/bot maxbots 15

Sets maximum number of bots. It must be less than number of slots (sv_maxclients). The server manager script will automatically kick one bot when a human player connects to server and joins axis or allied team. Similarly, it will add a new bot if some player disconnects.

/bot minbots 2

Sets minimum number of bots. Default value is -1. You should set minbots only if you want some bots to be always playing even if your server is full.

If you want to add bots manually, you must set maxbots and minbots to -1. Then you can add bots by commands [[Omni-bot_Command_Reference#ab|/bot ab]] or [[Omni-bot_Command_Reference#addbot|/bot addbot]].

== Difficulty levels ==

/bot difficulty 4

Difficulty ranges from 0 to 6 (0 is easy, 6 is hard).

If you change difficulty, bots' properties will be adjusted (reaction time, field of view, aim error, view distance, ...). Advanced users can adjust bot properties for each difficulty level in the file omni-bot/et/scripts/goals/goal_difficulty.gm.

== Combat movement skill ==

/bot moveskill 4

Moveskill ranges from 0 to 3. Specifying 4 for moveskill will have each bot choose a random moveskill.

It affects bot's behaviour during combat (crouch, strafe left or right, ...).

== Balance teams ==

/bot balanceteams 1

If you enable balanceteams, bots will move between teams in order to keep same number of players in both teams.

== Log files ==

Log files are written to folder omni-bot/et/logs. If the folder does not exists, log files are written to Enemy Territory game folder. File name is omnibot_<mapname>.log.

/seta omnibot_logsize 100

* Default value 0 disables logging.
* Value greater than 0 means maximal file size in KB.

== Configuration file ==

You can find the file '''omni-bot.cfg''' in the folder omni-bot/et/user. You usually don't need to modify this file because most settings can be changed from the console. Nevertheless, some advanced settings are not accessible from the console: CountSpectators, SleepBots, SaveConfigChanges, AdjustAim, DumpFileEnable, DumpFileDialog, LiveUpdate, Debug, EnableInterProcess, LogInfo, LogWarnings, LogErrors, LogCriticalErrors.

Documentation can be found in file omni-bot.txt.

== Changing bot names ==

You need to go into the omni-bot/et/scripts folder. In Omni-bot 0.82 or later open file "'''et_botnames_ext.gm'''". In Omni-bot 0.81 or 0.8 open file "et_botnames.gm". In Omni-bot 0.71 or older open file "et_autoexec.gm". Bots' names are in quotes. Do not change other commands in that scripts.

== Waypoints folder ==

Waypoints and map scripts can be found in the '''omni-bot/et/nav''' and '''omni-bot/et/incomplete_navs''' folders. New waypoints should be added into this folder. You can add new waypoints in a zip or 7z file (they must be at the root level of the zip file, not in a folder) or you can just add the files directly.

Paththrough Navigation

2025-08-16T09:00:17Z

Palota: /* Navigation */

{{process header
| title = Paththrough Navigation
| section =
| previous = [[paththrough | Paththrough Main Page]]
| next =
| shortcut =
| notes =
}}

== Navigation ==
Navigation is the simplest paththrough type. It requires two things:

(1) Navigation table inside the Map table in the map script that could look like this:
<syntaxhighlight lang="java">
global Map =
{
Navigation =
{
strafe_r_point =
{
navigate = function()
{
this.AddAimRequest(Priority.High, "facing", Vec3(0.7, 0, 0.8));
this.Bot.HoldButton(BTN.STRAFE_R, 2);
sleep(2);
}
},
},
};</syntaxhighlight>

In the above example, the navigate function tells the bot that when it reaches a waypoint whose paththrough property is set to <nowiki>Navigation_PT:strafe_r_point,</nowiki> it should hold the strafe right button for two seconds.

If you use HoldButton with buttons FORWARD, BACKWARD, STRAFE_L or STRAFE_R, you must also call AddAimRequest, otherwise bot would aim at enemies and direction would be unpredictable.

(2) The second thing that's necessary to set up paththrough navigation: go to the waypoint where you want the bots to strafe (or whatever) and add the property:

/bot waypoint_setproperty paththrough Navigation_PT:strafe_r_point

===Using the Script Goal Object===
Although this is the simplest paththrough type, it is also the most powerful in terms of capabilities. The navigate function receives the entire [[ScriptGoal|script goal]] object as this parameter. This basically exposes the new goal scripting system to map scripters; providing means for the map scripter to define more complex bot behaviors or "mini goals" when a bot gets to a specific waypoint.

'''If navigate function does not call Goto or GotoAsync, bot follows the path to his current goal.''' If navigate function calls Goto, bot goes to that position and then stops there and waits. Bot will find new path to current goal after your navigate function exits.

Paththrough navigation in Omni-Bot 0.71, 0.8 and 0.81 could be interrupted if high level goal changed. This caused bots to stuck or fall to death. This changed in 0.82 and paththrough navigation is interrupted only by death. It's recommended that every while loop checks for time out so that navigate function won't suspend bot forever.

As an example, this following setup would instruct a bot that reaches the paththrough waypoint to go throw a grenade at some target:

<syntaxhighlight lang="java">
global Map =
{
Grate_Bot_Count = 0,
Grate_Destroyed = false,

Navigation =
{
grenadegrate =
{
EvalFunc = function() // if EvalFunc returns false, navigation and OnExit will not run
{
// do nothing if the grate is already destroyed
return !Map.Grate_Destroyed;
},
navigate = function()
{
// you can use command /bot mypos or /bot spp to get coordinates
if ( this.Goto(Vec3(1608, 3830, 24)) == EVENT.PATH_SUCCESS
// only one bot will throw grenade
&& Map.Grate_Bot_Count == 0 && this.Bot.HasWeapon( WEAPON.AXIS_GRENADE ))
{
this.Grate_Bot = true; //this is local, each bot has his own variable
Map.Grate_Bot_Count += 1; //Map is global and shared by all bots

// look at the grate, you can use command /bot mypos to get facing vector
this.AddAimRequest(Priority.High, "facing", Vec3(-0.758, 0.614, -0.221));
// switch to grenade (the navigation is only for Axis team !)
this.AddWeaponRequest(Priority.High, WEAPON.AXIS_GRENADE );
this.BlockForWeaponChange( WEAPON.AXIS_GRENADE );
// throw grenade
this.Bot.HoldButton(BTN.ATTACK1, 0.5);
sleep(1);
// switch to primary weapon
this.ReleaseAimRequest();
this.ReleaseWeaponRequest();
//wait until the grenade explodes
sleep(4);
}
else
{
// wait and hope that somebody else will destroy the grate
sleep(6);
}
},
OnExit = function() // OnExit is called after navigate finished or the bot has been killed
{
//if this is the bot who threw a grenade, decrease count
if (this.Grate_Bot)
{
this.Grate_Bot = null;
Map.Grate_Bot_Count -= 1;
}
},
},
},

Grate_Trigger = function(trigger)
{
Map.Grate_Destroyed = true;
},
};
</syntaxhighlight>

In this case the waypoint property would be set as:
/bot waypoint_setproperty paththrough Navigation_PT:grenadegrate

While this application of the navigation paththrough goal offers complete flexibility, great care should be taken when scripting such things. Any implementation should be thoroughly tested.

Waypoint Commands

2025-08-13T06:40:41Z

Palota: /* waypoint_autoflag */

{{TOCright}}
== Waypoint Commands ==

* [[Console|How to open console and execute command]]

=== waypoint_add ===

''Usage:'' waypoint_add

''Example:'' waypoint_add
* Adds a waypoint at the location where you are currently standing. When executing waypoint_add, a new waypoint will be created at the location you are currently standing. Some waypoint flags may be automatically placed on the waypoint.
** If the waypoint is underwater, the underwater flag should be automatically added.
** If you are crouching when you place the waypoint, the crouch flag should be automatically added.
** If you are proning when you place the waypoint, the crouch flag should be automatically added instead of adding prone flag.

=== waypoint_addflag ===

''Usage:'' waypoint_addflag flags[string] ...

''Example:'' waypoint_addflag crouch
* Flags the nearest waypoint with named properties, or clears the flag from the waypoint if it already exists. This command can take any number of waypoint flags. See [[Waypoint_Flags | the list of flags]] here.

=== waypoint_addflagx ===

''Usage:'' waypoint_addflagx flags[string] ...

''Example:'' waypoint_addflagx crouch
* Same as waypoint_addflag, only instead of the nearest waypoint, uses the waypoint you are currently aimed at.

=== waypoint_addx ===

''Usage:'' waypoint_addx

''Example:'' waypoint_addx
* Same as waypoint_add, only instead of location you are currently standing., it adds a waypoint where you are currently aimed at.
* Note for 0.7 and above only

=== waypoint_autobuild ===

''Usage:'' waypoint_autobuild dc[1/0] bbox[1/0] limitheight[#] limitdist[#] maxconnections[#]

''Example:'' waypoint_autobuild 1 0 32 1024 4
* This command automatically creates connections between waypoints based on the parameters used. It is a time saving function that can generate a pretty good starting point for paths between waypoints. It is not meant to do all the work for you, and will likely need additional cleanup after using where you may need to add additional connections it missed, or removed bad connections in may have added.

** dc - Disconnect all current connections before auto connecting.
** bbox - Use a small bounding box when casting the ray between waypoints. Useful for filtering out some connections that clip closely to a wall.
** limitheight - Only make connections to waypoints that are only within this height difference. Useful to prevent connections between multiple levels in a wide open room, even if there is line of sight between them.
** limitdist - Only make connections to other waypoints within this distance.
** maxconnections - Only make a maximum of this many connections. 3-5 tends to be a good range to start with.

=== waypoint_autofeature ===

''Usage:'' waypoint_autofeature

''Example:'' waypoint_autofeature
* Attempts to add waypoints at all detected map features. This includes spawn points, mg42, and portals. If used, it should be used first before adding any other waypoints in the map. The detected features are game dependent; meaning not all games will have all listed features detected.

=== waypoint_autoradius ===

''Usage:'' waypoint_autoradius all/cur[string] height[#] minradius[#] maxradius[#]

''Example:'' waypoint_autoradius all 32 20 200
* Automatically detects a waypoint radius on the nearest or all waypoints(depending on 1st parameter).
** all/cur - all performs autoradius on all waypoints, cur performs it on the nearest.
** height - A vertical offset from the waypoint position to perform the collision tests with. This is useful due to differences in waypoint position between games. In Doom3 & HL2 engine games, the position is at the ground, while in ET the position is about half-way up a players height.
** minradius - The minimum radius to use.
** maxradius - The maximum radius to use.

=== waypoint_biconnect ===

''Usage:'' waypoint_biconnect

''Example:'' waypoint_biconnect
* Same as waypoint_connect, but results in a 2 way connection between the waypoints.

=== waypoint_biconnectx ===

''Usage:'' waypoint_biconnectx

''Example:'' waypoint_biconnectx
* Same as waypoint_connectx, but results in a 2 way connection between the waypoints.

=== waypoint_boxselect ===

''Usage:'' waypoint_boxselect

''Example:'' waypoint_boxselect
* Creates a box area to select all waypoints within the boundaries. First usage starts the select area, use the cursor to expand the box, then use the command again to finish the selection.

=== waypoint_boxselectroom ===

''Usage:'' waypoint_boxselectroom

''Example:'' waypoint_boxselectroom
* Not fully implemented

=== waypoint_changeradius ===

''Usage:'' waypoint_changeradius change[#]

''Example:'' waypoint_changeradius -10
* Change the radius of the nearest waypoint by the change amount. Useful if you want to bind a increase and decrease radius key, such as a mouse wheel.

=== waypoint_clearallflags ===

''Usage:'' waypoint_clearallflags flags[string] ...

''Example:'' waypoint_clearallflags crouch
* Clears a list of flags from all waypoints in the map. Like waypoint_addflag, it can take any number of flag names, and clears the flags from all waypoints in the map. Useful if you want to remove all of a particular flag from a map.

=== waypoint_clearcon ===

''Usage:'' waypoint_clearcon

''Example:'' waypoint_clearcon
* Clears all the connections from the nearest waypoint or all selected waypoints(if any).

=== waypoint_clearproperty ===

''Usage:'' waypoint_clearproperty name[string]

''Example:'' waypoint_clearproperty bias
* Clears a property from a waypoint by its name.

=== waypoint_color ===

''Usage:'' waypoint_color

''Example:'' waypoint_color type[string] red[#] green[#] blue[#]
* Allows colors to be configured for certain types of waypoints.
** waypoint_color - Default color of waypoints.
** waypoint_selected - Selected waypoints.
** link_closedcolor - If the waypoint has a closed flag.
** link_teleport - If the waypoint has a teleport flag.
** link_1way - One-way connection links.
** link_2way - Two-way connection link.
** blockable_blocked - Blockable line indicators when it is blocked.
** blockable_open - Blockable line indicators when it is open(unblocked).
** aimentity - Color of the box drawn around entities when you aim at them with waypoint_view enabled.
** radius - Color of the radius indicator.
** team1 - Team 1 flagged waypoints
** team2 - Team 2 flagged waypoints
** team3 - Team 3 flagged waypoints (not for ET)
** team4 - Team 4 flagged waypoints (not for ET)

=== waypoint_connect ===

''Usage:'' waypoint_connect

''Example:'' waypoint_connect
* Flags the nearest waypoint for a connection. If a waypoint is already flagged for connection that waypoint will be connected to this waypoint with a 1-way connection.

=== waypoint_connectx ===

''Usage:'' waypoint_connectx

''Example:'' waypoint_connectx
* Same as waypoint_connect, only uses the waypoint you are aiming at.

=== waypoint_dcall ===

''Usage:'' waypoint_dcall

''Example:'' waypoint_dcall
* Disconnect all waypoints in the map. This removes all connections, while leaving only the waypoints.

=== waypoint_del ===

''Usage:'' waypoint_del

''Example:'' waypoint_del
* Deletes a nearest waypoint that you are standing within 100 units of. All connections from and to the waypoint will get automatically removed as well.

=== waypoint_delx ===

''Usage:'' waypoint_delx

''Example:'' waypoint_delx
* Same as waypoint_del, but removes the waypoint you are aiming at.

=== waypoint_deleteaxis ===

''Usage:'' waypoint_deleteaxis axis[string]

''Example:'' waypoint_deleteaxis
* Deletes all waypoints on a specified side of a specified axis.
** axis - x, y, z, -x, -y, -z, which side of which axis to delete all waypoints from. Mainly useful for symmetrical maps when you wish to delete a side, make adjustments, and re-mirror the waypoints.

=== waypoint_goto ===

''Usage:'' waypoint_goto <waypoint GUID>

''Example:'' waypoint_goto 127
* Teleports the player to the given waypoint by GUID
* Requires game specific implementation, not all games support it.

=== waypoint_ground ===

''Usage:'' waypoint_ground

''Example:'' waypoint_ground
* Grounds all waypoints based on the navigation rendering offsets.

=== waypoint_info ===

''Usage:'' waypoint_info

''Example:'' waypoint_info
* Prints some basic information about the nearest waypoint.

=== waypoint_load ===

''Usage:'' waypoint_load name[string, optional]

''Example:'' waypoint_load
* name is optional and if used, loads the waypoints for the currently loaded map with the suffix name. For example, if the map d3ctf1 is loaded, waypoint_load half would load from the nav directory the file d3ctf1half.way
* Loads the waypoints for the currently loaded map. Waypoints are loaded from the nav directory under the mod currently running. Warning: Any changes you may have made to the waypoints since the last load will be lost. This command is typically used for undoing changes made after the last save.

=== waypoint_lockselected ===

''Usage:'' waypoint_lockselected

''Example:'' waypoint_lockselected
* Locks all currently selected waypoints. Locked waypoints aren't effected by waypoint_translate.

=== waypoint_maxradius ===

''Usage:'' waypoint_maxradius <radius>

''Example:'' waypoint_maxradius 70
* Clamps all waypoints maximum radius to this value

=== waypoint_minradius ===

''Usage:'' waypoint_minradius <radius>

''Example:'' waypoint_minradius 70
* Clamps all waypoints minimum radius to this value

=== waypoint_mirror ===

''Usage:'' waypoint_mirror axis[string] p[optional]
* If axis parameter is x, y, or z, waypoints are rotated around provided axis.
* If axis parameter is m, waypoints are mirrored, north to south.
* If axis parameter is mz, waypoints are mirrored, west to east.
* p is optional, and if defined will use your current position to define origin (map center)

''Example:'' waypoint_mirror z
* This command duplicates all or selected waypoints and rotates or mirrors the duplicated waypoints across the origin of a provided axis. This function is useful for mirroring the waypoints in a symmetrical map, where each team has an identical base. The optional p parameter is useful for when the map isn't centered around the 0 axis. Stand as closely to the center of the map as possible and execute the command including the optional p parameter and the waypoints will be mirrored and offset based on the player position.

=== waypoint_move ===

''Usage:'' waypoint_move

''Example:'' waypoint_move
* Grabs the nearest waypoint for moving. If a waypoint has already been grabbed by a previous call to waypoint_move, it is dropped at your current position. Connections are maintained throughout waypoint moving.

=== waypoint_save ===

''Usage:'' waypoint_save

''Example:'' waypoint_save
* name is optional and if used, saves the waypoints for the currently loaded map with the suffix name. For example, if the map d3ctf1 is loaded, waypoint_save half would save the waypoints to the nav directory as the file d3ctf1half.way
* Saves the waypoints for the currently loaded map. Waypoints are saved to a file called mapname.way in the nav directory under the mod currently running. Warning: This will overwrite an existing waypoint file of the same name without asking. Rename or backup your original waypoint files when you want to experiment.

=== waypoint_select ===

''Usage:'' waypoint_select radius[#]

''Example:'' waypoint_select 500
* Selects all waypoints in the provided radius. If no radius is provided, the selection is cleared. Some of the above functions work on selected waypoints.

=== waypoint_setdefaultradius ===

''Usage:'' waypoint_setdefaultradius radius[#]

''Example:'' waypoint_setdefaultradius 100
* Sets the default radius that is used with all waypoints placed. Useful if you plan to waypoint_add a bunch of waypoints that will share a radius different from the current default to save time going back and changing radius manually.

=== waypoint_setfacing ===

''Usage:'' waypoint_setfacing

''Example:'' waypoint_setfacing
* Sets the facing for the nearest waypoint to your current facing. A waypoint's facing is basically a vector associated with a waypoint. It was used in Omni-bot 0.71 to tell the bot in which direction to look when the bot was camping on that waypoint (due to a sniper or defend flag in most cases). Goals do not use waypoint facing since Omni-bot 0.8, but it can be used for various purposes in map scripts.

=== waypoint_setname ===

''Usage:'' waypoint_setname name[string]

''Example:'' waypoint_setname spawnarea
* Sets the name of the nearest waypoint. Waypoint names are used as part of the map goal name if goal entity does not have name. It usually happens only for goals MOUNTMG42, REPAIRMG42, AMMOCAB, HEALTHCAB. It's much easier and less error-prone to manipulate goals in a map script based on meaningful names rather than UIDs.
* Note: Omni-bot 0.71 and older used waypoint name for any goals that were created as a result of the flags on a waypoint. For example, if you set a waypoint's name to "barrier_axis1" and the waypoint had a sniper flag set, it appeared as SNIPE_barrier_axis1 in the bots' goal list.

=== waypoint_setproperty ===

''Usage:'' waypoint_setproperty name[string] value[string]

''Example:'' waypoint_setproperty paththrough Navigation_PT:ladder1
* Sets an arbitrary propery value by name. It is usually used to set [[Paththrough]].

=== waypoint_setradius ===

''Usage:'' waypoint_setradius radius[#]

''Example:'' waypoint_setradius 100
* Sets the radius of the nearest waypoint.

=== waypoint_shownames ===

''Usage:'' waypoint_shownames expression[string, optional]

''Example:'' waypoint_shownames ATTACK.*
* Prints all waypoint id's and names that optionally match an expression.

=== waypoint_showproperty ===

''Usage:'' waypoint_showproperty

''Example:'' waypoint_showproperty
* Shows all properties on the current waypoint.

=== waypoint_slice ===

''Usage:'' waypoint_slice

''Example:'' waypoint_slice maxsegmentlength[#]
* Slices a 2 way connection so that it doesn't exceed a specified length.

=== waypoint_split ===

''Usage:'' waypoint_split
* Splits a 2 way connection to 2 parts. A new waypoint is created near the location where you are currently standing.

=== waypoint_stats ===

''Usage:'' waypoint_stats

''Example:'' waypoint_stats
* Prints out some basic information for the waypoint pathing system. Primarily a debug tool, but useful if you want to see the total number of waypoints currently placed.

=== waypoint_translate ===

''Usage:'' waypoint_translate x[#] y[#] z[#]

''Example:'' waypoint_translate 10 0 0
* Translates(moves) all waypoints, or the currently selected waypoints by Vector3(x,y,z)

=== waypoint_unlockall ===

''Usage:'' waypoint_unlockall

''Example:'' waypoint_unlockall
* Unlocks all waypoints.

=== waypoint_unsplit ===

''Usage:'' waypoint_unsplit

* Deletes a nearest waypoint which has 2 connections and makes 1 connection.

=== waypoint_view ===

''Usage:'' waypoint_view enable[1,0,true,false,on,off,toggle]

''Example:'' waypoint_view 1
* Enables or disables waypoint rendering.

=== waypoint_viewfacing ===

''Usage:'' waypoint_viewfacing enable[1,0,true,false,on,off]

''Example:'' waypoint_viewfacing 1
* Enables or disables rendering of the facing vector for waypoints if they have a facing vector.

Waypoint Commands

2025-08-11T15:11:53Z

Palota: /* waypoint_view */

{{TOCright}}
== Waypoint Commands ==

* [[Console|How to open console and execute command]]

=== waypoint_add ===

''Usage:'' waypoint_add

''Example:'' waypoint_add
* Adds a waypoint at the location where you are currently standing. When executing waypoint_add, a new waypoint will be created at the location you are currently standing. Some waypoint flags may be automatically placed on the waypoint.
** If the waypoint is underwater, the underwater flag should be automatically added.
** If you are crouching when you place the waypoint, the crouch flag should be automatically added.
** If you are proning when you place the waypoint, the crouch flag should be automatically added instead of adding prone flag.

=== waypoint_addflag ===

''Usage:'' waypoint_addflag flags[string] ...

''Example:'' waypoint_addflag crouch
* Flags the nearest waypoint with named properties, or clears the flag from the waypoint if it already exists. This command can take any number of waypoint flags. See [[Waypoint_Flags | the list of flags]] here.

=== waypoint_addflagx ===

''Usage:'' waypoint_addflagx flags[string] ...

''Example:'' waypoint_addflagx crouch
* Same as waypoint_addflag, only instead of the nearest waypoint, uses the waypoint you are currently aimed at.

=== waypoint_addx ===

''Usage:'' waypoint_addx

''Example:'' waypoint_addx
* Same as waypoint_add, only instead of location you are currently standing., it adds a waypoint where you are currently aimed at.
* Note for 0.7 and above only

=== waypoint_autobuild ===

''Usage:'' waypoint_autobuild dc[1/0] bbox[1/0] limitheight[#] limitdist[#] maxconnections[#]

''Example:'' waypoint_autobuild 1 0 32 1024 4
* This command automatically creates connections between waypoints based on the parameters used. It is a time saving function that can generate a pretty good starting point for paths between waypoints. It is not meant to do all the work for you, and will likely need additional cleanup after using where you may need to add additional connections it missed, or removed bad connections in may have added.

** dc - Disconnect all current connections before auto connecting.
** bbox - Use a small bounding box when casting the ray between waypoints. Useful for filtering out some connections that clip closely to a wall.
** limitheight - Only make connections to waypoints that are only within this height difference. Useful to prevent connections between multiple levels in a wide open room, even if there is line of sight between them.
** limitdist - Only make connections to other waypoints within this distance.
** maxconnections - Only make a maximum of this many connections. 3-5 tends to be a good range to start with.

=== waypoint_autofeature ===

''Usage:'' waypoint_autofeature

''Example:'' waypoint_autofeature
* Attempts to add waypoints at all detected map features. This includes spawn points, mg42, and portals. If used, it should be used first before adding any other waypoints in the map. The detected features are game dependent; meaning not all games will have all listed features detected.

=== waypoint_autoflag ===

''Usage:'' waypoint_autoflag <flag>

''Example:'' waypoint_autoflag crouch
* Toggles whether or not waypoints are autoflagged. '''Currently not used'''

=== waypoint_autoradius ===

''Usage:'' waypoint_autoradius all/cur[string] height[#] minradius[#] maxradius[#]

''Example:'' waypoint_autoradius all 32 20 200
* Automatically detects a waypoint radius on the nearest or all waypoints(depending on 1st parameter).
** all/cur - all performs autoradius on all waypoints, cur performs it on the nearest.
** height - A vertical offset from the waypoint position to perform the collision tests with. This is useful due to differences in waypoint position between games. In Doom3 & HL2 engine games, the position is at the ground, while in ET the position is about half-way up a players height.
** minradius - The minimum radius to use.
** maxradius - The maximum radius to use.

=== waypoint_biconnect ===

''Usage:'' waypoint_biconnect

''Example:'' waypoint_biconnect
* Same as waypoint_connect, but results in a 2 way connection between the waypoints.

=== waypoint_biconnectx ===

''Usage:'' waypoint_biconnectx

''Example:'' waypoint_biconnectx
* Same as waypoint_connectx, but results in a 2 way connection between the waypoints.

=== waypoint_boxselect ===

''Usage:'' waypoint_boxselect

''Example:'' waypoint_boxselect
* Creates a box area to select all waypoints within the boundaries. First usage starts the select area, use the cursor to expand the box, then use the command again to finish the selection.

=== waypoint_boxselectroom ===

''Usage:'' waypoint_boxselectroom

''Example:'' waypoint_boxselectroom
* Not fully implemented

=== waypoint_changeradius ===

''Usage:'' waypoint_changeradius change[#]

''Example:'' waypoint_changeradius -10
* Change the radius of the nearest waypoint by the change amount. Useful if you want to bind a increase and decrease radius key, such as a mouse wheel.

=== waypoint_clearallflags ===

''Usage:'' waypoint_clearallflags flags[string] ...

''Example:'' waypoint_clearallflags crouch
* Clears a list of flags from all waypoints in the map. Like waypoint_addflag, it can take any number of flag names, and clears the flags from all waypoints in the map. Useful if you want to remove all of a particular flag from a map.

=== waypoint_clearcon ===

''Usage:'' waypoint_clearcon

''Example:'' waypoint_clearcon
* Clears all the connections from the nearest waypoint or all selected waypoints(if any).

=== waypoint_clearproperty ===

''Usage:'' waypoint_clearproperty name[string]

''Example:'' waypoint_clearproperty bias
* Clears a property from a waypoint by its name.

=== waypoint_color ===

''Usage:'' waypoint_color

''Example:'' waypoint_color type[string] red[#] green[#] blue[#]
* Allows colors to be configured for certain types of waypoints.
** waypoint_color - Default color of waypoints.
** waypoint_selected - Selected waypoints.
** link_closedcolor - If the waypoint has a closed flag.
** link_teleport - If the waypoint has a teleport flag.
** link_1way - One-way connection links.
** link_2way - Two-way connection link.
** blockable_blocked - Blockable line indicators when it is blocked.
** blockable_open - Blockable line indicators when it is open(unblocked).
** aimentity - Color of the box drawn around entities when you aim at them with waypoint_view enabled.
** radius - Color of the radius indicator.
** team1 - Team 1 flagged waypoints
** team2 - Team 2 flagged waypoints
** team3 - Team 3 flagged waypoints (not for ET)
** team4 - Team 4 flagged waypoints (not for ET)

=== waypoint_connect ===

''Usage:'' waypoint_connect

''Example:'' waypoint_connect
* Flags the nearest waypoint for a connection. If a waypoint is already flagged for connection that waypoint will be connected to this waypoint with a 1-way connection.

=== waypoint_connectx ===

''Usage:'' waypoint_connectx

''Example:'' waypoint_connectx
* Same as waypoint_connect, only uses the waypoint you are aiming at.

=== waypoint_dcall ===

''Usage:'' waypoint_dcall

''Example:'' waypoint_dcall
* Disconnect all waypoints in the map. This removes all connections, while leaving only the waypoints.

=== waypoint_del ===

''Usage:'' waypoint_del

''Example:'' waypoint_del
* Deletes a nearest waypoint that you are standing within 100 units of. All connections from and to the waypoint will get automatically removed as well.

=== waypoint_delx ===

''Usage:'' waypoint_delx

''Example:'' waypoint_delx
* Same as waypoint_del, but removes the waypoint you are aiming at.

=== waypoint_deleteaxis ===

''Usage:'' waypoint_deleteaxis axis[string]

''Example:'' waypoint_deleteaxis
* Deletes all waypoints on a specified side of a specified axis.
** axis - x, y, z, -x, -y, -z, which side of which axis to delete all waypoints from. Mainly useful for symmetrical maps when you wish to delete a side, make adjustments, and re-mirror the waypoints.

=== waypoint_goto ===

''Usage:'' waypoint_goto <waypoint GUID>

''Example:'' waypoint_goto 127
* Teleports the player to the given waypoint by GUID
* Requires game specific implementation, not all games support it.

=== waypoint_ground ===

''Usage:'' waypoint_ground

''Example:'' waypoint_ground
* Grounds all waypoints based on the navigation rendering offsets.

=== waypoint_info ===

''Usage:'' waypoint_info

''Example:'' waypoint_info
* Prints some basic information about the nearest waypoint.

=== waypoint_load ===

''Usage:'' waypoint_load name[string, optional]

''Example:'' waypoint_load
* name is optional and if used, loads the waypoints for the currently loaded map with the suffix name. For example, if the map d3ctf1 is loaded, waypoint_load half would load from the nav directory the file d3ctf1half.way
* Loads the waypoints for the currently loaded map. Waypoints are loaded from the nav directory under the mod currently running. Warning: Any changes you may have made to the waypoints since the last load will be lost. This command is typically used for undoing changes made after the last save.

=== waypoint_lockselected ===

''Usage:'' waypoint_lockselected

''Example:'' waypoint_lockselected
* Locks all currently selected waypoints. Locked waypoints aren't effected by waypoint_translate.

=== waypoint_maxradius ===

''Usage:'' waypoint_maxradius <radius>

''Example:'' waypoint_maxradius 70
* Clamps all waypoints maximum radius to this value

=== waypoint_minradius ===

''Usage:'' waypoint_minradius <radius>

''Example:'' waypoint_minradius 70
* Clamps all waypoints minimum radius to this value

=== waypoint_mirror ===

''Usage:'' waypoint_mirror axis[string] p[optional]
* If axis parameter is x, y, or z, waypoints are rotated around provided axis.
* If axis parameter is m, waypoints are mirrored, north to south.
* If axis parameter is mz, waypoints are mirrored, west to east.
* p is optional, and if defined will use your current position to define origin (map center)

''Example:'' waypoint_mirror z
* This command duplicates all or selected waypoints and rotates or mirrors the duplicated waypoints across the origin of a provided axis. This function is useful for mirroring the waypoints in a symmetrical map, where each team has an identical base. The optional p parameter is useful for when the map isn't centered around the 0 axis. Stand as closely to the center of the map as possible and execute the command including the optional p parameter and the waypoints will be mirrored and offset based on the player position.

=== waypoint_move ===

''Usage:'' waypoint_move

''Example:'' waypoint_move
* Grabs the nearest waypoint for moving. If a waypoint has already been grabbed by a previous call to waypoint_move, it is dropped at your current position. Connections are maintained throughout waypoint moving.

=== waypoint_save ===

''Usage:'' waypoint_save

''Example:'' waypoint_save
* name is optional and if used, saves the waypoints for the currently loaded map with the suffix name. For example, if the map d3ctf1 is loaded, waypoint_save half would save the waypoints to the nav directory as the file d3ctf1half.way
* Saves the waypoints for the currently loaded map. Waypoints are saved to a file called mapname.way in the nav directory under the mod currently running. Warning: This will overwrite an existing waypoint file of the same name without asking. Rename or backup your original waypoint files when you want to experiment.

=== waypoint_select ===

''Usage:'' waypoint_select radius[#]

''Example:'' waypoint_select 500
* Selects all waypoints in the provided radius. If no radius is provided, the selection is cleared. Some of the above functions work on selected waypoints.

=== waypoint_setdefaultradius ===

''Usage:'' waypoint_setdefaultradius radius[#]

''Example:'' waypoint_setdefaultradius 100
* Sets the default radius that is used with all waypoints placed. Useful if you plan to waypoint_add a bunch of waypoints that will share a radius different from the current default to save time going back and changing radius manually.

=== waypoint_setfacing ===

''Usage:'' waypoint_setfacing

''Example:'' waypoint_setfacing
* Sets the facing for the nearest waypoint to your current facing. A waypoint's facing is basically a vector associated with a waypoint. It was used in Omni-bot 0.71 to tell the bot in which direction to look when the bot was camping on that waypoint (due to a sniper or defend flag in most cases). Goals do not use waypoint facing since Omni-bot 0.8, but it can be used for various purposes in map scripts.

=== waypoint_setname ===

''Usage:'' waypoint_setname name[string]

''Example:'' waypoint_setname spawnarea
* Sets the name of the nearest waypoint. Waypoint names are used as part of the map goal name if goal entity does not have name. It usually happens only for goals MOUNTMG42, REPAIRMG42, AMMOCAB, HEALTHCAB. It's much easier and less error-prone to manipulate goals in a map script based on meaningful names rather than UIDs.
* Note: Omni-bot 0.71 and older used waypoint name for any goals that were created as a result of the flags on a waypoint. For example, if you set a waypoint's name to "barrier_axis1" and the waypoint had a sniper flag set, it appeared as SNIPE_barrier_axis1 in the bots' goal list.

=== waypoint_setproperty ===

''Usage:'' waypoint_setproperty name[string] value[string]

''Example:'' waypoint_setproperty paththrough Navigation_PT:ladder1
* Sets an arbitrary propery value by name. It is usually used to set [[Paththrough]].

=== waypoint_setradius ===

''Usage:'' waypoint_setradius radius[#]

''Example:'' waypoint_setradius 100
* Sets the radius of the nearest waypoint.

=== waypoint_shownames ===

''Usage:'' waypoint_shownames expression[string, optional]

''Example:'' waypoint_shownames ATTACK.*
* Prints all waypoint id's and names that optionally match an expression.

=== waypoint_showproperty ===

''Usage:'' waypoint_showproperty

''Example:'' waypoint_showproperty
* Shows all properties on the current waypoint.

=== waypoint_slice ===

''Usage:'' waypoint_slice

''Example:'' waypoint_slice maxsegmentlength[#]
* Slices a 2 way connection so that it doesn't exceed a specified length.

=== waypoint_split ===

''Usage:'' waypoint_split
* Splits a 2 way connection to 2 parts. A new waypoint is created near the location where you are currently standing.

=== waypoint_stats ===

''Usage:'' waypoint_stats

''Example:'' waypoint_stats
* Prints out some basic information for the waypoint pathing system. Primarily a debug tool, but useful if you want to see the total number of waypoints currently placed.

=== waypoint_translate ===

''Usage:'' waypoint_translate x[#] y[#] z[#]

''Example:'' waypoint_translate 10 0 0
* Translates(moves) all waypoints, or the currently selected waypoints by Vector3(x,y,z)

=== waypoint_unlockall ===

''Usage:'' waypoint_unlockall

''Example:'' waypoint_unlockall
* Unlocks all waypoints.

=== waypoint_unsplit ===

''Usage:'' waypoint_unsplit

* Deletes a nearest waypoint which has 2 connections and makes 1 connection.

=== waypoint_view ===

''Usage:'' waypoint_view enable[1,0,true,false,on,off,toggle]

''Example:'' waypoint_view 1
* Enables or disables waypoint rendering.

=== waypoint_viewfacing ===

''Usage:'' waypoint_viewfacing enable[1,0,true,false,on,off]

''Example:'' waypoint_viewfacing 1
* Enables or disables rendering of the facing vector for waypoints if they have a facing vector.

System Library

2025-07-06T13:15:27Z

Palota: /* Global FileSystem Functions */

{{process header
| title = System Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Global FileSystem Functions==
----
===FileDelete===
Deletes a file by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
System.FileDelete("myfile.txt");</syntaxhighlight>
----

===FileEnumerate===
Enumerates over all files in a directory. This function is restricted to files under the user folder. This function will call the provided script function with all files enumerated.

'''Parameters:''' (folder name, script function)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
myfunc = function(filename)
{
}
System.FileEnumerate("myfolder", myfunc);</syntaxhighlight>
----
===FileExists===
Checks if a file exists by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if exists, false if not

'''Example:''' <syntaxhighlight lang="java">
if(System.FileExists("myfile.txt"))
{
}</syntaxhighlight>
----
===Newline===
Returns a NewLine custom type. Used for writing newlines in text formatted files. It was a function in Omni-bot 0.71, but now it is a variable in Omni-bot 0.8.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
f.Write("Some test data", System.NewLine);
}
f.Close();</syntaxhighlight>
----

==File==
Creates a new File Object.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();</syntaxhighlight>

----
===Close===
Closes the file object and commits changes to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Close();</syntaxhighlight>

----

===EndOfFile===
Checks if the File Object is at the end of the file. Useful for read operations.

'''Parameters:''' none

'''Returns:''' true if end of file, false if not.

'''Example:''' <syntaxhighlight lang="java">
eof = f.EndOfFile();</syntaxhighlight>

----

===FileSize===
Gets the file size of the file, in bytes.

'''Parameters:''' none

'''Returns:''' size of file in bytes

'''Example:''' <syntaxhighlight lang="java">
size = f.FileSize();</syntaxhighlight>

----

===Flush===
Flushes the file buffer to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Flush();</syntaxhighlight>

----

===IsOpen===
Checks if the file is currently open. Usually used after a call to Open.

'''Parameters:''' none

'''Returns:''' true if file is open, false if not

'''Example:''' <syntaxhighlight lang="java">
if(f.IsOpen())
{
}</syntaxhighlight>

----

===Open===
Creates a new File Object.

'''Parameters:''' (filename, "text"/"binary", readonly<optional>, append<optional>)

'''Returns:''' true if success, false if failed.

'''Example:''' <syntaxhighlight lang="java">
if(f.Open("myfile.txt", "text", false))
{
}</syntaxhighlight>

----

===ReadFloat===
Reads a float from the file.

'''Parameters:''' none

'''Returns:''' float read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadFloat();</syntaxhighlight>

----

===ReadInt===
Reads an integer from the file.

'''Parameters:''' none

'''Returns:''' integer read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadInt();</syntaxhighlight>

----

===ReadLine===
Reads a string from a file until a newline or end of file is encountered.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadLine();</syntaxhighlight>

----

===ReadString===
Reads a string from a file.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadString();</syntaxhighlight>

----

===Seek===
Seeks the read/write position to a specified offset.

'''Parameters:''' (byte offset to seek to)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Seek(100); // seek 100 bytes into file</syntaxhighlight>

----

===Tell===
Returns the current offset of the read/write position in the file.

'''Parameters:''' none

'''Returns:''' byte position in file

'''Example:''' <syntaxhighlight lang="java">
t = f.Tell();</syntaxhighlight>

----

===Write===
Writes a value of varying types to the file, in whatever file mode was used to open the file.

'''Parameters:''' (...)

This function can take any number of parameters, of types integer, float, string, or System.NewLine.

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
assert( f.Write("Some test data", System.NewLine) );
}
f.Close();</syntaxhighlight>
----

Waypoint Library

2025-07-05T10:57:25Z

Palota: /* AddWaypoint */

{{process header
| title = Waypoint Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
== AddWaypoint ==
Creates a new waypoint at a specified location.

'''Parameters'''

<nowiki><Vector3></nowiki> The position to add waypoint.

<nowiki><optional Vector3></nowiki> The facing for the waypoint.

'''Returns'''

int Waypoint Id if successful OR null if there was an error adding waypoint.

'''Example'''
<syntaxhighlight lang="java">
Wp.AddWaypoint(Vector3(1000,2000,1000))</syntaxhighlight>

== CheckBlockable ==
Verifies all red blockable connections and changes them to green immediately if they are not blocked anymore. This function should be used in triggers of destroyable walls or constructible bridges. It prevents a lot of path failed errors. Objects destroyed by a dynamite usually also require sleep(0.1) before CheckBlockable.

'''Parameters'''

None

'''Returns'''

Count of changed connections, but the number is unreliable and can be zero.

== Connect ==
Connects two waypoints

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint.

<nowiki><int></nowiki> Guid of another waypoint.

'''Returns'''

true if successful, false if not

== DeleteWaypoint ==
Delete a waypoint from a specified location.

'''Parameters'''

<nowiki><Vector3></nowiki> <nowiki>The <Vector3> position to delete waypoint from.</nowiki>

'''Returns'''

true if successful, false if not

'''Example'''
<syntaxhighlight lang="java">
Wp.DeleteWaypoint(Vector3(1000,2000,1000))</syntaxhighlight>

== Disconnect ==
Disconnects two waypoints.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint.

<nowiki><int></nowiki> Guid of another waypoint.

'''Returns'''

true if successful, false if not

== GetAllWaypoints ==
Gets all waypoints.

'''Parameters'''

<nowiki><table></nowiki> An empty table, the function will fill tables of position, facing, guid, radius, name, flags, property.

'''Returns'''

None

'''Example'''
<syntaxhighlight lang="java">
wpTable = {};
Wp.GetAllWaypoints( wpTable );
foreach( waypoint in wpTable ) {
if( waypoint.name ) {
print(waypoint.name, "-", waypoint.position);
}
}

</syntaxhighlight>

== GetClosestWaypoint ==
Gets waypoint near position.

'''Parameters'''

<Vector3> position

<optional int> team

<optional options> 1=don't skip closed waypoints, 2=ignore waypoints without connections

'''Returns'''

<nowiki><table></nowiki>

'''Example'''
<syntaxhighlight lang="java">
w = Wp.GetClosestWaypoint( Vec3(100,200,0) );
if(w) {
print("waypoint UID ", w.guid);
}
</syntaxhighlight>

== GetAllSelectedWaypoints ==
Gets selected waypoints.

'''Parameters'''

<nowiki><table></nowiki> An empty table, the function will fill tables of position, facing, guid, radius, name, flags, property.

'''Returns'''

None

== GetWaypointByGUID ==
Gets a waypoint information by its guid.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint.

<nowiki><table></nowiki> An empty table, the function will fill in position, facing, guid, radius, name, flags, property.

'''Returns'''

true if successful, false if not

== GetWaypointByName ==
Gets a waypoint's information by its name.

'''Parameters'''

<nowiki><string></nowiki> The name of the waypoint to get the info of.

<nowiki><table></nowiki> An empty table, the function will fill in position, facing, guid, radius, name, flags, property.

'''Returns'''

true if successful, false if not

== IsWaypointViewOn ==
Checks if waypoint view is on.

'''Parameters'''

None

'''Returns'''

int true if waypoint_view is on, false if not

'''Example'''
<syntaxhighlight lang="java">
Wp.IsWaypointViewOn()</syntaxhighlight>

== Load ==
Loads waypoints from nav folder.

'''Parameters'''

<nowiki><optional string></nowiki> File name.

'''Returns'''

true if successful, false if not

== Save ==
Saves waypoints to nav folder.

'''Parameters'''

<nowiki><optional string></nowiki> File name.

'''Returns'''

true if successful, false if not

== SetRadius ==
Sets a wapoint radius.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint

<nowiki><int></nowiki> Radius.

'''Returns'''

true if successful, false if not

== SetWaypointFlag ==
Sets the [[Waypoint_Flags|flag]] on a waypoint by name.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint '''OR'''<nowiki> <string></nowiki> Name of the waypoint or a regular expression.

<nowiki><string></nowiki> The name of the flag to set '''OR''' <nowiki><table></nowiki> Multiple flags to set.

<nowiki><int></nowiki> True to set, false to clear.

'''Returns'''

None

'''Example'''
<syntaxhighlight lang="java">
Wp.SetWaypointFlag("waypointname", "closed", false);
Wp.SetWaypointFlag("bridge_.*", "crouch", true);
Wp.SetWaypointFlag("main_entrance", { "axis", "door" }, true );</syntaxhighlight>

== SetWaypointName ==
Assigns a name to a waypoint.

'''Parameters'''

<nowiki><int></nowiki> The id of the waypoint to set the name of.

<nowiki><string></nowiki> The name to assign to the waypoint.

'''Returns'''

true if successful, false if not

== SetWaypointProperty ==
Sets the waypoint property.

'''Parameters'''

<nowiki><int></nowiki> Guid of a waypoint '''OR'''<nowiki> <string></nowiki> Name of the waypoint.

<nowiki><string></nowiki> The name of the property to set.

<nowiki><string></nowiki> Property value to set.

'''Returns'''

None

== WaypointColor ==
Customize the color of various types of waypoints, paths, etc... See [[Waypoint_Commands#waypoint_color|waypoint_color]] command for help.

'''Parameters'''

<nowiki><string></nowiki> The name of the category to set a color for.

<nowiki><int></nowiki> The color to use for this type.

'''Returns'''

None

=Properties=

== BlockablePathOffset ==
the offset for blockable paths for drawing purposes.

== BottomPathOffset ==
the offset for path bottom for drawing purposes.

== BottomWaypointOffset ==
the offset for waypoint bottom for drawing purposes.

== FacingOffset ==
the offset for drawing the facing indicator.

== PathLevelOffset ==
relative offset for path finding, default is 0.5

== TextDuration ==
drawing duration for texts, default is 2 seconds

== TextOffset ==
the offset for drawing waypoint name, UID, radius, flags.

== TopPathOffset ==
the offset for path top for drawing purposes.

== TopWaypointOffset ==
the offset for waypoint top for drawing purposes.

Supported Games

2025-07-01T11:12:53Z

Palota:

{{process header
| title = Supported Games
| section =
| previous = [[Main_Page | Main Page]]
| next =
| shortcut =
| notes =
}}

== [[Gameet | Enemy Territory]] ==

Enemy Territory is a free for [https://www.etlegacy.com/ download] team based game that currently is the most advanced in terms of bot support as it has been focused on more than other games.

Omni-bot has been integrated into many of the popular ET mods ([http://etpub.org/ etpub], [http://jaymod.clanfu.org/ jaymod], noquarter ...) , which contain enhancements, fixes, additional weapons, etc on top of the ET game type. Supported mods versions are listed on page [[Download_Omni-Bot_ET]].

== [[Gamertcw | Return to Castle Wolfenstein]] ==

[http://www.idsoftware.com/games/wolfenstein/rtcw/ Return to Castle Wolfenstein] game is similar to Enemy Territory. All scripts and commands have been recently updated to the latest Omni-bot version.

== [[Fortressforever | Fortress Forever]] ==

[http://www.fortress-forever.com/ Fortress Forever] is a Team Fortress modification for [https://www.half-life.com/es/halflife2 Half-life 2]. Omni-bot will come with the default installation for training and scrimmage purposes, with training scripts targeted to helping those that are new to Team Fortress, as it can be a difficult game to attract new players.

== [[Quake4| Quake 4]] ==

[http://www.quake4game.com/ Quake 4] by [http://www.ravensoft.com/ Raven Software] has had an alpha Omni-bot release in an early version.

== [[Doom3 | Doom 3]] ==

[http://www.doom3.com/ Doom 3] by [http://www.idsoftware.com/ id software] has joined the Omni-bot supported games list. It was supported by Geekfeststarter. There has not been a public release.

== Want to support Omni-bot? ==
Omni-bot support is added to a mod by adding a lightweight interface file to the mod that compiles into it and communicates with the bot dll. After that, all the bot behavior is handled in the bot dll. If you are a minor variation of an existing supported game, chances are your mod can use the same dll, like Jaymod, etpub, NQ.

Faqomnibot

2025-07-01T10:23:31Z

Palota: /* How do I customize the bots names ? */

== Omni-Bot F.A.Q.==
=== General Questions ===
==== How do I customize the bots names ? ====

ET and RTCW games have bots names in files '''et_botnames_ext.gm''' and '''rtcw_botnames_ext.gm'''. Other games have names in autoexec. For Quake4 it is called '''q4_autoexec.gm''', and so on.

Inside you will see a table being constructed that associate names with a profile script.

Here's what the '''q4_autoexec.gm''' looks like at the time of this writing.

Names["[BOT]Walter"] = "def_bot.gm";
Names["[BOT]Fred"] = "def_bot.gm";
Names["[BOT]Morgan"] = "def_bot.gm";
Names["[BOT]Lawrence"] = "def_bot.gm";
Names["[BOT]Richard"] = "def_bot.gm";
Names["[BOT]Michael"] = "def_bot.gm";
Names["[BOT]Brad"] = "def_bot.gm";
Names["[BOT]George"] = "def_bot.gm";
Names["[BOT]Anton"] = "def_bot.gm";
Names["[BOT]Monty"] = "def_bot.gm";
Names["[BOT]Bean"] = "def_bot.gm";
Names["[BOT]Sean"] = "def_bot.gm";
Names["[BOT]Backfire"] = "def_bot.gm";
Names["[BOT]Halfwit"] = "def_bot.gm";
Names["[BOT]Halfbaked"] = "def_bot.gm";
Names["[BOT]Fullmonty"] = "def_bot.gm";
Names["[BOT]Nohope"] = "def_bot.gm";
Names["[BOT]Hitnrun"] = "def_bot.gm";
Names["[BOT]Missnrun"] = "def_bot.gm";
Names["[BOT]Oysterhead"] = "def_bot.gm";
Names["[BOT]Fullthrottle"] = "def_bot.gm";
Names["[BOT]Noammo"] = "def_bot.gm";
Names["[BOT]Bullseye"] = "def_bot.gm";
Names["[BOT]Aimless"] = "def_bot.gm";
Names["[BOT]Blackadder"] = "def_bot.gm";

When a bot is added to the game without a name specified, it will choose a random available name from the ones listed. Each name has a profile associated with it, in this case all of these names have def_bot.gm, which is typically common for most games. The profile script is a way to customize a particular bot. You can script additional features or modifications to existing features into a script and associate the script with a specific bot name in order to have varying yet consistent behavior.
Look [[Main_Page#Customizing_Omni-bot|here]] for more on customizing your Omni-bots.

'''To add additional names, simply add another line with a new name.'''

Normally there should be at least as many names as there are player slots available in the game, though you can add more and Omni-bot will randomly choose between all of them.

Small note : you don't have to add the prefix [BOT] to the name of the bot, but it would be fair or at least informative to let the players on your server know in a glance that Omni-bot is enabled and running.

=== ET Related ===
====How To Adjust The Difficulty====
Use command /bot difficulty

====How To Edit Waypoints====

Here you have the [[Template:Basewaypointing|Omni-bot Waypointing]] general info page.

====How To use Custom Waypoints====

When you've downloaded a custom map, your Omni-bots will need a waypoint file for that map.

When you've downloaded a waypoint file for a custom ET map, you simply put the *.way and *.gm files inside your : ... \et\nav directory.

Currently released waypoints can be found in the Assembla SVN repository.

====How To Run Omni-bot On Windows(tm) Home Server====

Here's a small description on how to make a quick -vanilla ET + Omni-bot server run on your Win32 home computer.
You should be able to let some Omni-bots run and also view and edit or create waypoints for the maps with it.

If not already :
* Install Wolfenstein:Enemy Territory
* Run the patch 2.60b
* Install the latest Omni-Bot version

When the above is installed you'll see a new shortcut in your Start Menu : Omni-Bot ET. The new shortcut is also on your desktop.
When you click on this shortcut you will start Enemy Territory with the mod : Omni-bot.
In this way you will still have to go through the ingame menu to host and or play on your own server.

To avoid this hassle every time here below there's the double click way to start your own server.
Make a shortcut like this on your desktop or wherever you want :

"C:\Program Files\Wolfenstein - Enemy Territory\ET.exe" +set dedicated 0 +set fs_game omnibot +set com_hunkmegs 64 +exec server.cfg

*+set dedicated 0 *''a server, to be played on as well by the server host (=you)''
*+set fs_game omnibot *''set the gametype, make sure to set this if you want to start waypointing''
*+set com_hunkmegs 64 *''allocates a certain amount of memory for map and item loading''
*+exec server.cfg *''server settings, your server configuration file which gets executed, in directory 'etmain, if you put a .cfg in your modfolder this gets executed, this comes in handy if you want to run different mods'''

Note : The above settings are called Cvar's (server variables).

After you made the shortcut, you should be able to start and run the Omni-bot server with it.

More and in depth info:
[https://wolffiles.de/filebase/ET/Stuff/ET-Serverguide.pdf Advanced Wolfenstein: Enemy Territory Server Setup Guide]

====How To Run Omni-bot On Linux Home Server====

#et +set fs_game omnibot +set com_hunkmegs 64

Make sure you've read the information on [[Gameet#Installation|Installing Omni-bot]].

====How To Quickly Add The Omni-bots To Your server====

There are -in short- 3 ways :

* Via the : [[Omni-bot_Command_Reference#minbots|MinBots]] & [[Omni-bot_Command_Reference#maxbots|MaxBots]] Omni-bot commands *''set those in your et_autoexec.gm. file, in the directory 'scripts'''
* Via the [[Bot_Library#AddBot|'bot addbot']] console command, f.e to add a Axis Covert type : "\bot addbot 1 5 Covert-Axis"
* Via a omni-bot.cfg, a file in which you put the above [[Omni-bot_Command_Reference#addbot|'bot addbot']] command as many times you want a bot with a selected class.

Example 1 omni-bot.cfg :
<pre>
// start
// bot addbot <team> <class> <name>
// save f.e as : omni-bot.cfg -in same folder where your server.cfg is-
// put the line : exec omni-bot.cfg in your server.cfg to add bots automatic on map start
bot addbot 1 1 Soldat-Axis
bot addbot 1 2 Sani-Axis
bot addbot 1 3 Engi-Axis
bot addbot 1 4 Leut-Axis
bot addbot 1 5 Covert-Axis
bot addbot 2 1 Soldier-Allied
bot addbot 2 2 Medic-Allied
bot addbot 2 3 Engi-Allied
bot addbot 2 4 Leut-Allied
bot addbot 2 5 Covert-Allied
// eof
</pre>

Example 2 omni-bot2.cfg :
<pre>
// start
bot minbots 0
bot maxbots 10
// eof
</pre>

Example 3 omni-bot3.cfg :
<pre>
// kicks all bots from server
// start
bot kickall
// eof
</pre>

==== Omni-bot and Other Mods ====

Running Omni-bot with Wolfenstein:Enemy Territory is also possible in combination with several other mods.

Setting up a mod server to run with Omni-bot isn't much different from running Omni-bot with vanilla etmain.

*Reassure yourself that the Omni-bot & mod version you are trying to run are fully compatible. (See [[Download Omni-Bot ET]])
*Use the included readme file in the mod folder or check their website and or forum, f.e. to get more info on Omni-bot specific cvars for your mod.
*'''Important Note''' : waypoints can be edited only in omnibot mod.

==== Mod Folders & Mod Versions ====
The modfolders called omnibot, jaymod, etpub & noquarter should all (if installed) be at the same level as the etmain folder.
<br>
So after you install the mod you can create a new shortcut that points to the specific mod (folder) like :

*ETPub
"C:\...\ET.exe" +set fs_game etpub +set com_hunkmegs 64 +exec pubserver.cfg

*Jaymod
"C:\...\ET.exe" +set fs_game jaymod +set com_hunkmegs 64 +exec jayserver.cfg

*NQ
"C:\...\ET.exe" +set fs_game noquarter +set com_hunkmegs 64 +exec nqserver.cfg

You'll notice that the only thing in the shortcut line changing is the setting of fs_game.

Also you can set some Cvars which are specific to your mod into your (mod)server.cfg.

{| border="1" cellpadding="5" cellspacing="0"|colspan="3"|

==== Mod Specific Cvars ====

{| class="wikitable sortable" border="1" cellpadding="5" cellspacing="1"
! ET Mod
! Omni-bot Specific Cvars Link
! Mod Version Documentation Link
|--
|[http://www.etpub.org/news.php ET Pub]
|[http://etpub.org/ETPubServerDocs.html#omnibot_flags Omni-bot ET Pub 0.8.1 ]
|[http://etpub.org/ETPubServerDocs.html#gen 0.8.1]
|--
|[http://jaymod.clanfu.org/ Jaymod]
|[http://www.clanfu.org/jaymod/2.1.6/html/omni.html Omni-bot Jaymod]
|[http://www.clanfu.org/jaymod/2.1.5/html/index.html 2.1.5] [http://www.clanfu.org/jaymod/2.1.6/html/index.html 2.1.6] [http://www.clanfu.org/jaymod/2.1.7/html/index.html 2.1.7]
|--
|[http://shitstorm.org/noquarter/wiki/index.php?title=Main_Page NQ]
|[http://shitstorm.org/noquarter/wiki/index.php?title=No_Quarter_Mod#Omni-Bot_Enabling Omni-bot NQ]
|[http://shitstorm.org/noquarter/wiki/index.php?title=Admin_CVARs#omnibot_enable_.28New_in_1.1.1.29 1.1.1]


|-
|}

Note :

Version [http://jaymod.clanfu.org/index.php?date=2007-04-10 2.0.6 of Jaymod] is the latest of the "stable" branch and runs with [http://www.omni-bot.de/e107/download.php?list.2 Omni-Bot version 0.61.]

====General Cvars====

Whatever mod you are running, the server.cfg needs to be configured before players can connect.
If you are renting a server then your game server provider will probably do the initial configuration for you.

The list is not to be said : complete.
You as a server admin have to tweak it !

Here below are the most common ones.

* set dedicated "2" : ''change to 1 if you use the server on a LAN, change to 0 if you use it to be played on as well by the server host (=you)''
* set net_ip "" : ''set to override the default IP ET uses. No need to change''
* set net_port "27970" : ''set to override the default port ET uses. Default port is 27960 but some server providers use other ports. Should already be set correctly if you rent a server''
* set sv_maxclients "22" : ''number of maximum players that can be connected on the server including private slots. If you are renting then this is controlled by your provider and changing it will have no effect''
* set g_password "" : ''set a password to lock the server. Players will be prompted for password when they connect. You can lock server e.g. during scrims''
* set sv_privateclients "2" : ''if set > 0, then this number of client slots will be reserved only for people who have the privatepassword (see below)''
* set sv_privatepassword "your password" : ''if you have defined private slots then you should define a password for them as well''
* set rconpassword "your_rcon_ password" : ''this is the most important password. Access to it should be strictly restricted to people who change the configuration and manage the server at this level. People who have this password can have full server control''
* set refereePassword "your_ref_password" : ''this will set the password for a referee. If you are running any of the mods this will be useful because you can assign people referee status to administer the server. Referees can shuffle teams, put players in teams or spectator, kick players etc. Again, be careful about who you give ref access.''
* set sv_wwwDownload "1" : ''if you have custom maps on your server then make sure you have this set at 1. Otherwise players won't be able to download them''
* set sv_wwwBaseURL "http://myre-direct.com" : ''if you are re-directing your downloads then here is where you set the url.''
* set g_friendlyFire "1" : ''set this to 0 if you don't want Friendly Fire on i.e. if set to 1, you can kill your team mates''
* set g_teamforcebalance "1" : ''if you have this set to 1 then the server won't allow a player to join a team which has already one player more than the other team. If set to 0 then it will be easier to end up with unequal teams in terms of numbers''
* set g_voiceChatsAllowed "4" : ''this is the maximum number of chats someone can spam chat with. Make this too big and you risk a lot of spamming''
* set g_warmup "60" : ''warm-up time i.e. the number of seconds prior to starting the game. Make sure this is long enough to allow players to connect after the end of the previous map. You can increase it e.g. during scrims to allow people more time to organise''
* set vote_allow_kick "1" : ''if you set this as 1 then players will be allowed to vote-kick someone out of the server''
* exec maprotation.cfg : ''set this as your map rotation config file.''

===General Server Setup Tips===

*Use a 'shortcut' to startup your server.

*Start your server with a 'basic settings' server.cfg. (f.e. for ET use the server.cfg in your mod folder)

*Make back-ups of (all) your server configuration files!

*Add the cvars you want to run the server with gradually, so you can always revert to a previous version when something is wrong.

Utility Functions

2025-06-30T08:59:04Z

Palota: /* ETUtil.SetCabinets */

{{process header
| title = Utility Functions
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

{{TOCright}}

=== Util ===

==== Util.AddUsePoint ====

<syntaxhighlight lang="java">
syntax: Util.AddUsePoint(goalname, <Vector3 or table>);
example: Util.AddUsePoint("PLANT_wall",{Vec3(12,34,5),Vec3(23,5,67)});</syntaxhighlight>

used to add use points for a goal at given positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AddUseWp ====

<syntaxhighlight lang="java">
syntax: Util.AddUseWp(goalname, <waypointname or table>);
example: Util.AddUseWp( "somegoalname", "somewaypointname" );</syntaxhighlight>

used to add use points for a goal at given waypoints positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AliveCount ====

<syntaxhighlight lang="java">
syntax: Util.AliveCount( team, class );
example: Util.AliveCount( TEAM.AXIS, CLASS.MEDIC ); </syntaxhighlight>

returns the number of bots alive on a team with a given class

==== Util.BotChat ====

<syntaxhighlight lang="java">
syntax: Util.BotChat(Team, msgType, Msg, NumBots);
example: Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_CHEER, 2);
</syntaxhighlight>

See [[Talking_bots]] page

==== Util.BotHasAnyRole ====

This function is deprecated. Use [[Bot#HasRole|HasRole]]

==== Util.CanBotSnipe ====

<syntaxhighlight lang="java">
syntax: Util.CanBotSnipe(bot);
example: if ( Util.CanBotSnipe(bot) ) {
</syntaxhighlight>

returns true if bot has a sniper weapon.

==== Util.CappointForFlag ====
<syntaxhighlight lang="java">
syntax: Util.CappointForFlag( flag_goalname, cappoint_goalname );
example: Util.CappointForFlag( "FLAG_axis_gold", "CAPPOINT_Truck" );
</syntaxhighlight>

used if there are multiple active cappoint goals. It should be called from _Taken triggers.

==== Util.ChangeBotSpawn ====
This function is deprecated. See [[Changing spawns]].

==== Util.ChangeCrucialClassForRole ====
<syntaxhighlight lang="java">
syntax: Util.ChangeCrucialClassForRole ( team, role, class );
example: Util.ChangeCrucialClassForRole(TEAM.AXIS, ROLE.DEFENDER1, CLASS.COVERTOPS);
</syntaxhighlight>

Sets new crucialClass in the Map.Roles table.

==== Util.ChangeSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.ChangeSpawnForRole ====

<syntaxhighlight lang="java">
syntax: Util.ChangeSpawnForRole( <team>, <role>, <spawnpoint> );
example: Util.ChangeSpawnForRole(TEAM.ALLIES, ROLE.ATTACKER, 1);
</syntaxhighlight>

Set the spawn point for all bots on the given team with the given role

see also: [[Roles]] Page

==== Util.ChangeToSniperWeapons ====

<syntaxhighlight lang="java">
syntax: Util.ChangeToSniperWeapons( bot, <optional viewDistance> );
example: Util.ChangeToSniperWeapons(bot);
</syntaxhighlight>

called from OnBotJoin on sniper maps.

see also: [[Sniper_and_Panzer_maps]]

==== Util.ClearRoleForGoals ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.ClearRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.ClearRoleForGroup( group, <role or table> );
example: Util.ClearRoleForGroup( "someGroup", ROLE.DEFENDER );
</syntaxhighlight>

used to remove roles from a given group of goals

see also: [[Roles]] Page

==== Util.ClearRoleForTable ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.DisableGoal ====

<syntaxhighlight lang="java">
syntax: Util.DisableGoal(goalname, <optional true>);
example: Util.DisableGoal("FLAG_someflag"); </syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== Util.DisableGroup ====

<syntaxhighlight lang="java">
syntax: Util.DisableGroup(groupname, team);
example: Util.DisableGroup( "somegroupname", TEAM.ALLIES );</syntaxhighlight>

used to disable a set of goals in the given group for a given team

==== Util.EnableGoal ====

<syntaxhighlight lang="java">
syntax: Util.EnableGoal(goalname);
example: Util.EnableGoal("FLAG_someflag");</syntaxhighlight>

enables the goal for both teams.

==== Util.EnableGroup ====

<syntaxhighlight lang="java">
syntax: Util.EnableGroup(groupname, team);
example: Util.EnableGroup( "somegroupname", TEAM.SOMETEAM );</syntaxhighlight>

used to enable a set of goals in the given group for a given team

==== Util.ExcludeClass ====

<syntaxhighlight lang="java">
syntax: Util.ExcludeClass( goalname, team, class1, class2, class3, class4 );
example: Util.ExcludeClass( "DEFEND_somegoal.*", TEAM.AXIS, CLASS.MEDIC );
example: Util.ExcludeClass( "MOUNTMG42_.*", TEAM.ALLIES, CLASS.FIELDOPS, CLASS.ENGINEER );
</syntaxhighlight>

limit given goal usage to specific classes by team. class2, class3, and class4 are optional.

==== Util.ForceRouting ====

<syntaxhighlight lang="java">
syntax: Util.ForceRouting(goalName, true/false);
example: Util.ForceRouting( "BUILD_Tank", true );</syntaxhighlight>

disables BUILD goal offsets and enables routes to the goal. You should set ForceRouting to true only when a vehicle is at known position (in OnMapLoad or at tank barriers). You must set it to false when a vehicle is repaired.

==== Util.GetEntHealth ====

<syntaxhighlight lang="java">
syntax: Util.GetEntHealth(entity);
example: health = Util.GetEntHealth(this.TargetEntity);</syntaxhighlight>

returns entity health.

==== Util.GetGroup ====

<syntaxhighlight lang="java">
syntax: Util.GetGroup(groupname);
example: Util.GetGroup("somegroupname");</syntaxhighlight>

this function will return a table of goals belonging to the given group name

==== Util.GetRandomFromTable ====

<syntaxhighlight lang="java">
syntax: Util.GetRandomFromTable( tbl );
example: index = Util.GetRandomFromTable( someTable );
</syntaxhighlight>

used to get a randomly selected index from a given table. Returns -1 if invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GetRandomTableValue====

<syntaxhighlight lang="java">
syntax: Util.GetRandomTableValue( tbl );
example: value = Util.GetRandomTableValue( someTable );
</syntaxhighlight>

used to get a randomly selected value from a given table. Returns null if the table is empty or invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GoalTable ====

<syntaxhighlight lang="java">
syntax: Util.GoalTable( <optional expression>, <optional teamId> );
example: goals = Util.GoalTable("PLANT_Back_Door");
example: goals = Util.GoalTable("FLAG.*", TEAM.AXIS);
</syntaxhighlight>

returns table of map goals that match a regular expression.

==== Util.IgnoreTargetGoal ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IgnoreTargetGoalTable ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IsBot ====

<syntaxhighlight lang="java">
syntax: Util.IsBot(entity);
example: bot = Util.IsBot(ent);
</syntaxhighlight>

returns Bot object from entity or null if entity is not a bot. Usually used in region triggers if the TriggerOnClass is CLASS.ANYPLAYER.

==== Util.LimitToClass ====

<syntaxhighlight lang="java">
syntax: Util.LimitToClass(goalname, team, class1, class2, class3, class4);
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER); //only soldiers on the allied team
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER, CLASS.MEDIC); //only soldiers and medics</syntaxhighlight>

used to limit specific goals to a specific class or classes

==== Util.LimitToTeam ====

<syntaxhighlight lang="java">
syntax: Util.LimitToTeam(team, goal);
example: Util.LimitToTeam(TEAM.AXIS, "SWITCH_gate_depot");
</syntaxhighlight>

limits goals to a certain team without the need to disable for 1 team

==== Util.MapDebugPrint ====

<syntaxhighlight lang="java">
syntax: Util.MapDebugPrint( "Text", <optional message only> );
example: Util.MapDebugPrint( "East_Barrier_Destroyed" );
example: Util.MapDebugPrint( "East_Barrier_Destroyed", true ); // only print the message
</syntaxhighlight>

used to print text & list of available goals in the console when in debug mode

see also: [[Debugging_tips]]

==== Util.OnTriggerPosition ====

<syntaxhighlight lang="java">
syntax: Util.OnTriggerPosition( goalname, wpname or position, tolerance, wpfunction );
example: Util.OnTriggerPosition( "MOVER_train1", "depotyard", 200.0, Map.tug_depotyard );</syntaxhighlight>

note: used for setting up positional triggers for movers.

==== Util.RandomBotSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RandomSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RemoveGoal ====

<syntaxhighlight lang="java">
syntax: Util.RemoveGoal( goalnames );
example: Util.RemoveGoal( "MOVER_truck" );</syntaxhighlight>

removes the goals from the map goal table. It should only be used for invalid goals which are badly detected by the game.

==== Util.Routes ====

<syntaxhighlight lang="java">
syntax: Util.Routes( <table> );
example: Util.Routes(MapRoutes);</syntaxhighlight>

initializes routes

see also: [[Template:Baserouting|Routing]]

==== Util.SetGoalOffset ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalOffset( x, y, z, GoalName );
info x = North, -x = South y = East, -y = West, z = Up, -z =Down
example: Util.SetGoalOffset( 0, -20, -10, "MOUNTMG42_boat" );</syntaxhighlight>

the x y and z parameters are added to the origin of the goal to move the location of where bots will look for the goal. It is sometimes needed for MOUNTMG42 and REPAIRMG42 goals because some mg42 cannot be mounted or repaired if it's position is not corrected.

==== Util.SetGoalPosition ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalPosition( x, y, z, GoalName );
example: Util.SetGoalPosition( 4534, 2168, -199, "BUILD_construct" )</syntaxhighlight>

used to give the goal a new origin.

note: it's usually much better to use function Util.AddUsePoint to set position of BUILD or PLANT goals.

note: console command "/bot mypos" prints your body position, command "/viewpos" prints your eye position rounded to integer.

==== Util.SetGoalRange ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalRange( goalNames, distance or AABB );
examples:
Util.SetGoalRange("GRENADE_tower.*", 800);
Util.SetGoalRange("PLANT_SideGate", AABB(-2785,-3579,65,2702,-1306,257));
//reset to unlimited
Util.SetGoalRange("GRENADE_tower.*", 0);
Util.SetGoalRange("PLANT_SideGate", AABB());</syntaxhighlight>

sets the range for map goals. It can be int radius or AABB box or both. The QueryGoals functions does not return goals which are out of range. Default range for all goals is unlimited. Goals will not be interrupted if the range changes after the bot has already activated the goal.

==== Util.SetGroup ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetGroupForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetMaxUsers ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsers( botnum, goal );
example: Util.SetMaxUsers( 1, "ATTACK_.*" );
</syntaxhighlight>

used to limit number of bots using a particular goal(s). this function sets both In_Use and In_Progress

==== Util.SetMaxUsersInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInProgress( Users, GoalNames );
example: Util.SetMaxUsersInProgress( 15, "CHECKPOINT.*" );</syntaxhighlight>

used to set the maximum number of bots going for a particular goal(s).

==== Util.SetMaxUsersInUse ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInUse( Users, GoalNames );
example: Util.SetMaxUsersInUse( 1, "MOUNT_.*" );
</syntaxhighlight>

used to set the maximum number of bots using a particular goal(s).

==== Util.SetPercentInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetPercentInProgress(%, goal);
example: Util.SetPercentInProgress(70, "FLAG_docs");
</syntaxhighlight>

sets a percentage of bots to use a particular goal(s).

note: number of bots is calculated only once when this function is called. It does not work well after bots are added or kicked.

==== Util.SetPositionGoal ====

<syntaxhighlight lang="java">
syntax: Util.SetPositionGoal( goalname1, goalname2 );
example: Util.SetPositionGoal( "BUILD_Tank", "MOVER_tank" );</syntaxhighlight>

sets the origin of one goal to match the origin of another. This function was used in Omni-bot 0.66. Current Omni-bot version automatically sets positions of BUILD goals.

==== Util.SetRoleForGoals ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

==== Util.SetRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.SetRoleForGroup( <goal group>, <role or table> );
example: Util.SetRoleForGroup( "myGroup", ROLE.DEFENDER );
</syntaxhighlight>

sets the given roles for the given group of goals.

==== Util.SetRoleForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

see also: [[Roles]] Page

==== Util.ShowGroup ====

<syntaxhighlight lang="java">
syntax: Util.ShowGroup(groupname);
example: Util.ShowGroup("somegroupname");</syntaxhighlight>

this function will list all goals in the given group in the console.

==== Util.UpdateSwitchData ====

This function is deprecated. Use [[Switch_Goal]]

==== Util.WpNameInfo ====

<syntaxhighlight lang="java">
syntax: Util.WpNameInfo(waypointName);
example: wpInfo = Util.WpNameInfo("rNadeHall");</syntaxhighlight>

finds waypoint by name and returns table which contains position, facing, radius, flags, property. It is often used in paththrough navigation.

=== ETUtil ===
These functions are available only in the Enemy Territory game.

==== ETUtil.ChangeToPanzer ====

<syntaxhighlight lang="java">
syntax: ETUtil.ChangeToPanzer( bot );</syntaxhighlight>

called from OnBotJoin on panzer maps.

see also: [[Sniper_and_Panzer_maps]]

==== ETUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: ETUtil.CountClass( team, class );
example: ETUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== ETUtil.GetReinforceTime ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetReinforceTime(TEAM.AXIS);
</syntaxhighlight>

returns time to next respawn, or null if no bot exists in the team.

==== ETUtil.GetTimeElapsed ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetTimeElapsed();
</syntaxhighlight>

returns time since map start.

==== ETUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamClassDead( team, class );
example: ETUtil.IsTeamClassDead( TEAM.AXIS, CLASS.MEDIC );
</syntaxhighlight>

returns true if all the players of the given class on the given team are dead.

==== ETUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamDead( team );
example: ETUtil.IsTeamDead( TEAM.AXIS );
</syntaxhighlight>

returns true if all players on the given team are dead.

==== ETUtil.KillTeam ====

<syntaxhighlight lang="java">
syntax: ETUtil.KillTeam( team, <optional maxTime> );
example: ETUtil.KillTeam( TEAM.AXIS, 15 );
</syntaxhighlight>

waits for next respawn and then kills all bots in the team, but only if time to next respawn is not greater than maxTime.

==== ETUtil.LosingChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.LosingChat(team);
example: ETUtil.LosingChat( TEAM.AXIS );
</syntaxhighlight>

See [[Talking_bots]] page

==== ETUtil.SelectWeapon ====

This function does not work since version 0.82. Now you have to use [[Utility_Functions#WeaponTable|WeaponTable.SetWeaponAvailability]].

==== ETUtil.SetAimModeForMount====

<syntaxhighlight lang="java">
syntax: ETUtil.SetAimModeForMount(goalName, aimType);
example: ETUtil.SetAimModeForMount("MOUNT_ship", Vec3(-340, 1530, 90));</syntaxhighlight>

Sets AimMode property of MOUNT goal. Valid values are "velocity", "opposite", "random" or Vector3.

==== ETUtil.SetExcludeIndexes ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetExcludeIndexes( goal, { offset } );
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", { 4, 5, 6 } ); // Disable offset 4, 5 & 6
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", {} ); // Removes Disabled offsets
</syntaxhighlight>

disables vehicle offsets, used when an offset cannot be reached. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SetStartIndex ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetStartIndex(goal, offset);
example: ETUtil.SetStartIndex("ESCORT_tank", 2); // Use Offset 2
example: ETUtil.SetStartIndex("ESCORT_tank", -1); // Random
</syntaxhighlight>

used to make a bot start from a certain vehicle offset in mover goals that have offsets defined. Normally set in OnMapLoad then reset inside a trigger. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SuicideSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.SuicideSpawn( team, spawn, numbots, class);
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, 1, CLASS.ENGINEER ); // 2 bots spawn at spawnpoint 2
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, -1, CLASS.ENGINEER ); // all axis engineer bots spawn at spawnpoint 2
</syntaxhighlight>

used to make bots self kill and change to a new spawn, often used in maps to defend areas when players have sneaked past.

==== ETUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: ETUtil.SwitchWeapon(weapon);
example: ETUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer</syntaxhighlight>

This function is deprecated since version 0.82 because it only kills bot and does not change his weapon.

==== ETUtil.WaitForSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.WaitForSpawn(Team);
example: ETUtil.WaitForSpawn( TEAM.ALLIES );
</syntaxhighlight>

Sleeps until next respawn of the team. Returns 0.15 seconds before respawn.

==== ETUtil.WinningChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.WinningChat(Team);
example: ETUtil.WinningChat( TEAM.ALLIES );
</syntaxhighlight>

See [[Talking_bots]] page

=== RTCWUtil ===
These functions are available only in the Return to Castle Wolfenstein game.

==== RTCWUtil.BotDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.BotDisableCombatCrouch( bot, bool enable );
example: RTCWUtil.BotDisableCombatCrouch( bot, true );
</syntaxhighlight>

used to disable crouching in combat for the given bot

==== RTCWUtil.ChangeClass ====

This function is deprecated. Use Server.MinClassCount.

==== RTCWUtil.ChangeSpawnNoDefenders ====

This function is deprecated. See [[Changing spawns]].

==== RTCWUtil.ClearMainGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearMainGoals();</syntaxhighlight>

This function will deactivate all main goals for both teams.

goals deactivated: PLANT MOUNTMG42 MOVER CHECKPOINT FLAG

==== RTCWUtil.ClearSecondaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearSecondaryGoals();</syntaxhighlight>

This function will deactivate all secondary goals for both teams.

goals deactivated: ARTILLERY REPAIR

==== RTCWUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.CountClass( team, class );
example: RTCWUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== RTCWUtil.CountTeam ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.DisableGoal(goalname, <optional true>);
example: RTCWUtil.DisableGoal("FLAG_someflag");
</syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== RTCWUtil.IsPlantGoalAvailable ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsPlantGoalAvailable();
example: RTCWUtil.IsPlantGoalAvailable();
</syntaxhighlight>

returns true if there is a plant goal available

==== RTCWUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamClassDead( team, class );
example: RTCWUtil.IsTeamClassDead( TEAM.AXIS, CLASS.ENGINEER )
</syntaxhighlight>

returns true if there are no living players or bots of a given class on the given team

==== RTCWUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamDead( team, minbots );
example: RTCWUtil.IsTeamDead( TEAM.AXIS, 2 );
</syntaxhighlight>

returns true if the number of living players on the given team is less than minbots.

note: minbots is optional as it defaults to 1

==== RTCWUtil.KillEntities ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.KillEntities( table or int );
example: RTCWUtil.KillEntities( 123 );
example: RTCWUtil.KillEntities( {123, 124} );
</syntaxhighlight>

used to remove entities from the map. typically called from OnMapLoad

==== RTCWUtil.NoSnipe ====

<syntaxhighlight lang="java">
syntax: syntax: RTCWUtil.NoSnipe(bot);</syntaxhighlight>
soldier bots will not choose a mauser when selecting a weapon

note: this is typically called in OnBotJoin

==== RTCWUtil.SelectSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in OnBotJoin to have soldiers choose between given weapons
example: RTCWUtil.SelectSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SelectSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser</syntaxhighlight>

==== RTCWUtil.SelectWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectWeapon(bot, weapon, isFog);
example: RTCWUtil.SelectWeapon(bot, WEAPON.MAUSER);

</syntaxhighlight>

the given bot will switch to the given weapon if it is the correct class for the weapon

note: typically used in OnBotJoin to have soldiers choose a specific weapon
the isFog parameter is optional and disables extra view distance given to snipers

==== RTCWUtil.SetPrimaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetPrimaryGoals(priority);
</syntaxhighlight>

used for setting priorities of common goals.

note: this is typically called in OnMapLoad and effects the following goals (in order of priority):
CAPPOINT FLAGRETURN PLANT CHECKPOINT FLAG

==== RTCWUtil.SetSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, class, suicide, persistant);
sets all classes on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.SetTeamSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, suicide, persistant);
sets all bots on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.StopSniping ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.StopSniping();</syntaxhighlight>
all bots currently using a sniper weapon will switch to a different weapon

note: this is typically called inside trigger functions

==== RTCWUtil.SwitchSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in triggers to have soldiers choose between given weapons
example: RTCWUtil.SwitchSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SwitchSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser
</syntaxhighlight>

==== RTCWUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchWeapon(weapon);
all qualifying bots will switch to the given weapon

example: RTCWUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer
note: typically used in trigger functions</syntaxhighlight>

==== RTCWUtil.TeamDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.TeamDisableCombatCrouch( team );
example: RTCWUtil.TeamDisableCombatCrouch( TEAM.AXIS );
</syntaxhighlight>

disables combat crouching for the given team

==== RTCWUtil.ToggleFlag ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ToggleFlag( goal, time in seconds );
example: thread(RTCWUtil.ToggleFlag, "CHECKPOINT.someFlag", 300);
</syntaxhighlight>

used in dual objective maps like mp_depot to set availability of the checkpoint goal for the opposite team in the given interval
note: this should be called as a gm thread.

=== WeaponTable ===

==== WeaponTable.ListWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.ListWeaponAvailability();
</syntaxhighlight>

prints current availability of all weapons

==== WeaponTable.SetWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponAvailability( class, weapon, <true/false>);
example: WeaponTable.SetWeaponAvailability( CLASS.SOLDIER, WEAPON.FLAMETHROWER, false );</syntaxhighlight>

enables or disables specified weapon for class. The weapon parameter can be table.
The class parameter can be null to set availability for all classes.

note: allied PANZERFAUST is automatically converted to BAZOOKA or LAW in Noquarter or ETnam

note: bots select random available weapon every spawn (in limbo)

==== WeaponTable.SetWeaponTeamAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponTeamAvailability( team, class, weapon, <true/false>);
example: WeaponTable.SetWeaponTeamAvailability( TEAM.AXIS, CLASS.ENGINEER, WEAPON.KAR98, false );</syntaxhighlight>

enables or disables weapon for team and class.

==== WeaponTable.Shotgun ====

The Shotgun property has value WEAPON.SHOTGUN, WEAPON.ITHACA, WEAPON.M97 or null.

Template:Baserouting

2025-06-23T08:08:46Z

Palota: /* Step 6: Copying routes */

[[Category:ET|Routing]]
[[Category:Doom 3|Routing]]
[[Category:Quake 4|Routing]]
[[Category:RTCW|Routing]]
[[Category:Waypointing]]
==Routing Overview==

Until version 0.65, omni-bot path selection relied on the shortest path to a goal. While this typically provided for very focused attacks, game play became very predictable. The solution is Routing. Routing provides alternate goals for the bots to go to before heading to their main goal. When positioned correctly, these alternate goals provide the effect of bots choosing realistic and varied paths to their main goals.

Routing requires some setup in script and in the waypoints, but the results are worth the effort. The objective of this article is to provide an overview of how the routing system works and to clearly define how to set it up by walking through a working example on Goldrush.

[[Image:Gr_routes2.jpg|Goldrush Multiple Routes Example]]

In this picture, Squares are route nodes and the Dots are potential paths. The color of the Dots correspond to the color of the Route nodes. Once they reach a route node, they will travel along the path(s) of the same color IF the route node is set up for their current main goal.

Walking through the picture, let’s say the tank construction goal is set up for an allied engineer within the AllySpawn route nodes, and that the engineer has the tank construct as its goal. The engineer will randomly choose whether to go to the green route node (as_right) or the yellow route node (depotgate). For the purpose of this example, let’s say the bot chose to go to the green route node. From there, he will randomly choose to go to the white or red route node. The bot will continue to make these decisions until there are no route nodes left to go to. From that point, the bot will take the shortest path to the tank construct goal.
As you can see, this opens up several different points of attack for the bots; which creates a sense of realism in terms of predictability. Defenses will now need to be set up to be able to react to all of the entry points rather than focusing on easily predicted choke points if the shortest path is always used.

==Setting It Up==

Setting up Routes involves waypointing and scripting. This section will take you step by step through the process of setting up the routes in the Goldrush example.

===Step 1: Setting up the script===

The first requirement for routing is that the routes are defined in the map script. The method to do this consists of building a table for the routes and calling a utility function that will register the routes.

If a map script does not exist yet, open up your favorite text editor and add the following to a new file:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
}; </syntaxhighlight>

Save the file as <mapname>.gm in your Omni-Bot\et\nav folder. You are now ready to start building the routes. Inside the InitializeRoutes function is where the route definitions are placed and they all start with a basic layout:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You now have a MapRoutes table defined and are registering everything within that table with the Util.Routes function.

===Step 2: Adding route goal ===

Route goals are fairly straight forward. They have two important properties; route name and radius. You can use any name you want for the route nodes, but they should be somewhat intuitive. To see the full guide on adding route goals see the [[Route_Goal]] page.

Route goals are placed in positions where a bot might receive the goal you want them to use alternate paths for. The bot MUST be inside the route node radius when receiving a goal for it to work. Spawn points are good spots for route nodes because bots always receive a goal when they spawn.

In the spawns area you need to place the goal over the spawn positions and give it a large radius to cover the spawn points. Issue the following commands in console:

/bot show_spawns
/bot goal_create route AllySpawn
/bot goal_setproperty radius 500

The radius of the route nodes at spawn positions are very critical because the bots must be inside its radius for it to work. Be sure that the radius covers the entire spawn area. Bots do not always receive goals immediately at spawn. Sometimes they receive goals 2 seconds after spawn. That's why it's always better to set bigger radius. But be careful, route nodes must not overlap.

For routing to be effective, you will need at least two defined because once they reach the route node, they will take the shortest path to their goal UNLESS there is another route node set up for them to go to. Continuing with our example, create a route node where the green square is in the picture and name it as_right:

/bot goal_create route as_right

You now have two route nodes; meeting the requirement for working routes. In our example, we want the bots to use two paths from the spawn, so add the route node depicted by the yellow square at the depot gate:

/bot goal_create route depotgate

Be sure to save the goals at this point. The next step is to set up the goals and route node selection in the script.

/bot goal_save

===Step 3: Scripting the routes===

The Maproutes table is set up with the following format:
<syntaxhighlight lang="java">
MapRoutes =
{
GOALNAME1 =
{
ROUTE_NAME = {},
},
GOALNAME2 =
{
ROUTE_NAME = {},
},
};
MapRoutes["GOALNAME3.*"] =
{
ROUTE_NAME = {},
};
MapRoutes["GOALNAME4.*"] =
{
ROUTE_NAME = {},
};
</syntaxhighlight>

If you are new to map scripting, this may appear a bit intimidating. The key is to follow the steps and syntax exactly, then let the understanding of the syntax come naturally. If you are comfortable with gm scripting, the routing set up consists of nested tables.

"GOALNAME3.*" is a regular expression which matches multiple goals. It is usually used for ATTACK and DEFEND goals. For example, regular expression "ATTACK_Depot.*" matches goals ATTACK_Depot1, ATTACK_Depot2, ATTACK_Depot3, etc. Regular expression "ATTACK_Depot[25]" matches goals ATTACK_Depot2 and ATTACK_Depot5. Routes for regular expressions have special syntax and they must be defined after the initial MapRoutes table.

The goal names and route names must match the output from command /bot show_goals. Be sure to double check the goal names. Route names are case sensitive.

For the Goldrush example, set up the tank construct routing as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn = {},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

The AllySpawn route node is now a valid route node for the tank construct goal. If a bot spawns within its radius and receives the tank construct as a goal, it will use that route node. In and of itself, this route node will not do anything because at spawn the bot is already at it. So let’s add the two path options we want to give the bots from the Allied Spawn:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

It’s important to understand what we just did with this:
<syntaxhighlight lang="java">
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},</syntaxhighlight>

The bot reaches the AllySpawn route node by default when it spawns; and because we have added the two routes inside the brackets, the bots will randomly choose between them. At this point, you have randomized routes for Allied engineers with the tank construct goal. Half the time they will choose to go to route as_right and half the time they will choose to go to route depotgate.

Let’s make them even less predictable. Looking at the example picture, you can see that we want them to have a couple different options once they reach the route nodes we just set up. Repeating step 2, add the rest of the route nodes depicted by the colored squares.

The scripting for the path options in the picture is as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn =
{
ROUTE_as_right =
{
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
ROUTE_depotflank = {},
},
},
ROUTE_depotgate =
{
ROUTE_cproute = {},
ROUTE_depotgatesplit = {},
ROUTE_as_rightsplit1 = {},
},
},
},
};

Util.Routes(Maproutes);
}; </syntaxhighlight>

===Step 4: Testing the routes===

Testing the routes is by far the most important step. It is recommended that you test routes individually as you start to learn the routing system. Once you are comfortable with the setup, you may want to add routes for an entire phase and then test them to make the process a bit faster.

If the routing is not working as expected, there are some basic troubleshooting options. It’s important to remember the criteria for the routes; the bot must be within the radius of the route node when receiving the goal, and the route node must be set up to support the goal. The basic troubleshooting steps are:

# Check in console when the map loads for any error messages. It should list any goal names not found when initializing the routes.
# Check the radius of the route where the bot receives the goal
# Make sure the bot can reach the goal
# Make sure the bot is getting the expected goal

For numbers 2 and 3, consider using the command /bot debugbot all goals with only one bot connected. In console, it should give success / failure messages for short term and long term goals. An example of a known problem is if there are priority type goals (like radar parts stealing) that are active when they aren’t reachable. The solution is to set them to be not active in OnMapLoad if they are unreachable.

===Step 5: Adding priorities to routes===

In some cases, you may want bots to use a certain route more often than others. This can be done by adding a “weight” to the route table:
<syntaxhighlight lang="java">
ROUTE_as_right =
{
Weight = 2,
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
Weight = 2,
ROUTE_depotflank = {},
},
},</syntaxhighlight>

In this example, the bots will randomly choose to go to route as_right twice as much as route depotgate. And then they will choose to go to route as_rightsplit2 twice as much as route as_rightsplit1.

===Step 6: Copying routes===

If you have more than one goal that you want to share the same routing with, you can copy the routing. In the Goldrush example, say we have some attack goals in the yard that we want to route to. Rather than writing out the tables for each attack goal, we can copy them like this:
<syntaxhighlight lang="java">
MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;
</syntaxhighlight>

The key point to remember when doing this is that the route table that exists must be on the right side of the equation. In this case, we have created routes for multiple attack goals and a mount goal that are the same as our example routing to build the tank.

These should be placed in InitializeRoutes as well, below the Maproutes table and above the Util function that registers the routes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_Tank =
{

},
};

MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;

Util.Routes(MapRoutes);
};</syntaxhighlight>

You can also store shared routes to a local variable and then use it for several goals:
<syntaxhighlight lang="java">
r = {
ROUTE_city1 = {},
ROUTE_city2 = {},
ROUTE_city3 = {},
};
MapRoutes =
{
FLAG_Gold_Bars =
{
ROUTE_spawn = r
},
CAPPOINT_gold =
{
ROUTE_gold = r
},
};
</syntaxhighlight>

If there are shared routes within one goal, then don't copy them. Just define them once:
<syntaxhighlight lang="java">
MapRoutes =
{
PLANT_Gun =
{
ROUTE_spawn =
{
ROUTE_door =
{
ROUTE_hatch =
{
ROUTE_eastdoor = {},
ROUTE_westdoor = {},
},
ROUTE_stairs =
{
ROUTE_westladder = {},
ROUTE_eastladder = {},
},
},
ROUTE_radar =
{
ROUTE_hatch = {},
ROUTE_stairs = {},
},
},
},
};
</syntaxhighlight>
If a bot chooses path ROUTE_spawn -> ROUTE_radar -> ROUTE_hatch, then he will continue to ROUTE_eastdoor or ROUTE_westdoor.

===Step 7: Toggling routes===

Routes are treated very similar to map goals. They will show up in your list if you do a /bot show_goals. They can be turned on and off via scripting with the SetAvailableMapGoals function. As an example, say we have route that we want opened up when barrier is destroyed, then closed when that barrier is constructed. This can be done inside the OnTriggers for those events:
<syntaxhighlight lang="java">
Barrier_construct = function ()
{
Util.DisableGoal( "ROUTE_routname" );
};

Barrier_destroyed = function ()
{
Util.EnableGoal( "ROUTE_routname" );
};
</syntaxhighlight>

===Step 8: Route maker===
* Windows users can use the route maker tool to easily create the MapRoutes table.
* Download it from http://svn.assembla.com/svn/omnibot/Enemy-Territory/0.8/tools/route_tool/
* Extract both RouteMaker.zip and RouteMaker2.zip into the same folder.
* Run RouteMaker2.exe
* You must set rcon password on your Enemy Territory or RTCW server.
* Then use menu command File / Load From RCON
* Drag & drop goals from left panel into middle panel.
* Drag & drop routes from right panel into middle panel.
* Double-click to delete routes.
* Finally use menu command Write / Script
* Output script will be copied to the clipboard. Paste it into the InitializeRoutes function in your map gm script.

===Step 9: Ask for help===

If you are having trouble with the syntax, set up, or understanding the routing system, ask for help. This guide is by no means comprehensive and complex maps will offer different challenges. Please post in the forums if you have questions / problems / bug reports.

Template:Baserouting

2025-06-23T07:28:57Z

Palota: /* Step 3: Scripting the routes */

[[Category:ET|Routing]]
[[Category:Doom 3|Routing]]
[[Category:Quake 4|Routing]]
[[Category:RTCW|Routing]]
[[Category:Waypointing]]
==Routing Overview==

Until version 0.65, omni-bot path selection relied on the shortest path to a goal. While this typically provided for very focused attacks, game play became very predictable. The solution is Routing. Routing provides alternate goals for the bots to go to before heading to their main goal. When positioned correctly, these alternate goals provide the effect of bots choosing realistic and varied paths to their main goals.

Routing requires some setup in script and in the waypoints, but the results are worth the effort. The objective of this article is to provide an overview of how the routing system works and to clearly define how to set it up by walking through a working example on Goldrush.

[[Image:Gr_routes2.jpg|Goldrush Multiple Routes Example]]

In this picture, Squares are route nodes and the Dots are potential paths. The color of the Dots correspond to the color of the Route nodes. Once they reach a route node, they will travel along the path(s) of the same color IF the route node is set up for their current main goal.

Walking through the picture, let’s say the tank construction goal is set up for an allied engineer within the AllySpawn route nodes, and that the engineer has the tank construct as its goal. The engineer will randomly choose whether to go to the green route node (as_right) or the yellow route node (depotgate). For the purpose of this example, let’s say the bot chose to go to the green route node. From there, he will randomly choose to go to the white or red route node. The bot will continue to make these decisions until there are no route nodes left to go to. From that point, the bot will take the shortest path to the tank construct goal.
As you can see, this opens up several different points of attack for the bots; which creates a sense of realism in terms of predictability. Defenses will now need to be set up to be able to react to all of the entry points rather than focusing on easily predicted choke points if the shortest path is always used.

==Setting It Up==

Setting up Routes involves waypointing and scripting. This section will take you step by step through the process of setting up the routes in the Goldrush example.

===Step 1: Setting up the script===

The first requirement for routing is that the routes are defined in the map script. The method to do this consists of building a table for the routes and calling a utility function that will register the routes.

If a map script does not exist yet, open up your favorite text editor and add the following to a new file:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
}; </syntaxhighlight>

Save the file as <mapname>.gm in your Omni-Bot\et\nav folder. You are now ready to start building the routes. Inside the InitializeRoutes function is where the route definitions are placed and they all start with a basic layout:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You now have a MapRoutes table defined and are registering everything within that table with the Util.Routes function.

===Step 2: Adding route goal ===

Route goals are fairly straight forward. They have two important properties; route name and radius. You can use any name you want for the route nodes, but they should be somewhat intuitive. To see the full guide on adding route goals see the [[Route_Goal]] page.

Route goals are placed in positions where a bot might receive the goal you want them to use alternate paths for. The bot MUST be inside the route node radius when receiving a goal for it to work. Spawn points are good spots for route nodes because bots always receive a goal when they spawn.

In the spawns area you need to place the goal over the spawn positions and give it a large radius to cover the spawn points. Issue the following commands in console:

/bot show_spawns
/bot goal_create route AllySpawn
/bot goal_setproperty radius 500

The radius of the route nodes at spawn positions are very critical because the bots must be inside its radius for it to work. Be sure that the radius covers the entire spawn area. Bots do not always receive goals immediately at spawn. Sometimes they receive goals 2 seconds after spawn. That's why it's always better to set bigger radius. But be careful, route nodes must not overlap.

For routing to be effective, you will need at least two defined because once they reach the route node, they will take the shortest path to their goal UNLESS there is another route node set up for them to go to. Continuing with our example, create a route node where the green square is in the picture and name it as_right:

/bot goal_create route as_right

You now have two route nodes; meeting the requirement for working routes. In our example, we want the bots to use two paths from the spawn, so add the route node depicted by the yellow square at the depot gate:

/bot goal_create route depotgate

Be sure to save the goals at this point. The next step is to set up the goals and route node selection in the script.

/bot goal_save

===Step 3: Scripting the routes===

The Maproutes table is set up with the following format:
<syntaxhighlight lang="java">
MapRoutes =
{
GOALNAME1 =
{
ROUTE_NAME = {},
},
GOALNAME2 =
{
ROUTE_NAME = {},
},
};
MapRoutes["GOALNAME3.*"] =
{
ROUTE_NAME = {},
};
MapRoutes["GOALNAME4.*"] =
{
ROUTE_NAME = {},
};
</syntaxhighlight>

If you are new to map scripting, this may appear a bit intimidating. The key is to follow the steps and syntax exactly, then let the understanding of the syntax come naturally. If you are comfortable with gm scripting, the routing set up consists of nested tables.

"GOALNAME3.*" is a regular expression which matches multiple goals. It is usually used for ATTACK and DEFEND goals. For example, regular expression "ATTACK_Depot.*" matches goals ATTACK_Depot1, ATTACK_Depot2, ATTACK_Depot3, etc. Regular expression "ATTACK_Depot[25]" matches goals ATTACK_Depot2 and ATTACK_Depot5. Routes for regular expressions have special syntax and they must be defined after the initial MapRoutes table.

The goal names and route names must match the output from command /bot show_goals. Be sure to double check the goal names. Route names are case sensitive.

For the Goldrush example, set up the tank construct routing as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn = {},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

The AllySpawn route node is now a valid route node for the tank construct goal. If a bot spawns within its radius and receives the tank construct as a goal, it will use that route node. In and of itself, this route node will not do anything because at spawn the bot is already at it. So let’s add the two path options we want to give the bots from the Allied Spawn:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

It’s important to understand what we just did with this:
<syntaxhighlight lang="java">
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},</syntaxhighlight>

The bot reaches the AllySpawn route node by default when it spawns; and because we have added the two routes inside the brackets, the bots will randomly choose between them. At this point, you have randomized routes for Allied engineers with the tank construct goal. Half the time they will choose to go to route as_right and half the time they will choose to go to route depotgate.

Let’s make them even less predictable. Looking at the example picture, you can see that we want them to have a couple different options once they reach the route nodes we just set up. Repeating step 2, add the rest of the route nodes depicted by the colored squares.

The scripting for the path options in the picture is as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn =
{
ROUTE_as_right =
{
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
ROUTE_depotflank = {},
},
},
ROUTE_depotgate =
{
ROUTE_cproute = {},
ROUTE_depotgatesplit = {},
ROUTE_as_rightsplit1 = {},
},
},
},
};

Util.Routes(Maproutes);
}; </syntaxhighlight>

===Step 4: Testing the routes===

Testing the routes is by far the most important step. It is recommended that you test routes individually as you start to learn the routing system. Once you are comfortable with the setup, you may want to add routes for an entire phase and then test them to make the process a bit faster.

If the routing is not working as expected, there are some basic troubleshooting options. It’s important to remember the criteria for the routes; the bot must be within the radius of the route node when receiving the goal, and the route node must be set up to support the goal. The basic troubleshooting steps are:

# Check in console when the map loads for any error messages. It should list any goal names not found when initializing the routes.
# Check the radius of the route where the bot receives the goal
# Make sure the bot can reach the goal
# Make sure the bot is getting the expected goal

For numbers 2 and 3, consider using the command /bot debugbot all goals with only one bot connected. In console, it should give success / failure messages for short term and long term goals. An example of a known problem is if there are priority type goals (like radar parts stealing) that are active when they aren’t reachable. The solution is to set them to be not active in OnMapLoad if they are unreachable.

===Step 5: Adding priorities to routes===

In some cases, you may want bots to use a certain route more often than others. This can be done by adding a “weight” to the route table:
<syntaxhighlight lang="java">
ROUTE_as_right =
{
Weight = 2,
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
Weight = 2,
ROUTE_depotflank = {},
},
},</syntaxhighlight>

In this example, the bots will randomly choose to go to route as_right twice as much as route depotgate. And then they will choose to go to route as_rightsplit2 twice as much as route as_rightsplit1.

===Step 6: Copying routes===

If you have more than one goal that you want to share the same routing with, you can copy the routing. In the Goldrush example, say we have some attack goals in the yard that we want to route to. Rather than writing out the tables for each attack goal, we can copy them like this:
<syntaxhighlight lang="java">
MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;
</syntaxhighlight>

The key point to remember when doing this is that the route table that exists must be on the right side of the equation. In this case, we have created routes for multiple attack goals and a mount goal that are the same as our example routing to build the tank.

These should be placed in OnMapLoad as well, below the Maproutes table and above the Utility function that registers the routes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_Tank =
{

},
};

MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;

Util.Routes(MapRoutes);
};</syntaxhighlight>

===Step 7: Toggling routes===

Routes are treated very similar to map goals. They will show up in your list if you do a /bot show_goals. They can be turned on and off via scripting with the SetAvailableMapGoals function. As an example, say we have route that we want opened up when barrier is destroyed, then closed when that barrier is constructed. This can be done inside the OnTriggers for those events:
<syntaxhighlight lang="java">
Barrier_construct = function ()
{
Util.DisableGoal( "ROUTE_routname" );
};

Barrier_destroyed = function ()
{
Util.EnableGoal( "ROUTE_routname" );
};
</syntaxhighlight>

===Step 8: Route maker===
* Windows users can use the route maker tool to easily create the MapRoutes table.
* Download it from http://svn.assembla.com/svn/omnibot/Enemy-Territory/0.8/tools/route_tool/
* Extract both RouteMaker.zip and RouteMaker2.zip into the same folder.
* Run RouteMaker2.exe
* You must set rcon password on your Enemy Territory or RTCW server.
* Then use menu command File / Load From RCON
* Drag & drop goals from left panel into middle panel.
* Drag & drop routes from right panel into middle panel.
* Double-click to delete routes.
* Finally use menu command Write / Script
* Output script will be copied to the clipboard. Paste it into the InitializeRoutes function in your map gm script.

===Step 9: Ask for help===

If you are having trouble with the syntax, set up, or understanding the routing system, ask for help. This guide is by no means comprehensive and complex maps will offer different challenges. Please post in the forums if you have questions / problems / bug reports.

Template:Baserouting

2025-06-23T06:55:00Z

Palota: /* Step 3: Scripting the routes */

[[Category:ET|Routing]]
[[Category:Doom 3|Routing]]
[[Category:Quake 4|Routing]]
[[Category:RTCW|Routing]]
[[Category:Waypointing]]
==Routing Overview==

Until version 0.65, omni-bot path selection relied on the shortest path to a goal. While this typically provided for very focused attacks, game play became very predictable. The solution is Routing. Routing provides alternate goals for the bots to go to before heading to their main goal. When positioned correctly, these alternate goals provide the effect of bots choosing realistic and varied paths to their main goals.

Routing requires some setup in script and in the waypoints, but the results are worth the effort. The objective of this article is to provide an overview of how the routing system works and to clearly define how to set it up by walking through a working example on Goldrush.

[[Image:Gr_routes2.jpg|Goldrush Multiple Routes Example]]

In this picture, Squares are route nodes and the Dots are potential paths. The color of the Dots correspond to the color of the Route nodes. Once they reach a route node, they will travel along the path(s) of the same color IF the route node is set up for their current main goal.

Walking through the picture, let’s say the tank construction goal is set up for an allied engineer within the AllySpawn route nodes, and that the engineer has the tank construct as its goal. The engineer will randomly choose whether to go to the green route node (as_right) or the yellow route node (depotgate). For the purpose of this example, let’s say the bot chose to go to the green route node. From there, he will randomly choose to go to the white or red route node. The bot will continue to make these decisions until there are no route nodes left to go to. From that point, the bot will take the shortest path to the tank construct goal.
As you can see, this opens up several different points of attack for the bots; which creates a sense of realism in terms of predictability. Defenses will now need to be set up to be able to react to all of the entry points rather than focusing on easily predicted choke points if the shortest path is always used.

==Setting It Up==

Setting up Routes involves waypointing and scripting. This section will take you step by step through the process of setting up the routes in the Goldrush example.

===Step 1: Setting up the script===

The first requirement for routing is that the routes are defined in the map script. The method to do this consists of building a table for the routes and calling a utility function that will register the routes.

If a map script does not exist yet, open up your favorite text editor and add the following to a new file:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
}; </syntaxhighlight>

Save the file as <mapname>.gm in your Omni-Bot\et\nav folder. You are now ready to start building the routes. Inside the InitializeRoutes function is where the route definitions are placed and they all start with a basic layout:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You now have a MapRoutes table defined and are registering everything within that table with the Util.Routes function.

===Step 2: Adding route goal ===

Route goals are fairly straight forward. They have two important properties; route name and radius. You can use any name you want for the route nodes, but they should be somewhat intuitive. To see the full guide on adding route goals see the [[Route_Goal]] page.

Route goals are placed in positions where a bot might receive the goal you want them to use alternate paths for. The bot MUST be inside the route node radius when receiving a goal for it to work. Spawn points are good spots for route nodes because bots always receive a goal when they spawn.

In the spawns area you need to place the goal over the spawn positions and give it a large radius to cover the spawn points. Issue the following commands in console:

/bot show_spawns
/bot goal_create route AllySpawn
/bot goal_setproperty radius 500

The radius of the route nodes at spawn positions are very critical because the bots must be inside its radius for it to work. Be sure that the radius covers the entire spawn area. Bots do not always receive goals immediately at spawn. Sometimes they receive goals 2 seconds after spawn. That's why it's always better to set bigger radius. But be careful, route nodes must not overlap.

For routing to be effective, you will need at least two defined because once they reach the route node, they will take the shortest path to their goal UNLESS there is another route node set up for them to go to. Continuing with our example, create a route node where the green square is in the picture and name it as_right:

/bot goal_create route as_right

You now have two route nodes; meeting the requirement for working routes. In our example, we want the bots to use two paths from the spawn, so add the route node depicted by the yellow square at the depot gate:

/bot goal_create route depotgate

Be sure to save the goals at this point. The next step is to set up the goals and route node selection in the script.

/bot goal_save

===Step 3: Scripting the routes===

The Maproutes table is set up with the following format:
<syntaxhighlight lang="java">
MapRoutes =
{
GOALNAME =
{
ROUTNAME = {},
},
GOALNAME2 =
{
ROUTENAME = {},
},
};</syntaxhighlight>

If you are new to map scripting, this may appear a bit intimidating. The key is to follow the steps and syntax exactly, then let the understanding of the syntax come naturally. If you are comfortable with gm scripting, the routing set up consists of nested tables.

The goal name must match the output from show_goals and the route name is the waypoint name prepended with ROUTE_. For the Goldrush example, set up the tank construct routing as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You have just added a map goal to the Maproutes table. The syntax of the goal name is VERY important. Be sure to double check the goal name with /bot show_goals. Once you are sure the goal name is correct, you can add the route nodes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn = {},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

The AllySpawn route node is now a valid route node for the tank construct goal. If a bot spawns within its radius and receives the tank construct as a goal, it will use that route node. In and of itself, this route node will not do anything because at spawn the bot is already at it. So let’s add the two path options we want to give the bots from the Allied Spawn:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

It’s important to understand what we just did with this:
<syntaxhighlight lang="java">
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},</syntaxhighlight>

The bot reaches the AllySpawn route node by default when it spawns; and because we have added the two routes inside the brackets, the bots will randomly choose between them. At this point, you have randomized routes for Allied engineers with the tank construct goal. Half the time they will choose to go to route as_right and half the time they will choose to go to route depotgate.

Let’s make them even less predictable. Looking at the example picture, you can see that we want them to have a couple different options once they reach the route nodes we just set up. Repeating step 2, add the rest of the route nodes depicted by the colored squares.

The scripting for the path options in the picture is as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank =
{
ROUTE_AllySpawn =
{
ROUTE_as_right =
{
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
ROUTE_depotflank = {},
},
},
ROUTE_depotgate =
{
ROUTE_cproute = {},
ROUTE_depotgatesplit = {},
ROUTE_as_rightsplit1 = {},
},
},
},
};

Util.Routes(Maproutes);
}; </syntaxhighlight>

===Step 4: Testing the routes===

Testing the routes is by far the most important step. It is recommended that you test routes individually as you start to learn the routing system. Once you are comfortable with the setup, you may want to add routes for an entire phase and then test them to make the process a bit faster.

If the routing is not working as expected, there are some basic troubleshooting options. It’s important to remember the criteria for the routes; the bot must be within the radius of the route node when receiving the goal, and the route node must be set up to support the goal. The basic troubleshooting steps are:

# Check in console when the map loads for any error messages. It should list any goal names not found when initializing the routes.
# Check the radius of the route where the bot receives the goal
# Make sure the bot can reach the goal
# Make sure the bot is getting the expected goal

For numbers 2 and 3, consider using the command /bot debugbot all goals with only one bot connected. In console, it should give success / failure messages for short term and long term goals. An example of a known problem is if there are priority type goals (like radar parts stealing) that are active when they aren’t reachable. The solution is to set them to be not active in OnMapLoad if they are unreachable.

===Step 5: Adding priorities to routes===

In some cases, you may want bots to use a certain route more often than others. This can be done by adding a “weight” to the route table:
<syntaxhighlight lang="java">
ROUTE_as_right =
{
Weight = 2,
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
Weight = 2,
ROUTE_depotflank = {},
},
},</syntaxhighlight>

In this example, the bots will randomly choose to go to route as_right twice as much as route depotgate. And then they will choose to go to route as_rightsplit2 twice as much as route as_rightsplit1.

===Step 6: Copying routes===

If you have more than one goal that you want to share the same routing with, you can copy the routing. In the Goldrush example, say we have some attack goals in the yard that we want to route to. Rather than writing out the tables for each attack goal, we can copy them like this:
<syntaxhighlight lang="java">
MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;
</syntaxhighlight>

The key point to remember when doing this is that the route table that exists must be on the right side of the equation. In this case, we have created routes for multiple attack goals and a mount goal that are the same as our example routing to build the tank.

These should be placed in OnMapLoad as well, below the Maproutes table and above the Utility function that registers the routes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_Tank =
{

},
};

MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;

Util.Routes(MapRoutes);
};</syntaxhighlight>

===Step 7: Toggling routes===

Routes are treated very similar to map goals. They will show up in your list if you do a /bot show_goals. They can be turned on and off via scripting with the SetAvailableMapGoals function. As an example, say we have route that we want opened up when barrier is destroyed, then closed when that barrier is constructed. This can be done inside the OnTriggers for those events:
<syntaxhighlight lang="java">
Barrier_construct = function ()
{
Util.DisableGoal( "ROUTE_routname" );
};

Barrier_destroyed = function ()
{
Util.EnableGoal( "ROUTE_routname" );
};
</syntaxhighlight>

===Step 8: Route maker===
* Windows users can use the route maker tool to easily create the MapRoutes table.
* Download it from http://svn.assembla.com/svn/omnibot/Enemy-Territory/0.8/tools/route_tool/
* Extract both RouteMaker.zip and RouteMaker2.zip into the same folder.
* Run RouteMaker2.exe
* You must set rcon password on your Enemy Territory or RTCW server.
* Then use menu command File / Load From RCON
* Drag & drop goals from left panel into middle panel.
* Drag & drop routes from right panel into middle panel.
* Double-click to delete routes.
* Finally use menu command Write / Script
* Output script will be copied to the clipboard. Paste it into the InitializeRoutes function in your map gm script.

===Step 9: Ask for help===

If you are having trouble with the syntax, set up, or understanding the routing system, ask for help. This guide is by no means comprehensive and complex maps will offer different challenges. Please post in the forums if you have questions / problems / bug reports.

Template:Baserouting

2025-06-23T06:28:13Z

Palota: /* Step 2: Adding route goal */

[[Category:ET|Routing]]
[[Category:Doom 3|Routing]]
[[Category:Quake 4|Routing]]
[[Category:RTCW|Routing]]
[[Category:Waypointing]]
==Routing Overview==

Until version 0.65, omni-bot path selection relied on the shortest path to a goal. While this typically provided for very focused attacks, game play became very predictable. The solution is Routing. Routing provides alternate goals for the bots to go to before heading to their main goal. When positioned correctly, these alternate goals provide the effect of bots choosing realistic and varied paths to their main goals.

Routing requires some setup in script and in the waypoints, but the results are worth the effort. The objective of this article is to provide an overview of how the routing system works and to clearly define how to set it up by walking through a working example on Goldrush.

[[Image:Gr_routes2.jpg|Goldrush Multiple Routes Example]]

In this picture, Squares are route nodes and the Dots are potential paths. The color of the Dots correspond to the color of the Route nodes. Once they reach a route node, they will travel along the path(s) of the same color IF the route node is set up for their current main goal.

Walking through the picture, let’s say the tank construction goal is set up for an allied engineer within the AllySpawn route nodes, and that the engineer has the tank construct as its goal. The engineer will randomly choose whether to go to the green route node (as_right) or the yellow route node (depotgate). For the purpose of this example, let’s say the bot chose to go to the green route node. From there, he will randomly choose to go to the white or red route node. The bot will continue to make these decisions until there are no route nodes left to go to. From that point, the bot will take the shortest path to the tank construct goal.
As you can see, this opens up several different points of attack for the bots; which creates a sense of realism in terms of predictability. Defenses will now need to be set up to be able to react to all of the entry points rather than focusing on easily predicted choke points if the shortest path is always used.

==Setting It Up==

Setting up Routes involves waypointing and scripting. This section will take you step by step through the process of setting up the routes in the Goldrush example.

===Step 1: Setting up the script===

The first requirement for routing is that the routes are defined in the map script. The method to do this consists of building a table for the routes and calling a utility function that will register the routes.

If a map script does not exist yet, open up your favorite text editor and add the following to a new file:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
}; </syntaxhighlight>

Save the file as <mapname>.gm in your Omni-Bot\et\nav folder. You are now ready to start building the routes. Inside the InitializeRoutes function is where the route definitions are placed and they all start with a basic layout:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You now have a MapRoutes table defined and are registering everything within that table with the Util.Routes function.

===Step 2: Adding route goal ===

Route goals are fairly straight forward. They have two important properties; route name and radius. You can use any name you want for the route nodes, but they should be somewhat intuitive. To see the full guide on adding route goals see the [[Route_Goal]] page.

Route goals are placed in positions where a bot might receive the goal you want them to use alternate paths for. The bot MUST be inside the route node radius when receiving a goal for it to work. Spawn points are good spots for route nodes because bots always receive a goal when they spawn.

In the spawns area you need to place the goal over the spawn positions and give it a large radius to cover the spawn points. Issue the following commands in console:

/bot show_spawns
/bot goal_create route AllySpawn
/bot goal_setproperty radius 500

The radius of the route nodes at spawn positions are very critical because the bots must be inside its radius for it to work. Be sure that the radius covers the entire spawn area. Bots do not always receive goals immediately at spawn. Sometimes they receive goals 2 seconds after spawn. That's why it's always better to set bigger radius. But be careful, route nodes must not overlap.

For routing to be effective, you will need at least two defined because once they reach the route node, they will take the shortest path to their goal UNLESS there is another route node set up for them to go to. Continuing with our example, create a route node where the green square is in the picture and name it as_right:

/bot goal_create route as_right

You now have two route nodes; meeting the requirement for working routes. In our example, we want the bots to use two paths from the spawn, so add the route node depicted by the yellow square at the depot gate:

/bot goal_create route depotgate

Be sure to save the goals at this point. The next step is to set up the goals and route node selection in the script.

/bot goal_save

===Step 3: Scripting the routes===

The Maproutes table is set up with the following format:
<syntaxhighlight lang="java">
MapRoutes =
{
GOALNAME =
{
ROUTNAME = {},
},
GOALNAME2 =
{
ROUTENAME = {},
},
};</syntaxhighlight>

If you are new to map scripting, this may appear a bit intimidating. The key is to follow the steps and syntax exactly, then let the understanding of the syntax come naturally. If you are comfortable with gm scripting, the routing set up consists of nested tables.

The goal name must match the output from show_goals and the route name is the waypoint name prepended with ROUTE_. For the Goldrush example, set up the tank construct routing as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You have just added a map goal to the Maproutes table. The syntax of the goal name is VERY important. Be sure to double check the goal name with /bot show_goals. Once you are sure the goal name is correct, you can add the route nodes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn = {},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

The AllySpawn route node is now a valid route node for the tank construct goal. If a bot spawns within its radius and receives the tank construct as a goal, it will use that route node. In and of itself, this route node will not do anything because at spawn the bot is already at it. So let’s add the two path options we want to give the bots from the Allied Spawn:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

It’s important to understand what we just did with this:
<syntaxhighlight lang="java">
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},</syntaxhighlight>

The bot reaches the AllySpawn route node by default when it spawns; and because we have added the two routes inside the brackets, the bots will randomly choose between them. At this point, you have randomized routes for Allied engineers with the tank construct goal. Half the time they will choose to go to route as_right and half the time they will choose to go to route depotgate.

Let’s make them even less predictable. Looking at the example picture, you can see that we want them to have a couple different options once they reach the route nodes we just set up. Repeating step 2, add the rest of the route nodes depicted by the colored squares.

The scripting for the path options in the picture is as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right =
{
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
ROUTE_depotflank = {},
},
},
ROUTE_depotgate =
{
ROUTE_cproute = {},
ROUTE_depotgatesplit = {},
ROUTE_as_rightsplit1 = {},
},
},
},
};

Util.Routes(Maproutes);
}; </syntaxhighlight>

===Step 4: Testing the routes===

Testing the routes is by far the most important step. It is recommended that you test routes individually as you start to learn the routing system. Once you are comfortable with the setup, you may want to add routes for an entire phase and then test them to make the process a bit faster.

If the routing is not working as expected, there are some basic troubleshooting options. It’s important to remember the criteria for the routes; the bot must be within the radius of the route node when receiving the goal, and the route node must be set up to support the goal. The basic troubleshooting steps are:

# Check in console when the map loads for any error messages. It should list any goal names not found when initializing the routes.
# Check the radius of the route where the bot receives the goal
# Make sure the bot can reach the goal
# Make sure the bot is getting the expected goal

For numbers 2 and 3, consider using the command /bot debugbot all goals with only one bot connected. In console, it should give success / failure messages for short term and long term goals. An example of a known problem is if there are priority type goals (like radar parts stealing) that are active when they aren’t reachable. The solution is to set them to be not active in OnMapLoad if they are unreachable.

===Step 5: Adding priorities to routes===

In some cases, you may want bots to use a certain route more often than others. This can be done by adding a “weight” to the route table:
<syntaxhighlight lang="java">
ROUTE_as_right =
{
Weight = 2,
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
Weight = 2,
ROUTE_depotflank = {},
},
},</syntaxhighlight>

In this example, the bots will randomly choose to go to route as_right twice as much as route depotgate. And then they will choose to go to route as_rightsplit2 twice as much as route as_rightsplit1.

===Step 6: Copying routes===

If you have more than one goal that you want to share the same routing with, you can copy the routing. In the Goldrush example, say we have some attack goals in the yard that we want to route to. Rather than writing out the tables for each attack goal, we can copy them like this:
<syntaxhighlight lang="java">
MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;
</syntaxhighlight>

The key point to remember when doing this is that the route table that exists must be on the right side of the equation. In this case, we have created routes for multiple attack goals and a mount goal that are the same as our example routing to build the tank.

These should be placed in OnMapLoad as well, below the Maproutes table and above the Utility function that registers the routes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_Tank =
{

},
};

MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;

Util.Routes(MapRoutes);
};</syntaxhighlight>

===Step 7: Toggling routes===

Routes are treated very similar to map goals. They will show up in your list if you do a /bot show_goals. They can be turned on and off via scripting with the SetAvailableMapGoals function. As an example, say we have route that we want opened up when barrier is destroyed, then closed when that barrier is constructed. This can be done inside the OnTriggers for those events:
<syntaxhighlight lang="java">
Barrier_construct = function ()
{
Util.DisableGoal( "ROUTE_routname" );
};

Barrier_destroyed = function ()
{
Util.EnableGoal( "ROUTE_routname" );
};
</syntaxhighlight>

===Step 8: Route maker===
* Windows users can use the route maker tool to easily create the MapRoutes table.
* Download it from http://svn.assembla.com/svn/omnibot/Enemy-Territory/0.8/tools/route_tool/
* Extract both RouteMaker.zip and RouteMaker2.zip into the same folder.
* Run RouteMaker2.exe
* You must set rcon password on your Enemy Territory or RTCW server.
* Then use menu command File / Load From RCON
* Drag & drop goals from left panel into middle panel.
* Drag & drop routes from right panel into middle panel.
* Double-click to delete routes.
* Finally use menu command Write / Script
* Output script will be copied to the clipboard. Paste it into the InitializeRoutes function in your map gm script.

===Step 9: Ask for help===

If you are having trouble with the syntax, set up, or understanding the routing system, ask for help. This guide is by no means comprehensive and complex maps will offer different challenges. Please post in the forums if you have questions / problems / bug reports.

Template:Baserouting

2025-06-23T06:11:27Z

Palota: /* Step 8: Route maker */

[[Category:ET|Routing]]
[[Category:Doom 3|Routing]]
[[Category:Quake 4|Routing]]
[[Category:RTCW|Routing]]
[[Category:Waypointing]]
==Routing Overview==

Until version 0.65, omni-bot path selection relied on the shortest path to a goal. While this typically provided for very focused attacks, game play became very predictable. The solution is Routing. Routing provides alternate goals for the bots to go to before heading to their main goal. When positioned correctly, these alternate goals provide the effect of bots choosing realistic and varied paths to their main goals.

Routing requires some setup in script and in the waypoints, but the results are worth the effort. The objective of this article is to provide an overview of how the routing system works and to clearly define how to set it up by walking through a working example on Goldrush.

[[Image:Gr_routes2.jpg|Goldrush Multiple Routes Example]]

In this picture, Squares are route nodes and the Dots are potential paths. The color of the Dots correspond to the color of the Route nodes. Once they reach a route node, they will travel along the path(s) of the same color IF the route node is set up for their current main goal.

Walking through the picture, let’s say the tank construction goal is set up for an allied engineer within the AllySpawn route nodes, and that the engineer has the tank construct as its goal. The engineer will randomly choose whether to go to the green route node (as_right) or the yellow route node (depotgate). For the purpose of this example, let’s say the bot chose to go to the green route node. From there, he will randomly choose to go to the white or red route node. The bot will continue to make these decisions until there are no route nodes left to go to. From that point, the bot will take the shortest path to the tank construct goal.
As you can see, this opens up several different points of attack for the bots; which creates a sense of realism in terms of predictability. Defenses will now need to be set up to be able to react to all of the entry points rather than focusing on easily predicted choke points if the shortest path is always used.

==Setting It Up==

Setting up Routes involves waypointing and scripting. This section will take you step by step through the process of setting up the routes in the Goldrush example.

===Step 1: Setting up the script===

The first requirement for routing is that the routes are defined in the map script. The method to do this consists of building a table for the routes and calling a utility function that will register the routes.

If a map script does not exist yet, open up your favorite text editor and add the following to a new file:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
}; </syntaxhighlight>

Save the file as <mapname>.gm in your Omni-Bot\et\nav folder. You are now ready to start building the routes. Inside the InitializeRoutes function is where the route definitions are placed and they all start with a basic layout:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You now have a MapRoutes table defined and are registering everything within that table with the Util.Routes function.

===Step 2: Adding route goal ===

Route goals are fairly straight forward. They have two important properties; route name and radius. You can use any name you want for the route nodes, but they should be somewhat intuitive. To see the full guide on adding route goals see the [[Route_Goal]] page.

Route goals are placed in positions where a bot might receive the goal you want them to use alternate paths for. The bot MUST be inside the route node radius when receiving a goal for it to work. Spawn points are good spots for route nodes because bots always receive a goal when they spawn.

In the spawns area you need to place the goal over the spawn positions and give it a large radius to cover the spawn points. Issue the following commands in console:

/bot show_spawns
/bot goal_create route AllySpawn
/bot goal_setproperty radius 500
/bot goal_finish

The radius of the route nodes at spawn positions are very critical because the bots must be inside its radius for it to work. Be sure that the radius covers the entire spawn area. Bots do not always receive goals immediately at spawn. Sometimes they receive goals 2 seconds after spawn. That's why it's always better to set bigger radius. But be careful, route nodes must not overlap.

For routing to be effective, you will need at least two defined because once they reach the route node, they will take the shortest path to their goal UNLESS there is another route node set up for them to go to. Continuing with our example, create a route node where the green square is in the picture and name it as_right:

/bot goal_create route as_right
/bot goal_finish

You now have two route nodes; meeting the requirement for working routes. In our example, we want the bots to use two paths from the spawn, so add the route node depicted by the yellow square at the depot gate:

/bot goal_create route depotgate
/bot goal_finish

Be sure to save the goals at this point. The next step is to set up the goals and route node selection in the script.

/bot goal_save

===Step 3: Scripting the routes===

The Maproutes table is set up with the following format:
<syntaxhighlight lang="java">
MapRoutes =
{
GOALNAME =
{
ROUTNAME = {},
},
GOALNAME2 =
{
ROUTENAME = {},
},
};</syntaxhighlight>

If you are new to map scripting, this may appear a bit intimidating. The key is to follow the steps and syntax exactly, then let the understanding of the syntax come naturally. If you are comfortable with gm scripting, the routing set up consists of nested tables.

The goal name must match the output from show_goals and the route name is the waypoint name prepended with ROUTE_. For the Goldrush example, set up the tank construct routing as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You have just added a map goal to the Maproutes table. The syntax of the goal name is VERY important. Be sure to double check the goal name with /bot show_goals. Once you are sure the goal name is correct, you can add the route nodes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn = {},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

The AllySpawn route node is now a valid route node for the tank construct goal. If a bot spawns within its radius and receives the tank construct as a goal, it will use that route node. In and of itself, this route node will not do anything because at spawn the bot is already at it. So let’s add the two path options we want to give the bots from the Allied Spawn:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

It’s important to understand what we just did with this:
<syntaxhighlight lang="java">
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},</syntaxhighlight>

The bot reaches the AllySpawn route node by default when it spawns; and because we have added the two routes inside the brackets, the bots will randomly choose between them. At this point, you have randomized routes for Allied engineers with the tank construct goal. Half the time they will choose to go to route as_right and half the time they will choose to go to route depotgate.

Let’s make them even less predictable. Looking at the example picture, you can see that we want them to have a couple different options once they reach the route nodes we just set up. Repeating step 2, add the rest of the route nodes depicted by the colored squares.

The scripting for the path options in the picture is as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right =
{
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
ROUTE_depotflank = {},
},
},
ROUTE_depotgate =
{
ROUTE_cproute = {},
ROUTE_depotgatesplit = {},
ROUTE_as_rightsplit1 = {},
},
},
},
};

Util.Routes(Maproutes);
}; </syntaxhighlight>

===Step 4: Testing the routes===

Testing the routes is by far the most important step. It is recommended that you test routes individually as you start to learn the routing system. Once you are comfortable with the setup, you may want to add routes for an entire phase and then test them to make the process a bit faster.

If the routing is not working as expected, there are some basic troubleshooting options. It’s important to remember the criteria for the routes; the bot must be within the radius of the route node when receiving the goal, and the route node must be set up to support the goal. The basic troubleshooting steps are:

# Check in console when the map loads for any error messages. It should list any goal names not found when initializing the routes.
# Check the radius of the route where the bot receives the goal
# Make sure the bot can reach the goal
# Make sure the bot is getting the expected goal

For numbers 2 and 3, consider using the command /bot debugbot all goals with only one bot connected. In console, it should give success / failure messages for short term and long term goals. An example of a known problem is if there are priority type goals (like radar parts stealing) that are active when they aren’t reachable. The solution is to set them to be not active in OnMapLoad if they are unreachable.

===Step 5: Adding priorities to routes===

In some cases, you may want bots to use a certain route more often than others. This can be done by adding a “weight” to the route table:
<syntaxhighlight lang="java">
ROUTE_as_right =
{
Weight = 2,
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
Weight = 2,
ROUTE_depotflank = {},
},
},</syntaxhighlight>

In this example, the bots will randomly choose to go to route as_right twice as much as route depotgate. And then they will choose to go to route as_rightsplit2 twice as much as route as_rightsplit1.

===Step 6: Copying routes===

If you have more than one goal that you want to share the same routing with, you can copy the routing. In the Goldrush example, say we have some attack goals in the yard that we want to route to. Rather than writing out the tables for each attack goal, we can copy them like this:
<syntaxhighlight lang="java">
MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;
</syntaxhighlight>

The key point to remember when doing this is that the route table that exists must be on the right side of the equation. In this case, we have created routes for multiple attack goals and a mount goal that are the same as our example routing to build the tank.

These should be placed in OnMapLoad as well, below the Maproutes table and above the Utility function that registers the routes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_Tank =
{

},
};

MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;

Util.Routes(MapRoutes);
};</syntaxhighlight>

===Step 7: Toggling routes===

Routes are treated very similar to map goals. They will show up in your list if you do a /bot show_goals. They can be turned on and off via scripting with the SetAvailableMapGoals function. As an example, say we have route that we want opened up when barrier is destroyed, then closed when that barrier is constructed. This can be done inside the OnTriggers for those events:
<syntaxhighlight lang="java">
Barrier_construct = function ()
{
Util.DisableGoal( "ROUTE_routname" );
};

Barrier_destroyed = function ()
{
Util.EnableGoal( "ROUTE_routname" );
};
</syntaxhighlight>

===Step 8: Route maker===
* Windows users can use the route maker tool to easily create the MapRoutes table.
* Download it from http://svn.assembla.com/svn/omnibot/Enemy-Territory/0.8/tools/route_tool/
* Extract both RouteMaker.zip and RouteMaker2.zip into the same folder.
* Run RouteMaker2.exe
* You must set rcon password on your Enemy Territory or RTCW server.
* Then use menu command File / Load From RCON
* Drag & drop goals from left panel into middle panel.
* Drag & drop routes from right panel into middle panel.
* Double-click to delete routes.
* Finally use menu command Write / Script
* Output script will be copied to the clipboard. Paste it into the InitializeRoutes function in your map gm script.

===Step 9: Ask for help===

If you are having trouble with the syntax, set up, or understanding the routing system, ask for help. This guide is by no means comprehensive and complex maps will offer different challenges. Please post in the forums if you have questions / problems / bug reports.

CAT

2025-06-22T17:36:46Z

Palota:

{{process header
| title = Category Constant
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
[[Category:Constants]]
== Common Categories ==
<syntaxhighlight lang="java">
CAT.AUTODEFENSE
CAT.AVOID - landmine, dynamite, satchel, smokemarker, grenade
CAT.MISC - corpse
CAT.MOUNTED_WPN - mg42
CAT.MOVER
CAT.OBSTACLE - breakable, landmine, vehicle, MOVER
CAT.PICKUP
CAT.PICKUP_AMMO
CAT.PICKUP_HEALTH
CAT.PICKUP_WEAPON
CAT.PLAYER
CAT.PROJECTILE - smokebomb, dynamite, satchel, smokemarker, grenade
CAT.SHOOTABLE
CAT.TRIGGER - button
CAT.STATIC - MOVER, vehicle, button
CAT.VEHICLE - tank, truck, tug</syntaxhighlight>

== Enemy Territory Categories ==
CAT.MINE

== Fortress Forever Categories ==
<syntaxhighlight lang="java">
CAT.BUILDABLE
</syntaxhighlight>

See also: [[Bot_Library#GetEntCategory|GetEntCategory]], [[Bot_Library#OnTriggerRegion|OnTriggerRegion]]

CAT

2025-06-22T17:02:42Z

Palota: /* Common Categories */

{{process header
| title = Category Constant
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
[[Category:Constants]]
== Common Categories ==
<syntaxhighlight lang="java">
CAT.AUTODEFENSE
CAT.AVOID
CAT.MISC
CAT.MOUNTED_WPN
CAT.MOVER
CAT.OBSTACLE
CAT.PICKUP
CAT.PICKUP_AMMO
CAT.PICKUP_HEALTH
CAT.PICKUP_WEAPON
CAT.PLAYER
CAT.PROJECTILE
CAT.SHOOTABLE
CAT.TRIGGER
CAT.STATIC
CAT.VEHICLE</syntaxhighlight>

== Fortress Forever Categories ==
<syntaxhighlight lang="java">
CAT.BUILDABLE
</syntaxhighlight>

See also: [[Bot_Library#GetEntCategory|GetEntCategory]], [[Bot_Library#OnTriggerRegion|OnTriggerRegion]]

Bot Library

2025-06-08T12:50:18Z

Palota: /* SetAvailableMapGoals */

{{process header
| title = Bot Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
== Global Bot Functions ==

=== AddBot ===
Adds a bot to the game, and optionally specifies team, class, and name for the bot.

'''Parameters:''' ()

'''Parameters:''' (team)

'''Parameters:''' (team, class)

'''Parameters:''' (team, class, name)

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
AddBot();
// OR
AddBot(TEAM.AXIS);
// OR
AddBot(TEAM.AXIS, CLASS.SOLDIER);
// OR
AddBot(TEAM.AXIS, CLASS.SOLDIER, "SomeDude");
// OR
// not all fields are valid for all games, here's a quake 4 example
// not all fields are required. any left out will use sensible default values
tbl =
{
name="SomeDude",
team=TEAM.STROGG,
class=CLASS.PLAYER,
spawnpoint="somespawnpointname",
model="model_player_kane_strogg",
skin="base",
};
AddBot(tbl);</syntaxhighlight>

'''See Also:'''
[[Bot Library#KickBot| KickBot]], [[Bot Library#KickAll| KickAll]]
----

=== AllocGoalSerialNum ===
Gets unique goal serial number.

'''Parameters:''' none

'''Returns:''' integer

----

=== CalcTrajectory ===
Calculates a projectile trajectory, and returns the results in a table, or null if no trajectory exists for the parameters given.

'''Parameters:''' (Vector3 start position, Vector3 target position, projectile speed, projectile gravity)

'''Returns:''' table or null

'''Example:''' <syntaxhighlight lang="java">
mypos = Vector3(10,10,10); // get a valid position from somewhere
targpos = Vector3(20,20,20); // get a valid position from somewhere
projVel = 1000;
projGrav = 0.5;
traj = CalcTrajectory(mypos, targpos, projVel, projGrav);
if(traj)
{
// if a table was returned, there can be 1 or 2 trajectories stored in it.
// the 1st trajectory is the most direct trajectory
// the 2nd trajectory is normally a mortar trajectory with a high degree of arc.
// both trajectories are a unit length facing vector
b.TurnToFacing(traj[0]);
// OR
b.TurnToFacing(traj[1]);
}</syntaxhighlight>

----

=== CheatsEnabled ===
Checks if cheat mode is enabled in the game. Useful for debug or development scripts that use functions that are only available in cheat mode.

'''Parameters:''' none

'''Returns:''' true if cheats are enabled, false if not

'''Example:''' <syntaxhighlight lang="java">
if(CheatsEnabled())
{
// do something
}</syntaxhighlight>

'''See Also:'''
[[Bot Library#EntityKill| EntityKill]], [[Bot Library#ServerCommand| ServerCommand]]
----

=== CheckEntityBoundsIntersect ===
Checks if entities intersect.

'''Parameters:''' (entity1, entity2)

'''Returns:''' true/false

----

=== ClearGoalRole ===
Clears one or more roles of one or more MapGoals.

'''Parameters:''' (expression or table, role or table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
example: ClearGoalRole( "FLAG_Gold", ROLE.ATTACKER ); //1 goal, 1 role
example: ClearGoalRole( "DEFEND_City[4567]", { ROLE.DEFENDER2, ROLE.DEFENDER3}); //4 goals, 2 roles
</syntaxhighlight>

'''See Also:''' [[Roles]]
----

=== ConfigGet ===
Gets a config value from omni-bot.cfg. Sets a config value if it does not exist yet and if the third parameter is not null.

Type of the return value is string, int or float according to the third parameter. If you call ConfigGet with only 2 parameters, it will return string.

'''Parameters:''' (section, config parameter name, config parameter value[optional])

'''Returns:''' config parameter value

'''Example:'''
<syntaxhighlight lang="java">
ft = ConfigGet("FireTeam", "enabled", 1);
</syntaxhighlight>

'''See Also:'''
[[Bot Library#ConfigSet|ConfigSet]]
----

=== ConfigSet ===
Sets a config value in omni-bot.cfg.

'''Parameters:''' (section, config parameter name, config parameter value)

'''Returns:''' none

'''Example:'''
<syntaxhighlight lang="java">ConfigSet("FireTeam", "enabled", 0);</syntaxhighlight>

'''See Also:'''
[[Bot Library#ConfigGet|ConfigGet]]
----

=== CreateMapGoal ===
Creates a new goal.

'''Parameters:''' (type)

'''Returns:''' MapGoal object

----

=== Debug Functions ===
----

==== DrawAABB ====
'''See:'''
[[Bot Library#DrawDebugAABB | DrawDebugAABB]]
----

==== DrawArrow ====
Draws an arrow. Used for facing or AimVectors.

'''Parameters:''' (Vector3 start, Vector3 end, color, duration)

'''Returns:''' none

----

==== DrawDebugAABB ====
Draws a box.

'''Parameters:''' (AABB, color, duration)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
AABB box; // initialize it with something
// draw it in red for 5 seconds
DrawDebugAABB(box, COLOR.RED, 5);</syntaxhighlight>

'''See Also:'''
[[Bot Library#DrawDebugLine | DrawDebugLine]], [[Bot Library#GetEntWorldAABB | GetEntWorldAABB]]
----

==== DrawDebugLine ====
Draws a line in the environment. Useful for debugging.

'''Parameters:''' (Vector3 start, Vector3 end, color, duration)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
start = Vector3(0,0,0);
end = Vector3(20,20,20);
// draw it in red for 5 seconds
DrawDebugLine(start, end, COLOR.RED, 5);</syntaxhighlight>

'''See Also:'''
[[Bot Library#DrawDebugAABB | DrawDebugAABB]], [[Bot Library#GetEntWorldAABB | GetEntWorldAABB]]

----

==== DrawEntityAABB ====
Draws a bounding box around an entity. The box is usually much bigger than the entity.

'''Parameters:''' (entity, duration, color)

'''Returns:''' true/false

----

==== DrawEntityOBB ====
Draws an oriented box around an entity.

'''Parameters:''' (entity, duration, color)

'''Returns:''' true/false

----

==== DrawLine ====
'''See:'''
[[Bot Library#DrawDebugLine | DrawDebugLine]]
----

==== DrawRadius ====
Draws radius.

'''Parameters:''' (position, radius, color, duration)

'''Returns:''' none

----

==== DrawText3d ====
Draws text.

'''Parameters:''' (position, string, color, duration, maxDistanceFromPlayer[optional, default 1024])

'''Returns:''' none

----

==== DrawTrajectory ====
Draws trajectory of grenade, mortar, airstrike or smokebomb.

'''Parameters:''' ( {Position, Velocity, Interval, Duration, BounceLoss, GravityMultiplier, StopAtHit, TraceBounce }, color, duration)

'''Returns:''' target position

----

==== DumpConsoleToFile ====
Saves debug console, only if debug window is enabled.

'''Parameters:''' (file name)

'''Returns:''' none

----

==== EchoToScreen ====
Prints a message to the screen.

'''Parameters:''' (duration, message)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
EchoToScreen(5,"Hello World!");</syntaxhighlight>

----

==== EnableDebugWindow ====
Enables or disables [[Debug_Window|debug window]]. Does not work in release build of omnibot dynamic link library. You must use omnibot_et.dll from dw_enabled subfolder on [[Assembla]].

'''Parameters:''' (true/false, width[optional, default 1024], height[optional, default 768], bitsPerPixel[optional, default 32])

'''Returns:''' none

----

==== Error ====
Prints an error to the games output console.

'''Parameters:''' (error message)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
Error("Somethin bad happened");</syntaxhighlight>

----

==== Log ====
Writes a string to the omnibot log file.

The second parameter: 0=info, 1=warning, 2=error, 3=critical

'''Note:''' logs are disabled if cvar omnibot_logsize is zero or negative

'''Note:''' logs can also be disabled in omni-bot.cfg

'''Parameters:''' (string, level[optinal, default 0])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
Log("Something cool happened");
Log("Something bad happened", 2);</syntaxhighlight>

----

==== ShowPaths ====
Debug Information function. Prints Omni-bot version, revision, and revision date, along with file system paths.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
ShowPaths();</syntaxhighlight>

----

==== TransformAndDrawLineList ====

'''Parameters:''' (veclist, color, duration, position, euler)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
TransformAndDrawLineList({Vec3(20,80,0), Vec3(20,-60,0), Vec3(-90,70,30), Vec3(-90,-50,30)},
COLOR.RED, 5, GetLocalPosition(), Vec3(DegToRad(45),0,0));</syntaxhighlight>

----

=== DeleteTriggerRegion ===
Deletes a trigger region previously created with [[Bot Library#OnTriggerRegion| OnTriggerRegion]]. Because regions aren't required to have unique names, DeleteTriggerRegion will delete all regions that match the provided name. This allows grouping of different trigger regions by shared names.

'''Parameters:''' (name)

'''Parameters:''' (serial #)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// creates a sphere trigger 256 units in radius around 0,0,0, then delete it immediately.
triggerInfo =
{
Name="TestTrigger",
TriggerOnClass=CLASS.ANYPLAYER,
OnEnter = function(ent)
{
print(GetEntName(ent),"entered aabb trigger");
},
OnExit = function(ent)
{
print(GetEntName(ent),"exited aabb trigger");
},
};
serial = OnTriggerRegion(Vector3(0,0,0),256,triggerInfo);

DeleteTriggerRegion(serial);
// OR
DeleteTriggerRegion("TestTrigger");

</syntaxhighlight>

'''See Also:'''
[[Bot Library#OnTriggerRegion| OnTriggerRegion]]
----

=== DistanceBetween ===
Utility function for checking distances between 2 objects. This function takes 2 parameters, but the parameter types can vary.

'''Parameters:''' (object1, object2)

For this function, each parameter can be one of the following types.
* Vector3
* GameEntity
* GameId
* MapGoal

This provides a flexible and fast function that allows a script to check the distance between a variety of source and destination object, and reduces the need for the script to convert between GameEntity or GameId, or to get the position of the GameEntity itself.

'''Returns:''' distance between the objects

'''Example:''' <syntaxhighlight lang="java">
// assume entity1 is a GameEntity from another source, such as GetAllType
if(DistanceBetween(b.GetGameEntity(), entity1))
{
}
// OR
if(DistanceBetween(b.GetGameEntity(), Vector3(10,20,30))
{
}</syntaxhighlight>

----

=== DynamicPathsUpdated ===
Finds new path for bots in teams specified if paths go through waypoint which has dynamic flag.

'''Parameters:''' (teamId, ...)

'''Returns:''' none

----

=== Entity Functions ===

==== EntityIsOutside ====
Checks if a given entity is outside. Added in 0.83

'''Parameters:''' (entity)

'''Returns:''' true/false

----

==== EntityIsValid ====
Checks if a given entity exists. Parameter can be entity handle or entity ID.
Since 0.92 it does not throw exception but returns false if parameter is null.

'''Parameters:''' (entity)

'''Returns:''' true/false

----

==== EntityKill ====
Kills an entity. Requires cheats to be enabled.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
EntityKill(GetEntityByName("truck"));</syntaxhighlight>

'''See Also:'''
[[Bot Library#CheatsEnabled | CheatsEnabled ]]

----

==== GetEntBonePosition ====
Gets the world position of a specific bone on an entity.

'''Note:''' This function may not be implemented for all games. It's not implemented in ET.

'''Parameters:''' (GameEntity/GameId, BoneId)

'''Returns:''' Vector3 world bone position, or null if bone not found

'''Example:''' <syntaxhighlight lang="java">
headpos = GetEntBonePosition(someent, BONE.HEAD);
if(headpos)
{
// got head position
}</syntaxhighlight>

----

==== GetEntCategory ====
Checks if the entity belongs to one or more entity categories. This function takes one or more categories, and returns true if the entity belongs to all the provided categories.

'''Parameters:''' (GameEntity/GameId, Category, ...)

'''Returns:''' true if the entity belongs to all provided categories.

'''Example:''' <syntaxhighlight lang="java">
if(GetEntCategory(someent, CAT.PROJECTILE))
{
}
if(GetEntCategory(someent, CAT.PLAYER, CAT.VEHICLE))
{
} </syntaxhighlight>

'''See also:''' [[CAT]]
----

==== GetEntClass ====
Gets the class of the entity.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' class of entity, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
if(GetEntClass(someent) == CLASS.SOLDIER)
{
}</syntaxhighlight>

'''See also:''' [[CLASS]]
----

==== GetEntEquippedWeapon ====
Gets current weapon of a player.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' weaponId

'''Example:''' <syntaxhighlight lang="java">
weapon = GetEntEquippedWeapon(this.TargetEntity);
</syntaxhighlight>

----

==== GetEntEyePosition ====
Gets the world eye position of an entity.

Note: position is not correct if bot is looking up or down

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 eye position, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
eyepos = GetEntEyePosition(someent);
if(eyepos)
{
// got eye position
}</syntaxhighlight>

----

==== GetEntFacing ====
Gets the world facing vector of an entity

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 facing, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
face = GetEntFacing(someent);
if(face)
{
// got face vector, as a direction vector
}</syntaxhighlight>

----

==== GetEntFlags ====
Checks if the entity has one or more entity flags.

'''Parameters:''' (GameEntity/GameId, Entity Flag, ...)

'''Returns:''' true if the entity has any of provided entity flags.

'''Example:''' <syntaxhighlight lang="java">
if(GetEntFlags(someent, ENTFLAG.CROUCHED))
{
}
if(GetEntFlags(someent, ENTFLAG.CROUCHED, ENTFLAG.RELOADING))
{
} </syntaxhighlight>

'''See also:''' [[ENTFLAG]]
----

==== GetEntHealthAndArmor ====
Gets health and armor of an entity.

'''Parameters:''' (GameEntity/GameId, table)

'''Returns:''' true if successful, false if not

Properties stored into table:
* Health - Current Health
* MaxHealth - Max Health
* Armor - Current Armor
* MaxArmor - Max Armor

'''Example:''' <syntaxhighlight lang="java">
healthArmor = {};
if(GetEntHealthAndArmor(someentity, healthArmor))
{
if(healthArmor.Health < 20)
{
b.Say("I'm Hurt!");
}
} </syntaxhighlight>

'''See also:''' [[Utility_Functions#Util.GetEntHealth|Util.GetEntHealth]]
----

==== GetEntName ====
'''See:'''
[[Bot Library#GetEntityName | GetEntityName]]
----

==== GetEntOwner ====
Gets the owner of an entity. Typically used for entities that can be held or carried.

Note: If player who is carrying objective is kicked, GetEntOwner will return invalid entity till end of match. This bug is in all ET mods (except the last version of omnibot mod).

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' GameId of owner, or null if none or error

'''Example:''' <syntaxhighlight lang="java">
owner = GetEntOwner(someent);</syntaxhighlight>

----

==== GetEntPosition ====
Gets the world position of an entity.

Note: old mods return wrong position (NoQuarter 1.2.5, ETpub 0.9.0, Jaymod 2.1.7, ...).

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 world position, or null if error

'''Example:''' <syntaxhighlight lang="java">
p = GetEntPosition(someent);</syntaxhighlight>
----

==== GetEntPowerups ====
Checks if the entity has one or more powerups. This function takes one or more powerups, and returns true if the entity has all of them.

'''Parameters:''' (GameEntity/GameId, PowerUp, ...)

'''Returns:''' true if the entity has all powerups.

'''Example:''' <syntaxhighlight lang="java">
if(GetEntPowerups(someent, POWERUP.INVINCIBLE))
{
}
if(GetEntPowerups(someent, POWERUP.QUADDAMAGE, POWERUP.BERSERK))
{
} </syntaxhighlight>

----

==== GetEntRotationMatrix ====
Gets the Matrix3 full transform of an entity.

'''Parameters:''' (GameEntity/GameId, Matrix3<optional>)

If you pass an Matrix3 as the 2nd parameter, that object will be filled in instead of a new Matrix3 returned. This can save memory allocations in a script that calls the function often by re-using the same object.

'''Returns:''' true if Matrix3 passed as 2nd parameter and filled in successfully, if no Matrix3 provided, returns Matrix3 for entity. Both return null on an error.

'''Example:''' <syntaxhighlight lang="java">
entMat = GetEntRotationMatrix(someent);
if(entMat)
{
// do something
}
// re-use the same Matrix3 later
if(GetEntRotationMatrix(someent, entMat))
{
} </syntaxhighlight>

----

==== GetEntTeam ====
Gets the team id that the entity belongs to.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Team Id of entity, or null if error

'''Example:''' <syntaxhighlight lang="java">
if(GetEntTeam(someent) == TEAM.RED)
{
}</syntaxhighlight>

'''See also:''' [[TEAM]]
----

==== GetEntVelocity ====
Gets the world velocity of an entity.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 world velocity, or null if error

'''Example:''' <syntaxhighlight lang="java">
vel = GetEntVelocity(someent);</syntaxhighlight>
----

==== GetEntWorldAABB ====
Gets the bounding box for an entity. The box is usually much bigger than the entity. Center of the box is not equal to entity position.

'''Parameters:''' (GameEntity/GameId, AABB<optional>)

If you pass an AABB as the 2nd parameter, that object will be filled in instead of a new AABB returned. This can save memory allocations in a script that calls the function often by re-using the same object.

'''Returns:''' true if AABB passed as 2nd parameter and filled in successfully, if no AABB provided, returns AABB for entity. Both return null on an error.

'''Example:''' <syntaxhighlight lang="java">
entAABB = GetEntWorldAABB(someent);
if(entAABB)
{
// do something
}
// re-use the same AABB later
if(GetEntWorldAABB(someent, entAABB))
{
} </syntaxhighlight>

----

==== GetEntityByName ====
Finds entity by target name. In ET you can use command '''/entitylist''' to see entity names.

Unfortunately this functions can't find entities which have only script name, but don't have target name.

'''Parameters:''' (name)

'''Returns:''' GameEntity found, or null if none found

----

==== GetEntityInSphere ====
Finds an entity within a radius around a point that matches a particular class Id. It is set up so that it can be used in a loop to find all entities.

'''Parameters:''' (Vector3 position, radius, classid, start entity)

'''Returns:''' GameEntity found, or null if none found

'''Example:''' <syntaxhighlight lang="java">
p = Vector3(10,10,10);
radius = 20;
ent = GetEntityInSphere(p, radius, CLASS.ANYPLAYER, null);
while(ent)
{
// do something with it?
// get the next one found
ent = GetEntityInSphere(p, radius, CLASS.ANYPLAYER, ent);
}</syntaxhighlight>
----

==== GetEntityLocalSpace ====
Converts a world position into a local space position of a specified entity.

'''Parameters:''' (GameEntity/GameId, Vector3 world position)

'''Returns:''' Vector3 local space position, or null if error

'''Example:''' <syntaxhighlight lang="java">
worldpos = Vector3(10,10,10);
localpos = GetEntityLocalSpace(someent, worldpos); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetEntityWorldSpace | GetEntityWorldSpace]]
----

==== GetEntityName ====
Gets the name of an entity. In ET you can use command '''/entitylist''' to see all entity names.

If entity has defined both script name and target name, GetEntityName returns script name.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' name of entity, or null if error

'''Example:''' <syntaxhighlight lang="java">
entName = GetEntityName(someent);
if(entName == "SomeName")
{
// do something
}
</syntaxhighlight>

----

==== GetEntityStat ====
Generic function for getting information about an entity, by name.

'''Parameters:''' (GameEntity/GameId, stat name)

'''Returns:''' stat, or null if error or stat doesn't exist. The type depends on the stat.

'''Example:''' <syntaxhighlight lang="java">
kills = GetEntityStat(someent, "kills");
deaths = GetEntityStat(someent, "deaths");
xp = GetEntityStat(bot.GetGameEntity(), "xp");
</syntaxhighlight>
----

==== GetEntityWorldSpace ====
Converts a local space position into a world space position of a specified entity.

'''Parameters:''' (GameEntity/GameId, Vector3 local position)

'''Returns:''' Vector3 world space position, or null if error

'''Example:''' <syntaxhighlight lang="java">
localpos = Vector3(10,10,10);
worldpos = GetEntityWorldSpace(someent, localpos); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetEntityLocalSpace | GetEntityLocalSpace]]
----

==== GetGameEntityFromId ====
Converts a GameId to a GameEntity.

'''Parameters:''' (GameId)

'''Returns:''' GameEntity

'''Example:''' <syntaxhighlight lang="java">
ent = GetGameEntityFromId(2); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetGameIdFromEntity | GetGameIdFromEntity ]]
----

==== GetGameIdFromEntity ====
Converts a GameEntity to a GameId.

'''Parameters:''' (GameEntity)

'''Returns:''' GameId

'''Example:''' <syntaxhighlight lang="java">
id = GetGameIdFromEntity(someent); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetGameEntityFromId | GetGameEntityFromId ]]
----

=== ExecCommand ===
This function executes a bot command as if it came from the games input console.

'''Parameters:''' (command string)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
ExecCommand("addbot 1 2")</syntaxhighlight>

----

=== ExecCommandOnClient ===
Executes a command for the entity. Usually equivilent to console commands.

'''Parameters:''' (GameEntity/GameId, command string)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
ExecCommandOnClient(bot.GetGameEntity(), "setviewpos 1200 2300 150 0");</syntaxhighlight>
----

=== ExecScript ===
Attempts to execute a script file. File is searched in scripts folder, global_scripts folder or game folder (omni-bot/et).

'''Parameters:''' (filename)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
ExecScript("myscript.gm");</syntaxhighlight>

----

=== GetClassNameFromId ===
Gets the current class name from a class id.

'''Parameters:''' (classId)

'''Returns:''' string

----

=== GetGameName ===
Gets the name of the currently running game.

'''Parameters:''' none

'''Returns:''' name of game

'''Example:''' <syntaxhighlight lang="java">
if(GetGameName() == "Enemy Territory")
{
}
else if(GetGameName() == "Quake 4")
{
}
</syntaxhighlight>

----

=== GetGameState ===
Gets the current state of the game (Playing, Warm-up, Warm-up Countdown, Intermission, Waiting for Players, Paused, Invalid).

'''Parameters:''' none

'''Returns:''' name of game state

'''Example:''' <syntaxhighlight lang="java">
if(GetGameState() == "Playing")
{
}</syntaxhighlight>

----

=== GetGameTimeLeft ===
Gets the current amount of time remaining in the game round.

'''Parameters:''' none

'''Returns:''' time left, in seconds

'''Example:''' <syntaxhighlight lang="java">
if(GetGameTimeLeft() < 30)
{
}</syntaxhighlight>

----

=== GetGoal ===
Gets a reference to a map goal by name. The goal name is case sensitive.

'''Parameters:''' (name of map goal to get)

'''Returns:''' MapGoal if found, null if not

'''Example:''' <syntaxhighlight lang="java">
mg = GetGoal("MAP_FLAG_redflag");</syntaxhighlight>

'''See Also:'''
[[MapGoal]]
----

=== GetGoals ===
Gets any number of map goals that match a regular expression. Stores the matching reference in the first table parameter. The previous table content is cleared since omni-bot 0.84. It's not possible to call GetGoals multiple times to accumulate results. The last optional parameter is table of parameters to filter result (Group, Role, SkipNoInProgress, SkipNoInUse, SkipInUse) or sort result (parameter Sort, values are "none", "priority", "name", "priority_name", "random").

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
goals = {};
GetGoals(goals, TEAM.AXIS, "FLAG.*", { Sort="priority" });</syntaxhighlight>

'''See Also:'''
[[Utility_Functions#Util.GoalTable|Util.GoalTable]], [[Bot Library#GetGoal| GetGoal]]
----

=== GetGravity ===
Gets the current gravity of the game.

'''Parameters:''' none

'''Returns:''' gravity

'''Example:''' <syntaxhighlight lang="java">
grav = GetGravity();</syntaxhighlight>

----

=== GetLocalAABB ===
Gets bounding box of local player.

'''Parameters:''' none

'''Returns:''' AABB

----

=== GetLocalAimNormal ===
Gets normal at aim position of local player.

'''Parameters:''' (collision mask[optional, default floodfill])

'''Returns:''' Vector3

----

=== GetLocalAimPosition ===
Gets aim position of local player.

'''Parameters:''' (collision mask[optional, default floodfill])

'''Returns:''' Vector3

----

=== GetLocalEntity ===
Gets local player.

'''Parameters:''' none

'''Returns:''' GameEntity

----

=== GetLocalEyePosition ===
Gets eye position of local player.

'''Parameters:''' none

'''Returns:''' Vector3

----

=== GetLocalCommand ===
Gets name of just running console command. It is useful if you use same script for multiple commands.

'''Parameters:''' none

'''Returns:''' string or null

----
=== GetLocalFacing ===
Gets facing vector of local player.

'''Parameters:''' none

'''Returns:''' Vector3

----

=== GetLocalGroundPosition ===
Gets ground position of local player.

'''Parameters:''' none

'''Returns:''' Vector3 or null

----

=== GetLocalPosition ===
Gets position of local player.

'''Parameters:''' none

'''Returns:''' Vector3

----

=== GetMapExtents ===
Gets the AABB map extents. Map extends are the bounds of the entire map.

'''Parameters:''' (AABB<optional>)

'''Returns:''' If no AABB passed as parameter, function will return the map AABB, otherwise the AABB parameter will be filled in with the results, and the function will return nothing.

'''Example:''' <syntaxhighlight lang="java">
aabb = GetMapExtents();
// or
AABB aabb;
GetMapExtents(aabb);</syntaxhighlight>

----

=== GetMapName ===
Get the name of the current map.

'''Parameters:''' none

'''Returns:''' name of map

'''Example:''' <syntaxhighlight lang="java">
if(GetMapName() == "oasis")
{
}</syntaxhighlight>

----

=== GetModName ===
Gets the name of the currently running mod.

'''Parameters:''' none

'''Returns:''' name of mod

'''Example:''' <syntaxhighlight lang="java">
if(GetModName() == "etpub")
{
}</syntaxhighlight>

----

=== GetModVersion ===
Gets the version of the current mod.

'''Parameters:''' none

'''Returns:''' version of mod

'''Example:''' <syntaxhighlight lang="java">
if(GetModVersion() == "DOOM 1.3")
{
}</syntaxhighlight>

----

=== GetNearestNonSolid ===
This function is similar to TraceLine, but ignores solids.

'''Parameters:''' (start, end, trace mask[optional])

'''Returns:''' position

----

=== GetPointContents ===
Gets the contents bits for a given position.

'''Parameters:''' (Vector3 position)

'''Returns:''' contents bits. Use bitwise manipulators along with constants from the global [[CONTENT]] table to check for specific content bits.

'''Example:''' <syntaxhighlight lang="java">
contents = GetPointContents(Vector3(10,10,10));
if(contents & CONTENT.WATER)
{
}</syntaxhighlight>

----

=== GetTeamStat ===
Generic function for getting information about a team, by name. It's not implemented in ET.

'''Parameters:''' (Team Id, stat name)

'''Returns:''' stat, or null if error or stat doesn't exist. The type depends on the stat.

'''Example:''' <syntaxhighlight lang="java">
score = GetTeamStat(TEAM.RED, "score");</syntaxhighlight>
----

=== GetTime ===
Gets the current time elapsed in the game.

'''Parameters:''' none

'''Returns:''' time, in seconds

'''Example:''' <syntaxhighlight lang="java">
if(GetTime() > 30)
{
}</syntaxhighlight>

----

=== GetWeapon ===
Gets weapon object by ID.

'''Parameters:''' (weaponId)

'''Returns:''' [[Weapon]]

----

=== GetWeaponIdFromClassId ===
Converts classId to weaponId.

'''Parameters:''' (classId)

'''Returns:''' weaponId

----

=== GroundPoint ===
Returns a point on the ground directly below the provided point.

'''Parameters:''' (position)

'''Returns:''' ground position

----

=== KickAll ===
Kicks all bots from the game.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
KickAll();</syntaxhighlight>

----

=== KickBot ===
Kicks a bot by name.

'''Parameters:''' (name)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
KickBot("Fred");</syntaxhighlight>

----

=== KickBotFromTeam ===
Kicks last bot from team.

'''Parameters:''' (teamId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
KickBot(TEAM.AXIS);</syntaxhighlight>

----

=== MoveBotToAnotherTeam ===
Moves a bot from a team to another team.

'''Parameters:''' (source teamId, destination teamId)

'''Returns:''' none

----

=== OnTrigger ===
Registers a script function callback for a given trigger string.

'''Parameters:''' (trigger string, script function)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
global Map =
{
myfunc = function(trigger)
{
direction = ToVector(trigger.Action);
entityName = GetEntName(trigger.Entity);
}
};
global OnMapLoad = function()
{
OnTrigger( "cargo_lift_goto", Map.myfunc);
};
</syntaxhighlight>

'''See Also:'''
[[Triggers]]
----

=== OnTriggerRegion===
Creates one of several types of trigger regions. A trigger region is an area that watches for entities of certain types to touch them and calls script callback functions for enter and exit. Useful if you want an easy way to be notified when certain entities go to certain areas of the map.

This function takes a table as the last parameter to define a number of flexible options for the trigger region. Here is a list of available key/value options for the table.
* Name - Optional name to give the region. Does not need to be unique.
* OnEnter - script function to call when an entity touches the region.
* OnExit - script function to call when an entity stops touching the region.
* TriggerOnClass - Define the class id you want the region to trigger on. This field may also be an indexed table with up to 8 class ids.
* TriggerOnCategory - Category of entities to watch for. This field may also be an indexed table with as many categories as you want to limit the trigger to.
* TriggerOnEntity - A specific entity to trigger on. This field may also be an indexed table with up to 8 entities you want to limit the trigger to.

The following region types are supported. The type is dependent on which parameters of the function are used.
* AABB - Axis aligned bounding box.
* Sphere - A radius around a position.

Triggers may be rendered for reference with ''/bot drawtriggers 1''

'''Parameters:''' (AABB, table)

'''Parameters:''' (position, radius, table)

'''Returns:''' unique serial number of region

'''Example:''' <syntaxhighlight lang="java">
// creates a sphere trigger 256 units in radius around 0,0,0
triggerInfo =
{
Name="TestTrigger",
TriggerOnClass=CLASS.ANYPLAYER,
OnEnter = function(ent)
{
print(GetEntName(ent),"entered aabb trigger");
},
OnExit = function(ent)
{
print(GetEntName(ent),"exited aabb trigger");
},
};
serial = OnTriggerRegion(Vector3(0,0,0),256,triggerInfo);
</syntaxhighlight>

'''See Also:'''
[[Bot Library#DeleteTriggerRegion| DeleteTriggerRegion]]
----

=== RegisterDefaultProfile ===
Registers a default profile that will be loaded for any bot that joins a specified class.

'''Parameters:''' (Class Id, script name)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
RegisterDefaultProfile(CLASS.SOLDIER, "def_bot.gm");</syntaxhighlight>

----

=== ReloadGoalScripts ===
Executes all goal scripts. You must also kick all bots because any changes will be applied to newly added bots.

'''Parameters:''' none

'''Returns:''' none

----

=== RunScript ===
'''See:'''
[[Bot Library#ExecScript| ExecScript]]
----

=== SendTrigger ===
It is used by goal scripts to call function in map script.
Parameter TagName is string which must be same as the first parameter of function [[Bot Library#OnTrigger|OnTrigger]].

'''Parameters:''' ( { TagName, Entity, Activator, Action } )

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
SendTrigger({
Entity = ent,
Activator = null,
TagName = GetEntName(ent) + " at location",
Action = "arrived"
});
</syntaxhighlight>
----

=== ServerCommand ===
Executes a server command. Requires cheats to be enabled.

'''Parameters:''' none

'''Returns:''' true if cheats are enabled, false if not

'''Example:''' <syntaxhighlight lang="java">
ServerCommand("map oasis");</syntaxhighlight>

'''See Also:'''
[[Bot Library#CheatsEnabled | CheatsEnabled ]]
----

=== ServerScriptFunction ===
Not implemented in ET.

'''Parameters:''' (entity name, function name, parameters[optinal])

'''Returns:''' none

----

=== SetAvailableMapGoals ===
Enables/Disables the available status of one or more map goals that match a regular expression, for a specific team.

'''Parameters:''' (Team Id, enable/disable, mapgoal expression string or table, ignoreErrors[optional])

'''Returns:''' number of goals that match regular expression

'''Example:''' <syntaxhighlight lang="java">
SetAvailableMapGoals( TEAM.ALLIES, false, "ATTACK.*" );
SetAvailableMapGoals( TEAM.AXIS, true, { "DEFEND_gate.*", "MOUNTMG42_bunker", "SNIPE_tower.*" } );
SetAvailableMapGoals( TEAM.AXIS, false, "DEFUSE_Gate.*", true );</syntaxhighlight>

'''See Also:'''
[[Availability]], [[Bot Library#GetGoal| GetGoal]], [[Bot Library#GetGoals| GetGoals]]
----

=== SetGoalGroup ===
Sets the goal or table of goals group name.

'''Parameters:''' (goalname or table, groupname)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
SetGoalGroup( "SomeGoalName", "SomeGroupName" );
SetGoalGroup( { "ROUTE_route1", "ROUTE_route2", "someothergoal" }, "MyGroup" );
</syntaxhighlight>

'''See Also:'''
[[Utility Functions#Util.DisableGroup| Util.DisableGroup]],
[[Utility Functions#Util.EnableGroup| Util.EnableGroup]],
[[Utility Functions#Util.GetGroup| Util.GetGroup]],
[[Utility Functions#Util.SetGroup| Util.SetGroup]],
[[Utility Functions#Util.ShowGroup| Util.ShowGroup]]

----

=== SetGoalPriority===
Sets priority of one or more MapGoals for specified team and class. The last parameter must be true for dynamically created goals (FLAG_dropped, FLAGRETURN, DEFUSE ...).

'''Parameters:''' (expression or table, priority, teamId[optional, default 0], classId[optional, default 0], persistent[optional])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
example: SetGoalPriority( "FLAG_Gold", 0.7 ); //all teams and all classes
example: SetGoalPriority( "CHECKPOINT_City", 0.8, TEAM.AXIS); //axis only all classes
example: SetGoalPriority( "DEFUSE_somedyno.*", 0.0, TEAM.AXIS, CLASS.ENGINEER, true ); //the persistent parameter is used for dynamic goals that may not have been created yet </syntaxhighlight>

'''See Also:''' [[Priority]]
----

=== SetGoalRole ===
Sets one or more roles of one or more MapGoals. The last parameter must be true for dynamically created goals (FLAG_dropped, FLAGRETURN, DEFUSE ...).

'''Parameters:''' (expression or table, role or table, persistent[optional])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
example: SetGoalRole( "FLAG_Gold", ROLE.ATTACKER ); //1 goal, 1 role
example: SetGoalRole( "DEFEND_City[4567]", { ROLE.DEFENDER2, ROLE.DEFENDER3}); //4 goals, 2 roles
example: SetGoalRole( "DEFUSE_somedyno.*", ROLE.DEFENDER2, true ); //the persistent parameter is used for dynamic goals that may not have been created yet </syntaxhighlight>

'''See Also:''' [[Roles]]
----

=== SetMapGoalProperties===
Passes a table full of properties along to all matching map goals to attempt to set their properties.

'''Parameters:''' (expression or table, table of properties)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Set the camp time for all attack and defend goals
SetMapGoalProperties( "ATTACK_.*", {mincamptime=15, maxcamptime=30});
SetMapGoalProperties( "DEFEND_.*", {mincamptime=15, maxcamptime=30});</syntaxhighlight>

'''See Also:'''
[[Goal specific instructions]] for a list of properties for each map goal type.
----

=== TraceLine ===
Performs a traceline collision test, and returns the results in a table. TraceLine calls are useful for testing visibility, line of sight, or for getting a collision point along a line.

'''Parameters:''' (Vector3 start, Vector3 end, AABB, collision mask, ignore user GameId, use PVS)

* Vector3 start - Start position of trace line.
* Vector3 end - End position of trace line.
* AABB - Pass an AABB if you with the line to have volume, otherwise pass null.
* Collision Mask - Mask of collision types to test. See global [[TRACE]] table.
* GameId - Ignore this GameId in the traceline. Usually the entity or bot it originates from.
* UsePVS - true to use PVS (Potentially visible set), false to ignore PVS

Always pass false to not UsePVS if you need collision information from the call to TraceLine. UsePVS=true is useful when all you need to know is whether or not something is blocking the path from start to end, it will not give you the collision position. It is slightly faster in most cases to use PVS as an early out test, but doing so limits the amount of useful information you get back from the function. In many cases you don't need this information, so the extra speed is useful.

'''Returns:''' table of results

Results table contains the following information.
* fraction - 0.0 to 1.0 The ratio along the line the collision took place. Not always valid if UsePVS=true. Example: 0.5 means ray hit half way between the start and end.
* startsolid - true/false The traceline started inside a solid object. Not always valid if UsePVS=true

Additional properties are available if UsePVS=false and there was a collision.
* entity - May be null, the GameEntity that was hit in the collision.
* normal - The Vector3 normal of the collision point.
* end - The Vector3 world position of the collision.
* contents - water etc., see global [[CONTENT]] table.
* surface - ice, ladder, see global [[SURFACE]] table.

'''Example:''' <syntaxhighlight lang="java">
// Do a traceline along a bots facing 1024 units out
start = b.GetEyePosition();
end = start + b.GetFacing() * 1024;
tr = TraceLine(start, end, null, TRACE.SHOT, b.GetGameId(), false);

// the fraction value tells us of a collision or not. If it's 1, there was no collision. If less than 1 there was a collision.
if(tr.fraction < 1)
{
// tr.startsolid
// tr.entity
// tr.normal
// tr.end
// tr.contents
// tr.surface
}
</syntaxhighlight>

----

== Enemy Territory Addendum ==

=== GetCabinetData ===
Gets information about health or ammo cabinet. Properties CurrentAmount, MaxAmount, Rate are stored into table.

'''Parameters:''' (entity, table)

'''Returns:''' true if successful, null if not

'''Example:''' <syntaxhighlight lang="java">
cab = {};
if (GetCabinetData( GetGoal("AMMOCAB_north").GetEntity(), cab)){
print( cab.CurrentAmount );
}
</syntaxhighlight>

----

=== GetCvar ===
Gets a game cvar. Returns zero if the cvar does not exists or if its value cannot be converted to integer.

'''Parameters:''' (name)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
friendlyFire = GetCvar("g_friendlyfire");</syntaxhighlight>
----

=== GetGameType ===
Gets the current game type:

2 - single-map objective, 3 - stopwatch, 4 - campaign, 5 - last man standing

'''Parameters:''' none

'''Returns:''' integer
----

=== IsWaitingForMedic ===
Deprecated.
----

=== SetCvar ===
Sets a game cvar.

'''Parameters:''' (name, value)

'''Returns:''' true if successful, false if not
----

Utility Functions

2025-06-08T07:39:49Z

Palota: /* Util.SetGoalRange */

{{process header
| title = Utility Functions
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

{{TOCright}}

=== Util ===

==== Util.AddUsePoint ====

<syntaxhighlight lang="java">
syntax: Util.AddUsePoint(goalname, <Vector3 or table>);
example: Util.AddUsePoint("PLANT_wall",{Vec3(12,34,5),Vec3(23,5,67)});</syntaxhighlight>

used to add use points for a goal at given positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AddUseWp ====

<syntaxhighlight lang="java">
syntax: Util.AddUseWp(goalname, <waypointname or table>);
example: Util.AddUseWp( "somegoalname", "somewaypointname" );</syntaxhighlight>

used to add use points for a goal at given waypoints positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AliveCount ====

<syntaxhighlight lang="java">
syntax: Util.AliveCount( team, class );
example: Util.AliveCount( TEAM.AXIS, CLASS.MEDIC ); </syntaxhighlight>

returns the number of bots alive on a team with a given class

==== Util.BotChat ====

<syntaxhighlight lang="java">
syntax: Util.BotChat(Team, msgType, Msg, NumBots);
example: Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_CHEER, 2);
</syntaxhighlight>

See [[Talking_bots]] page

==== Util.BotHasAnyRole ====

This function is deprecated. Use [[Bot#HasRole|HasRole]]

==== Util.CanBotSnipe ====

<syntaxhighlight lang="java">
syntax: Util.CanBotSnipe(bot);
example: if ( Util.CanBotSnipe(bot) ) {
</syntaxhighlight>

returns true if bot has a sniper weapon.

==== Util.CappointForFlag ====
<syntaxhighlight lang="java">
syntax: Util.CappointForFlag( flag_goalname, cappoint_goalname );
example: Util.CappointForFlag( "FLAG_axis_gold", "CAPPOINT_Truck" );
</syntaxhighlight>

used if there are multiple active cappoint goals. It should be called from _Taken triggers.

==== Util.ChangeBotSpawn ====
This function is deprecated. See [[Changing spawns]].

==== Util.ChangeCrucialClassForRole ====
<syntaxhighlight lang="java">
syntax: Util.ChangeCrucialClassForRole ( team, role, class );
example: Util.ChangeCrucialClassForRole(TEAM.AXIS, ROLE.DEFENDER1, CLASS.COVERTOPS);
</syntaxhighlight>

Sets new crucialClass in the Map.Roles table.

==== Util.ChangeSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.ChangeSpawnForRole ====

<syntaxhighlight lang="java">
syntax: Util.ChangeSpawnForRole( <team>, <role>, <spawnpoint> );
example: Util.ChangeSpawnForRole(TEAM.ALLIES, ROLE.ATTACKER, 1);
</syntaxhighlight>

Set the spawn point for all bots on the given team with the given role

see also: [[Roles]] Page

==== Util.ChangeToSniperWeapons ====

<syntaxhighlight lang="java">
syntax: Util.ChangeToSniperWeapons( bot, <optional viewDistance> );
example: Util.ChangeToSniperWeapons(bot);
</syntaxhighlight>

called from OnBotJoin on sniper maps.

see also: [[Sniper_and_Panzer_maps]]

==== Util.ClearRoleForGoals ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.ClearRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.ClearRoleForGroup( group, <role or table> );
example: Util.ClearRoleForGroup( "someGroup", ROLE.DEFENDER );
</syntaxhighlight>

used to remove roles from a given group of goals

see also: [[Roles]] Page

==== Util.ClearRoleForTable ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.DisableGoal ====

<syntaxhighlight lang="java">
syntax: Util.DisableGoal(goalname, <optional true>);
example: Util.DisableGoal("FLAG_someflag"); </syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== Util.DisableGroup ====

<syntaxhighlight lang="java">
syntax: Util.DisableGroup(groupname, team);
example: Util.DisableGroup( "somegroupname", TEAM.ALLIES );</syntaxhighlight>

used to disable a set of goals in the given group for a given team

==== Util.EnableGoal ====

<syntaxhighlight lang="java">
syntax: Util.EnableGoal(goalname);
example: Util.EnableGoal("FLAG_someflag");</syntaxhighlight>

enables the goal for both teams.

==== Util.EnableGroup ====

<syntaxhighlight lang="java">
syntax: Util.EnableGroup(groupname, team);
example: Util.EnableGroup( "somegroupname", TEAM.SOMETEAM );</syntaxhighlight>

used to enable a set of goals in the given group for a given team

==== Util.ExcludeClass ====

<syntaxhighlight lang="java">
syntax: Util.ExcludeClass( goalname, team, class1, class2, class3, class4 );
example: Util.ExcludeClass( "DEFEND_somegoal.*", TEAM.AXIS, CLASS.MEDIC );
example: Util.ExcludeClass( "MOUNTMG42_.*", TEAM.ALLIES, CLASS.FIELDOPS, CLASS.ENGINEER );
</syntaxhighlight>

limit given goal usage to specific classes by team. class2, class3, and class4 are optional.

==== Util.ForceRouting ====

<syntaxhighlight lang="java">
syntax: Util.ForceRouting(goalName, true/false);
example: Util.ForceRouting( "BUILD_Tank", true );</syntaxhighlight>

disables BUILD goal offsets and enables routes to the goal. You should set ForceRouting to true only when a vehicle is at known position (in OnMapLoad or at tank barriers). You must set it to false when a vehicle is repaired.

==== Util.GetEntHealth ====

<syntaxhighlight lang="java">
syntax: Util.GetEntHealth(entity);
example: health = Util.GetEntHealth(this.TargetEntity);</syntaxhighlight>

returns entity health.

==== Util.GetGroup ====

<syntaxhighlight lang="java">
syntax: Util.GetGroup(groupname);
example: Util.GetGroup("somegroupname");</syntaxhighlight>

this function will return a table of goals belonging to the given group name

==== Util.GetRandomFromTable ====

<syntaxhighlight lang="java">
syntax: Util.GetRandomFromTable( tbl );
example: index = Util.GetRandomFromTable( someTable );
</syntaxhighlight>

used to get a randomly selected index from a given table. Returns -1 if invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GetRandomTableValue====

<syntaxhighlight lang="java">
syntax: Util.GetRandomTableValue( tbl );
example: value = Util.GetRandomTableValue( someTable );
</syntaxhighlight>

used to get a randomly selected value from a given table. Returns null if the table is empty or invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GoalTable ====

<syntaxhighlight lang="java">
syntax: Util.GoalTable( <optional expression>, <optional teamId> );
example: goals = Util.GoalTable("PLANT_Back_Door");
example: goals = Util.GoalTable("FLAG.*", TEAM.AXIS);
</syntaxhighlight>

returns table of map goals that match a regular expression.

==== Util.IgnoreTargetGoal ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IgnoreTargetGoalTable ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IsBot ====

<syntaxhighlight lang="java">
syntax: Util.IsBot(entity);
example: bot = Util.IsBot(ent);
</syntaxhighlight>

returns Bot object from entity or null if entity is not a bot. Usually used in region triggers if the TriggerOnClass is CLASS.ANYPLAYER.

==== Util.LimitToClass ====

<syntaxhighlight lang="java">
syntax: Util.LimitToClass(goalname, team, class1, class2, class3, class4);
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER); //only soldiers on the allied team
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER, CLASS.MEDIC); //only soldiers and medics</syntaxhighlight>

used to limit specific goals to a specific class or classes

==== Util.LimitToTeam ====

<syntaxhighlight lang="java">
syntax: Util.LimitToTeam(team, goal);
example: Util.LimitToTeam(TEAM.AXIS, "SWITCH_gate_depot");
</syntaxhighlight>

limits goals to a certain team without the need to disable for 1 team

==== Util.MapDebugPrint ====

<syntaxhighlight lang="java">
syntax: Util.MapDebugPrint( "Text", <optional message only> );
example: Util.MapDebugPrint( "East_Barrier_Destroyed" );
example: Util.MapDebugPrint( "East_Barrier_Destroyed", true ); // only print the message
</syntaxhighlight>

used to print text & list of available goals in the console when in debug mode

see also: [[Debugging_tips]]

==== Util.OnTriggerPosition ====

<syntaxhighlight lang="java">
syntax: Util.OnTriggerPosition( goalname, wpname or position, tolerance, wpfunction );
example: Util.OnTriggerPosition( "MOVER_train1", "depotyard", 200.0, Map.tug_depotyard );</syntaxhighlight>

note: used for setting up positional triggers for movers.

==== Util.RandomBotSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RandomSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RemoveGoal ====

<syntaxhighlight lang="java">
syntax: Util.RemoveGoal( goalnames );
example: Util.RemoveGoal( "MOVER_truck" );</syntaxhighlight>

removes the goals from the map goal table. It should only be used for invalid goals which are badly detected by the game.

==== Util.Routes ====

<syntaxhighlight lang="java">
syntax: Util.Routes( <table> );
example: Util.Routes(MapRoutes);</syntaxhighlight>

initializes routes

see also: [[Template:Baserouting|Routing]]

==== Util.SetGoalOffset ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalOffset( x, y, z, GoalName );
info x = North, -x = South y = East, -y = West, z = Up, -z =Down
example: Util.SetGoalOffset( 0, -20, -10, "MOUNTMG42_boat" );</syntaxhighlight>

the x y and z parameters are added to the origin of the goal to move the location of where bots will look for the goal. It is sometimes needed for MOUNTMG42 and REPAIRMG42 goals because some mg42 cannot be mounted or repaired if it's position is not corrected.

==== Util.SetGoalPosition ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalPosition( x, y, z, GoalName );
example: Util.SetGoalPosition( 4534, 2168, -199, "BUILD_construct" )</syntaxhighlight>

used to give the goal a new origin.

note: it's usually much better to use function Util.AddUsePoint to set position of BUILD or PLANT goals.

note: console command "/bot mypos" prints your body position, command "/viewpos" prints your eye position rounded to integer.

==== Util.SetGoalRange ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalRange( goalNames, distance or AABB );
examples:
Util.SetGoalRange("GRENADE_tower.*", 800);
Util.SetGoalRange("PLANT_SideGate", AABB(-2785,-3579,65,2702,-1306,257));
//reset to unlimited
Util.SetGoalRange("GRENADE_tower.*", 0);
Util.SetGoalRange("PLANT_SideGate", AABB());</syntaxhighlight>

sets the range for map goals. It can be int radius or AABB box or both. The QueryGoals functions does not return goals which are out of range. Default range for all goals is unlimited. Goals will not be interrupted if the range changes after the bot has already activated the goal.

==== Util.SetGroup ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetGroupForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetMaxUsers ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsers( botnum, goal );
example: Util.SetMaxUsers( 1, "ATTACK_.*" );
</syntaxhighlight>

used to limit number of bots using a particular goal(s). this function sets both In_Use and In_Progress

==== Util.SetMaxUsersInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInProgress( Users, GoalNames );
example: Util.SetMaxUsersInProgress( 15, "CHECKPOINT.*" );</syntaxhighlight>

used to set the maximum number of bots going for a particular goal(s).

==== Util.SetMaxUsersInUse ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInUse( Users, GoalNames );
example: Util.SetMaxUsersInUse( 1, "MOUNT_.*" );
</syntaxhighlight>

used to set the maximum number of bots using a particular goal(s).

==== Util.SetPercentInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetPercentInProgress(%, goal);
example: Util.SetPercentInProgress(70, "FLAG_docs");
</syntaxhighlight>

sets a percentage of bots to use a particular goal(s).

note: number of bots is calculated only once when this function is called. It does not work well after bots are added or kicked.

==== Util.SetPositionGoal ====

<syntaxhighlight lang="java">
syntax: Util.SetPositionGoal( goalname1, goalname2 );
example: Util.SetPositionGoal( "BUILD_Tank", "MOVER_tank" );</syntaxhighlight>

sets the origin of one goal to match the origin of another. This function was used in Omni-bot 0.66. Current Omni-bot version automatically sets positions of BUILD goals.

==== Util.SetRoleForGoals ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

==== Util.SetRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.SetRoleForGroup( <goal group>, <role or table> );
example: Util.SetRoleForGroup( "myGroup", ROLE.DEFENDER );
</syntaxhighlight>

sets the given roles for the given group of goals.

==== Util.SetRoleForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

see also: [[Roles]] Page

==== Util.ShowGroup ====

<syntaxhighlight lang="java">
syntax: Util.ShowGroup(groupname);
example: Util.ShowGroup("somegroupname");</syntaxhighlight>

this function will list all goals in the given group in the console.

==== Util.UpdateSwitchData ====

This function is deprecated. Use [[Switch_Goal]]

==== Util.WpNameInfo ====

<syntaxhighlight lang="java">
syntax: Util.WpNameInfo(waypointName);
example: wpInfo = Util.WpNameInfo("rNadeHall");</syntaxhighlight>

finds waypoint by name and returns table which contains position, facing, radius, flags, property. It is often used in paththrough navigation.

=== ETUtil ===
These functions are available only in the Enemy Territory game.

==== ETUtil.ChangeToPanzer ====

<syntaxhighlight lang="java">
syntax: ETUtil.ChangeToPanzer( bot );</syntaxhighlight>

called from OnBotJoin on panzer maps.

see also: [[Sniper_and_Panzer_maps]]

==== ETUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: ETUtil.CountClass( team, class );
example: ETUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== ETUtil.GetReinforceTime ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetReinforceTime(TEAM.AXIS);
</syntaxhighlight>

returns time to next respawn, or null if no bot exists in the team.

==== ETUtil.GetTimeElapsed ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetTimeElapsed();
</syntaxhighlight>

returns time since map start.

==== ETUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamClassDead( team, class );
example: ETUtil.IsTeamClassDead( TEAM.AXIS, CLASS.MEDIC );
</syntaxhighlight>

returns true if all the players of the given class on the given team are dead.

==== ETUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamDead( team );
example: ETUtil.IsTeamDead( TEAM.AXIS );
</syntaxhighlight>

returns true if all players on the given team are dead.

==== ETUtil.KillTeam ====

<syntaxhighlight lang="java">
syntax: ETUtil.KillTeam( team, <optional maxTime> );
example: ETUtil.KillTeam( TEAM.AXIS, 15 );
</syntaxhighlight>

waits for next respawn and then kills all bots in the team, but only if time to next respawn is not greater than maxTime.

==== ETUtil.LosingChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.LosingChat(team);
example: ETUtil.LosingChat( TEAM.AXIS );
</syntaxhighlight>

See [[Talking_bots]] page

==== ETUtil.SelectWeapon ====

This function does not work since version 0.82. Now you have to use [[Utility_Functions#WeaponTable|WeaponTable.SetWeaponAvailability]].

==== ETUtil.SetAimModeForMount====

<syntaxhighlight lang="java">
syntax: ETUtil.SetAimModeForMount(goalName, aimType);
example: ETUtil.SetAimModeForMount("MOUNT_ship", Vec3(-340, 1530, 90));</syntaxhighlight>

Sets AimMode property of MOUNT goal. Valid values are "velocity", "opposite", "random" or Vector3.

==== ETUtil.SetCabinets ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetCabinets();
</syntaxhighlight>

disables health & ammo cabinets for Medic & FieldOp Classes

==== ETUtil.SetExcludeIndexes ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetExcludeIndexes( goal, { offset } );
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", { 4, 5, 6 } ); // Disable offset 4, 5 & 6
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", {} ); // Removes Disabled offsets
</syntaxhighlight>

disables vehicle offsets, used when an offset cannot be reached. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SetStartIndex ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetStartIndex(goal, offset);
example: ETUtil.SetStartIndex("ESCORT_tank", 2); // Use Offset 2
example: ETUtil.SetStartIndex("ESCORT_tank", -1); // Random
</syntaxhighlight>

used to make a bot start from a certain vehicle offset in mover goals that have offsets defined. Normally set in OnMapLoad then reset inside a trigger. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SuicideSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.SuicideSpawn( team, spawn, numbots, class);
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, 1, CLASS.ENGINEER ); // 2 bots spawn at spawnpoint 2
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, -1, CLASS.ENGINEER ); // all axis engineer bots spawn at spawnpoint 2
</syntaxhighlight>

used to make bots self kill and change to a new spawn, often used in maps to defend areas when players have sneaked past.

==== ETUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: ETUtil.SwitchWeapon(weapon);
example: ETUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer</syntaxhighlight>

This function is deprecated since version 0.82 because it only kills bot and does not change his weapon.

==== ETUtil.WaitForSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.WaitForSpawn(Team);
example: ETUtil.WaitForSpawn( TEAM.ALLIES );
</syntaxhighlight>

Sleeps until next respawn of the team. Returns 0.15 seconds before respawn.

==== ETUtil.WinningChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.WinningChat(Team);
example: ETUtil.WinningChat( TEAM.ALLIES );
</syntaxhighlight>

See [[Talking_bots]] page

=== RTCWUtil ===
These functions are available only in the Return to Castle Wolfenstein game.

==== RTCWUtil.BotDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.BotDisableCombatCrouch( bot, bool enable );
example: RTCWUtil.BotDisableCombatCrouch( bot, true );
</syntaxhighlight>

used to disable crouching in combat for the given bot

==== RTCWUtil.ChangeClass ====

This function is deprecated. Use Server.MinClassCount.

==== RTCWUtil.ChangeSpawnNoDefenders ====

This function is deprecated. See [[Changing spawns]].

==== RTCWUtil.ClearMainGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearMainGoals();</syntaxhighlight>

This function will deactivate all main goals for both teams.

goals deactivated: PLANT MOUNTMG42 MOVER CHECKPOINT FLAG

==== RTCWUtil.ClearSecondaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearSecondaryGoals();</syntaxhighlight>

This function will deactivate all secondary goals for both teams.

goals deactivated: ARTILLERY REPAIR

==== RTCWUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.CountClass( team, class );
example: RTCWUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== RTCWUtil.CountTeam ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.DisableGoal(goalname, <optional true>);
example: RTCWUtil.DisableGoal("FLAG_someflag");
</syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== RTCWUtil.IsPlantGoalAvailable ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsPlantGoalAvailable();
example: RTCWUtil.IsPlantGoalAvailable();
</syntaxhighlight>

returns true if there is a plant goal available

==== RTCWUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamClassDead( team, class );
example: RTCWUtil.IsTeamClassDead( TEAM.AXIS, CLASS.ENGINEER )
</syntaxhighlight>

returns true if there are no living players or bots of a given class on the given team

==== RTCWUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamDead( team, minbots );
example: RTCWUtil.IsTeamDead( TEAM.AXIS, 2 );
</syntaxhighlight>

returns true if the number of living players on the given team is less than minbots.

note: minbots is optional as it defaults to 1

==== RTCWUtil.KillEntities ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.KillEntities( table or int );
example: RTCWUtil.KillEntities( 123 );
example: RTCWUtil.KillEntities( {123, 124} );
</syntaxhighlight>

used to remove entities from the map. typically called from OnMapLoad

==== RTCWUtil.NoSnipe ====

<syntaxhighlight lang="java">
syntax: syntax: RTCWUtil.NoSnipe(bot);</syntaxhighlight>
soldier bots will not choose a mauser when selecting a weapon

note: this is typically called in OnBotJoin

==== RTCWUtil.SelectSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in OnBotJoin to have soldiers choose between given weapons
example: RTCWUtil.SelectSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SelectSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser</syntaxhighlight>

==== RTCWUtil.SelectWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectWeapon(bot, weapon, isFog);
example: RTCWUtil.SelectWeapon(bot, WEAPON.MAUSER);

</syntaxhighlight>

the given bot will switch to the given weapon if it is the correct class for the weapon

note: typically used in OnBotJoin to have soldiers choose a specific weapon
the isFog parameter is optional and disables extra view distance given to snipers

==== RTCWUtil.SetPrimaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetPrimaryGoals(priority);
</syntaxhighlight>

used for setting priorities of common goals.

note: this is typically called in OnMapLoad and effects the following goals (in order of priority):
CAPPOINT FLAGRETURN PLANT CHECKPOINT FLAG

==== RTCWUtil.SetSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, class, suicide, persistant);
sets all classes on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.SetTeamSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, suicide, persistant);
sets all bots on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.StopSniping ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.StopSniping();</syntaxhighlight>
all bots currently using a sniper weapon will switch to a different weapon

note: this is typically called inside trigger functions

==== RTCWUtil.SwitchSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in triggers to have soldiers choose between given weapons
example: RTCWUtil.SwitchSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SwitchSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser
</syntaxhighlight>

==== RTCWUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchWeapon(weapon);
all qualifying bots will switch to the given weapon

example: RTCWUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer
note: typically used in trigger functions</syntaxhighlight>

==== RTCWUtil.TeamDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.TeamDisableCombatCrouch( team );
example: RTCWUtil.TeamDisableCombatCrouch( TEAM.AXIS );
</syntaxhighlight>

disables combat crouching for the given team

==== RTCWUtil.ToggleFlag ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ToggleFlag( goal, time in seconds );
example: thread(RTCWUtil.ToggleFlag, "CHECKPOINT.someFlag", 300);
</syntaxhighlight>

used in dual objective maps like mp_depot to set availability of the checkpoint goal for the opposite team in the given interval
note: this should be called as a gm thread.

=== WeaponTable ===

==== WeaponTable.ListWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.ListWeaponAvailability();
</syntaxhighlight>

prints current availability of all weapons

==== WeaponTable.SetWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponAvailability( class, weapon, <true/false>);
example: WeaponTable.SetWeaponAvailability( CLASS.SOLDIER, WEAPON.FLAMETHROWER, false );</syntaxhighlight>

enables or disables specified weapon for class. The weapon parameter can be table.
The class parameter can be null to set availability for all classes.

note: allied PANZERFAUST is automatically converted to BAZOOKA or LAW in Noquarter or ETnam

note: bots select random available weapon every spawn (in limbo)

==== WeaponTable.SetWeaponTeamAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponTeamAvailability( team, class, weapon, <true/false>);
example: WeaponTable.SetWeaponTeamAvailability( TEAM.AXIS, CLASS.ENGINEER, WEAPON.KAR98, false );</syntaxhighlight>

enables or disables weapon for team and class.

==== WeaponTable.Shotgun ====

The Shotgun property has value WEAPON.SHOTGUN, WEAPON.ITHACA, WEAPON.M97 or null.

Utility Functions

2025-05-25T17:31:07Z

Palota: /* ETUtil.IsTeamDead */

{{process header
| title = Utility Functions
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

{{TOCright}}

=== Util ===

==== Util.AddUsePoint ====

<syntaxhighlight lang="java">
syntax: Util.AddUsePoint(goalname, <Vector3 or table>);
example: Util.AddUsePoint("PLANT_wall",{Vec3(12,34,5),Vec3(23,5,67)});</syntaxhighlight>

used to add use points for a goal at given positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AddUseWp ====

<syntaxhighlight lang="java">
syntax: Util.AddUseWp(goalname, <waypointname or table>);
example: Util.AddUseWp( "somegoalname", "somewaypointname" );</syntaxhighlight>

used to add use points for a goal at given waypoints positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AliveCount ====

<syntaxhighlight lang="java">
syntax: Util.AliveCount( team, class );
example: Util.AliveCount( TEAM.AXIS, CLASS.MEDIC ); </syntaxhighlight>

returns the number of bots alive on a team with a given class

==== Util.BotChat ====

<syntaxhighlight lang="java">
syntax: Util.BotChat(Team, msgType, Msg, NumBots);
example: Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_CHEER, 2);
</syntaxhighlight>

See [[Talking_bots]] page

==== Util.BotHasAnyRole ====

This function is deprecated. Use [[Bot#HasRole|HasRole]]

==== Util.CanBotSnipe ====

<syntaxhighlight lang="java">
syntax: Util.CanBotSnipe(bot);
example: if ( Util.CanBotSnipe(bot) ) {
</syntaxhighlight>

returns true if bot has a sniper weapon.

==== Util.CappointForFlag ====
<syntaxhighlight lang="java">
syntax: Util.CappointForFlag( flag_goalname, cappoint_goalname );
example: Util.CappointForFlag( "FLAG_axis_gold", "CAPPOINT_Truck" );
</syntaxhighlight>

used if there are multiple active cappoint goals. It should be called from _Taken triggers.

==== Util.ChangeBotSpawn ====
This function is deprecated. See [[Changing spawns]].

==== Util.ChangeCrucialClassForRole ====
<syntaxhighlight lang="java">
syntax: Util.ChangeCrucialClassForRole ( team, role, class );
example: Util.ChangeCrucialClassForRole(TEAM.AXIS, ROLE.DEFENDER1, CLASS.COVERTOPS);
</syntaxhighlight>

Sets new crucialClass in the Map.Roles table.

==== Util.ChangeSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.ChangeSpawnForRole ====

<syntaxhighlight lang="java">
syntax: Util.ChangeSpawnForRole( <team>, <role>, <spawnpoint> );
example: Util.ChangeSpawnForRole(TEAM.ALLIES, ROLE.ATTACKER, 1);
</syntaxhighlight>

Set the spawn point for all bots on the given team with the given role

see also: [[Roles]] Page

==== Util.ChangeToSniperWeapons ====

<syntaxhighlight lang="java">
syntax: Util.ChangeToSniperWeapons( bot, <optional viewDistance> );
example: Util.ChangeToSniperWeapons(bot);
</syntaxhighlight>

called from OnBotJoin on sniper maps.

see also: [[Sniper_and_Panzer_maps]]

==== Util.ClearRoleForGoals ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.ClearRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.ClearRoleForGroup( group, <role or table> );
example: Util.ClearRoleForGroup( "someGroup", ROLE.DEFENDER );
</syntaxhighlight>

used to remove roles from a given group of goals

see also: [[Roles]] Page

==== Util.ClearRoleForTable ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.DisableGoal ====

<syntaxhighlight lang="java">
syntax: Util.DisableGoal(goalname, <optional true>);
example: Util.DisableGoal("FLAG_someflag"); </syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== Util.DisableGroup ====

<syntaxhighlight lang="java">
syntax: Util.DisableGroup(groupname, team);
example: Util.DisableGroup( "somegroupname", TEAM.ALLIES );</syntaxhighlight>

used to disable a set of goals in the given group for a given team

==== Util.EnableGoal ====

<syntaxhighlight lang="java">
syntax: Util.EnableGoal(goalname);
example: Util.EnableGoal("FLAG_someflag");</syntaxhighlight>

enables the goal for both teams.

==== Util.EnableGroup ====

<syntaxhighlight lang="java">
syntax: Util.EnableGroup(groupname, team);
example: Util.EnableGroup( "somegroupname", TEAM.SOMETEAM );</syntaxhighlight>

used to enable a set of goals in the given group for a given team

==== Util.ExcludeClass ====

<syntaxhighlight lang="java">
syntax: Util.ExcludeClass( goalname, team, class1, class2, class3, class4 );
example: Util.ExcludeClass( "DEFEND_somegoal.*", TEAM.AXIS, CLASS.MEDIC );
example: Util.ExcludeClass( "MOUNTMG42_.*", TEAM.ALLIES, CLASS.FIELDOPS, CLASS.ENGINEER );
</syntaxhighlight>

limit given goal usage to specific classes by team. class2, class3, and class4 are optional.

==== Util.ForceRouting ====

<syntaxhighlight lang="java">
syntax: Util.ForceRouting(goalName, true/false);
example: Util.ForceRouting( "BUILD_Tank", true );</syntaxhighlight>

disables BUILD goal offsets and enables routes to the goal. You should set ForceRouting to true only when a vehicle is at known position (in OnMapLoad or at tank barriers). You must set it to false when a vehicle is repaired.

==== Util.GetEntHealth ====

<syntaxhighlight lang="java">
syntax: Util.GetEntHealth(entity);
example: health = Util.GetEntHealth(this.TargetEntity);</syntaxhighlight>

returns entity health.

==== Util.GetGroup ====

<syntaxhighlight lang="java">
syntax: Util.GetGroup(groupname);
example: Util.GetGroup("somegroupname");</syntaxhighlight>

this function will return a table of goals belonging to the given group name

==== Util.GetRandomFromTable ====

<syntaxhighlight lang="java">
syntax: Util.GetRandomFromTable( tbl );
example: index = Util.GetRandomFromTable( someTable );
</syntaxhighlight>

used to get a randomly selected index from a given table. Returns -1 if invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GetRandomTableValue====

<syntaxhighlight lang="java">
syntax: Util.GetRandomTableValue( tbl );
example: value = Util.GetRandomTableValue( someTable );
</syntaxhighlight>

used to get a randomly selected value from a given table. Returns null if the table is empty or invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GoalTable ====

<syntaxhighlight lang="java">
syntax: Util.GoalTable( <optional expression>, <optional teamId> );
example: goals = Util.GoalTable("PLANT_Back_Door");
example: goals = Util.GoalTable("FLAG.*", TEAM.AXIS);
</syntaxhighlight>

returns table of map goals that match a regular expression.

==== Util.IgnoreTargetGoal ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IgnoreTargetGoalTable ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IsBot ====

<syntaxhighlight lang="java">
syntax: Util.IsBot(entity);
example: bot = Util.IsBot(ent);
</syntaxhighlight>

returns Bot object from entity or null if entity is not a bot. Usually used in region triggers if the TriggerOnClass is CLASS.ANYPLAYER.

==== Util.LimitToClass ====

<syntaxhighlight lang="java">
syntax: Util.LimitToClass(goalname, team, class1, class2, class3, class4);
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER); //only soldiers on the allied team
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER, CLASS.MEDIC); //only soldiers and medics</syntaxhighlight>

used to limit specific goals to a specific class or classes

==== Util.LimitToTeam ====

<syntaxhighlight lang="java">
syntax: Util.LimitToTeam(team, goal);
example: Util.LimitToTeam(TEAM.AXIS, "SWITCH_gate_depot");
</syntaxhighlight>

limits goals to a certain team without the need to disable for 1 team

==== Util.MapDebugPrint ====

<syntaxhighlight lang="java">
syntax: Util.MapDebugPrint( "Text", <optional message only> );
example: Util.MapDebugPrint( "East_Barrier_Destroyed" );
example: Util.MapDebugPrint( "East_Barrier_Destroyed", true ); // only print the message
</syntaxhighlight>

used to print text & list of available goals in the console when in debug mode

see also: [[Debugging_tips]]

==== Util.OnTriggerPosition ====

<syntaxhighlight lang="java">
syntax: Util.OnTriggerPosition( goalname, wpname or position, tolerance, wpfunction );
example: Util.OnTriggerPosition( "MOVER_train1", "depotyard", 200.0, Map.tug_depotyard );</syntaxhighlight>

note: used for setting up positional triggers for movers.

==== Util.RandomBotSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RandomSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RemoveGoal ====

<syntaxhighlight lang="java">
syntax: Util.RemoveGoal( goalnames );
example: Util.RemoveGoal( "MOVER_truck" );</syntaxhighlight>

removes the goals from the map goal table. It should only be used for invalid goals which are badly detected by the game.

==== Util.Routes ====

<syntaxhighlight lang="java">
syntax: Util.Routes( <table> );
example: Util.Routes(MapRoutes);</syntaxhighlight>

initializes routes

see also: [[Template:Baserouting|Routing]]

==== Util.SetGoalOffset ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalOffset( x, y, z, GoalName );
info x = North, -x = South y = East, -y = West, z = Up, -z =Down
example: Util.SetGoalOffset( 0, -20, -10, "MOUNTMG42_boat" );</syntaxhighlight>

the x y and z parameters are added to the origin of the goal to move the location of where bots will look for the goal. It is sometimes needed for MOUNTMG42 and REPAIRMG42 goals because some mg42 cannot be mounted or repaired if it's position is not corrected.

==== Util.SetGoalPosition ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalPosition( x, y, z, GoalName );
example: Util.SetGoalPosition( 4534, 2168, -199, "BUILD_construct" )</syntaxhighlight>

used to give the goal a new origin.

note: it's usually much better to use function Util.AddUsePoint to set position of BUILD or PLANT goals.

note: console command "/bot mypos" prints your body position, command "/viewpos" prints your eye position rounded to integer.

==== Util.SetGoalRange ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalRange( goalNames, distance );
example: Util.SetGoalRange("GRENADE_tower.*", 800);</syntaxhighlight>

sets the range for map goals. The goals will not be available for bots that are out of range. Default range for all goals is 0 which means unlimited.

==== Util.SetGroup ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetGroupForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetMaxUsers ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsers( botnum, goal );
example: Util.SetMaxUsers( 1, "ATTACK_.*" );
</syntaxhighlight>

used to limit number of bots using a particular goal(s). this function sets both In_Use and In_Progress

==== Util.SetMaxUsersInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInProgress( Users, GoalNames );
example: Util.SetMaxUsersInProgress( 15, "CHECKPOINT.*" );</syntaxhighlight>

used to set the maximum number of bots going for a particular goal(s).

==== Util.SetMaxUsersInUse ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInUse( Users, GoalNames );
example: Util.SetMaxUsersInUse( 1, "MOUNT_.*" );
</syntaxhighlight>

used to set the maximum number of bots using a particular goal(s).

==== Util.SetPercentInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetPercentInProgress(%, goal);
example: Util.SetPercentInProgress(70, "FLAG_docs");
</syntaxhighlight>

sets a percentage of bots to use a particular goal(s).

note: number of bots is calculated only once when this function is called. It does not work well after bots are added or kicked.

==== Util.SetPositionGoal ====

<syntaxhighlight lang="java">
syntax: Util.SetPositionGoal( goalname1, goalname2 );
example: Util.SetPositionGoal( "BUILD_Tank", "MOVER_tank" );</syntaxhighlight>

sets the origin of one goal to match the origin of another. This function was used in Omni-bot 0.66. Current Omni-bot version automatically sets positions of BUILD goals.

==== Util.SetRoleForGoals ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

==== Util.SetRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.SetRoleForGroup( <goal group>, <role or table> );
example: Util.SetRoleForGroup( "myGroup", ROLE.DEFENDER );
</syntaxhighlight>

sets the given roles for the given group of goals.

==== Util.SetRoleForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

see also: [[Roles]] Page

==== Util.ShowGroup ====

<syntaxhighlight lang="java">
syntax: Util.ShowGroup(groupname);
example: Util.ShowGroup("somegroupname");</syntaxhighlight>

this function will list all goals in the given group in the console.

==== Util.UpdateSwitchData ====

This function is deprecated. Use [[Switch_Goal]]

==== Util.WpNameInfo ====

<syntaxhighlight lang="java">
syntax: Util.WpNameInfo(waypointName);
example: wpInfo = Util.WpNameInfo("rNadeHall");</syntaxhighlight>

finds waypoint by name and returns table which contains position, facing, radius, flags, property. It is often used in paththrough navigation.

=== ETUtil ===
These functions are available only in the Enemy Territory game.

==== ETUtil.ChangeToPanzer ====

<syntaxhighlight lang="java">
syntax: ETUtil.ChangeToPanzer( bot );</syntaxhighlight>

called from OnBotJoin on panzer maps.

see also: [[Sniper_and_Panzer_maps]]

==== ETUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: ETUtil.CountClass( team, class );
example: ETUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== ETUtil.GetReinforceTime ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetReinforceTime(TEAM.AXIS);
</syntaxhighlight>

returns time to next respawn, or null if no bot exists in the team.

==== ETUtil.GetTimeElapsed ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetTimeElapsed();
</syntaxhighlight>

returns time since map start.

==== ETUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamClassDead( team, class );
example: ETUtil.IsTeamClassDead( TEAM.AXIS, CLASS.MEDIC );
</syntaxhighlight>

returns true if all the players of the given class on the given team are dead.

==== ETUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamDead( team );
example: ETUtil.IsTeamDead( TEAM.AXIS );
</syntaxhighlight>

returns true if all players on the given team are dead.

==== ETUtil.KillTeam ====

<syntaxhighlight lang="java">
syntax: ETUtil.KillTeam( team, <optional maxTime> );
example: ETUtil.KillTeam( TEAM.AXIS, 15 );
</syntaxhighlight>

waits for next respawn and then kills all bots in the team, but only if time to next respawn is not greater than maxTime.

==== ETUtil.LosingChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.LosingChat(team);
example: ETUtil.LosingChat( TEAM.AXIS );
</syntaxhighlight>

See [[Talking_bots]] page

==== ETUtil.SelectWeapon ====

This function does not work since version 0.82. Now you have to use [[Utility_Functions#WeaponTable|WeaponTable.SetWeaponAvailability]].

==== ETUtil.SetAimModeForMount====

<syntaxhighlight lang="java">
syntax: ETUtil.SetAimModeForMount(goalName, aimType);
example: ETUtil.SetAimModeForMount("MOUNT_ship", Vec3(-340, 1530, 90));</syntaxhighlight>

Sets AimMode property of MOUNT goal. Valid values are "velocity", "opposite", "random" or Vector3.

==== ETUtil.SetCabinets ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetCabinets();
</syntaxhighlight>

disables health & ammo cabinets for Medic & FieldOp Classes

==== ETUtil.SetExcludeIndexes ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetExcludeIndexes( goal, { offset } );
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", { 4, 5, 6 } ); // Disable offset 4, 5 & 6
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", {} ); // Removes Disabled offsets
</syntaxhighlight>

disables vehicle offsets, used when an offset cannot be reached. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SetStartIndex ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetStartIndex(goal, offset);
example: ETUtil.SetStartIndex("ESCORT_tank", 2); // Use Offset 2
example: ETUtil.SetStartIndex("ESCORT_tank", -1); // Random
</syntaxhighlight>

used to make a bot start from a certain vehicle offset in mover goals that have offsets defined. Normally set in OnMapLoad then reset inside a trigger. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SuicideSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.SuicideSpawn( team, spawn, numbots, class);
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, 1, CLASS.ENGINEER ); // 2 bots spawn at spawnpoint 2
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, -1, CLASS.ENGINEER ); // all axis engineer bots spawn at spawnpoint 2
</syntaxhighlight>

used to make bots self kill and change to a new spawn, often used in maps to defend areas when players have sneaked past.

==== ETUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: ETUtil.SwitchWeapon(weapon);
example: ETUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer</syntaxhighlight>

This function is deprecated since version 0.82 because it only kills bot and does not change his weapon.

==== ETUtil.WaitForSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.WaitForSpawn(Team);
example: ETUtil.WaitForSpawn( TEAM.ALLIES );
</syntaxhighlight>

Sleeps until next respawn of the team. Returns 0.15 seconds before respawn.

==== ETUtil.WinningChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.WinningChat(Team);
example: ETUtil.WinningChat( TEAM.ALLIES );
</syntaxhighlight>

See [[Talking_bots]] page

=== RTCWUtil ===
These functions are available only in the Return to Castle Wolfenstein game.

==== RTCWUtil.BotDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.BotDisableCombatCrouch( bot, bool enable );
example: RTCWUtil.BotDisableCombatCrouch( bot, true );
</syntaxhighlight>

used to disable crouching in combat for the given bot

==== RTCWUtil.ChangeClass ====

This function is deprecated. Use Server.MinClassCount.

==== RTCWUtil.ChangeSpawnNoDefenders ====

This function is deprecated. See [[Changing spawns]].

==== RTCWUtil.ClearMainGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearMainGoals();</syntaxhighlight>

This function will deactivate all main goals for both teams.

goals deactivated: PLANT MOUNTMG42 MOVER CHECKPOINT FLAG

==== RTCWUtil.ClearSecondaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearSecondaryGoals();</syntaxhighlight>

This function will deactivate all secondary goals for both teams.

goals deactivated: ARTILLERY REPAIR

==== RTCWUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.CountClass( team, class );
example: RTCWUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== RTCWUtil.CountTeam ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.DisableGoal(goalname, <optional true>);
example: RTCWUtil.DisableGoal("FLAG_someflag");
</syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== RTCWUtil.IsPlantGoalAvailable ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsPlantGoalAvailable();
example: RTCWUtil.IsPlantGoalAvailable();
</syntaxhighlight>

returns true if there is a plant goal available

==== RTCWUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamClassDead( team, class );
example: RTCWUtil.IsTeamClassDead( TEAM.AXIS, CLASS.ENGINEER )
</syntaxhighlight>

returns true if there are no living players or bots of a given class on the given team

==== RTCWUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamDead( team, minbots );
example: RTCWUtil.IsTeamDead( TEAM.AXIS, 2 );
</syntaxhighlight>

returns true if the number of living players on the given team is less than minbots.

note: minbots is optional as it defaults to 1

==== RTCWUtil.KillEntities ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.KillEntities( table or int );
example: RTCWUtil.KillEntities( 123 );
example: RTCWUtil.KillEntities( {123, 124} );
</syntaxhighlight>

used to remove entities from the map. typically called from OnMapLoad

==== RTCWUtil.NoSnipe ====

<syntaxhighlight lang="java">
syntax: syntax: RTCWUtil.NoSnipe(bot);</syntaxhighlight>
soldier bots will not choose a mauser when selecting a weapon

note: this is typically called in OnBotJoin

==== RTCWUtil.SelectSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in OnBotJoin to have soldiers choose between given weapons
example: RTCWUtil.SelectSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SelectSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser</syntaxhighlight>

==== RTCWUtil.SelectWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectWeapon(bot, weapon, isFog);
example: RTCWUtil.SelectWeapon(bot, WEAPON.MAUSER);

</syntaxhighlight>

the given bot will switch to the given weapon if it is the correct class for the weapon

note: typically used in OnBotJoin to have soldiers choose a specific weapon
the isFog parameter is optional and disables extra view distance given to snipers

==== RTCWUtil.SetPrimaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetPrimaryGoals(priority);
</syntaxhighlight>

used for setting priorities of common goals.

note: this is typically called in OnMapLoad and effects the following goals (in order of priority):
CAPPOINT FLAGRETURN PLANT CHECKPOINT FLAG

==== RTCWUtil.SetSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, class, suicide, persistant);
sets all classes on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.SetTeamSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, suicide, persistant);
sets all bots on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.StopSniping ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.StopSniping();</syntaxhighlight>
all bots currently using a sniper weapon will switch to a different weapon

note: this is typically called inside trigger functions

==== RTCWUtil.SwitchSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in triggers to have soldiers choose between given weapons
example: RTCWUtil.SwitchSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SwitchSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser
</syntaxhighlight>

==== RTCWUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchWeapon(weapon);
all qualifying bots will switch to the given weapon

example: RTCWUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer
note: typically used in trigger functions</syntaxhighlight>

==== RTCWUtil.TeamDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.TeamDisableCombatCrouch( team );
example: RTCWUtil.TeamDisableCombatCrouch( TEAM.AXIS );
</syntaxhighlight>

disables combat crouching for the given team

==== RTCWUtil.ToggleFlag ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ToggleFlag( goal, time in seconds );
example: thread(RTCWUtil.ToggleFlag, "CHECKPOINT.someFlag", 300);
</syntaxhighlight>

used in dual objective maps like mp_depot to set availability of the checkpoint goal for the opposite team in the given interval
note: this should be called as a gm thread.

=== WeaponTable ===

==== WeaponTable.ListWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.ListWeaponAvailability();
</syntaxhighlight>

prints current availability of all weapons

==== WeaponTable.SetWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponAvailability( class, weapon, <true/false>);
example: WeaponTable.SetWeaponAvailability( CLASS.SOLDIER, WEAPON.FLAMETHROWER, false );</syntaxhighlight>

enables or disables specified weapon for class. The weapon parameter can be table.
The class parameter can be null to set availability for all classes.

note: allied PANZERFAUST is automatically converted to BAZOOKA or LAW in Noquarter or ETnam

note: bots select random available weapon every spawn (in limbo)

==== WeaponTable.SetWeaponTeamAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponTeamAvailability( team, class, weapon, <true/false>);
example: WeaponTable.SetWeaponTeamAvailability( TEAM.AXIS, CLASS.ENGINEER, WEAPON.KAR98, false );</syntaxhighlight>

enables or disables weapon for team and class.

==== WeaponTable.Shotgun ====

The Shotgun property has value WEAPON.SHOTGUN, WEAPON.ITHACA, WEAPON.M97 or null.

Utility Functions

2025-05-25T17:14:34Z

Palota: /* ETUtil.WinningChat */

{{process header
| title = Utility Functions
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

{{TOCright}}

=== Util ===

==== Util.AddUsePoint ====

<syntaxhighlight lang="java">
syntax: Util.AddUsePoint(goalname, <Vector3 or table>);
example: Util.AddUsePoint("PLANT_wall",{Vec3(12,34,5),Vec3(23,5,67)});</syntaxhighlight>

used to add use points for a goal at given positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AddUseWp ====

<syntaxhighlight lang="java">
syntax: Util.AddUseWp(goalname, <waypointname or table>);
example: Util.AddUseWp( "somegoalname", "somewaypointname" );</syntaxhighlight>

used to add use points for a goal at given waypoints positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AliveCount ====

<syntaxhighlight lang="java">
syntax: Util.AliveCount( team, class );
example: Util.AliveCount( TEAM.AXIS, CLASS.MEDIC ); </syntaxhighlight>

returns the number of bots alive on a team with a given class

==== Util.BotChat ====

<syntaxhighlight lang="java">
syntax: Util.BotChat(Team, msgType, Msg, NumBots);
example: Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_CHEER, 2);
</syntaxhighlight>

See [[Talking_bots]] page

==== Util.BotHasAnyRole ====

This function is deprecated. Use [[Bot#HasRole|HasRole]]

==== Util.CanBotSnipe ====

<syntaxhighlight lang="java">
syntax: Util.CanBotSnipe(bot);
example: if ( Util.CanBotSnipe(bot) ) {
</syntaxhighlight>

returns true if bot has a sniper weapon.

==== Util.CappointForFlag ====
<syntaxhighlight lang="java">
syntax: Util.CappointForFlag( flag_goalname, cappoint_goalname );
example: Util.CappointForFlag( "FLAG_axis_gold", "CAPPOINT_Truck" );
</syntaxhighlight>

used if there are multiple active cappoint goals. It should be called from _Taken triggers.

==== Util.ChangeBotSpawn ====
This function is deprecated. See [[Changing spawns]].

==== Util.ChangeCrucialClassForRole ====
<syntaxhighlight lang="java">
syntax: Util.ChangeCrucialClassForRole ( team, role, class );
example: Util.ChangeCrucialClassForRole(TEAM.AXIS, ROLE.DEFENDER1, CLASS.COVERTOPS);
</syntaxhighlight>

Sets new crucialClass in the Map.Roles table.

==== Util.ChangeSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.ChangeSpawnForRole ====

<syntaxhighlight lang="java">
syntax: Util.ChangeSpawnForRole( <team>, <role>, <spawnpoint> );
example: Util.ChangeSpawnForRole(TEAM.ALLIES, ROLE.ATTACKER, 1);
</syntaxhighlight>

Set the spawn point for all bots on the given team with the given role

see also: [[Roles]] Page

==== Util.ChangeToSniperWeapons ====

<syntaxhighlight lang="java">
syntax: Util.ChangeToSniperWeapons( bot, <optional viewDistance> );
example: Util.ChangeToSniperWeapons(bot);
</syntaxhighlight>

called from OnBotJoin on sniper maps.

see also: [[Sniper_and_Panzer_maps]]

==== Util.ClearRoleForGoals ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.ClearRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.ClearRoleForGroup( group, <role or table> );
example: Util.ClearRoleForGroup( "someGroup", ROLE.DEFENDER );
</syntaxhighlight>

used to remove roles from a given group of goals

see also: [[Roles]] Page

==== Util.ClearRoleForTable ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.DisableGoal ====

<syntaxhighlight lang="java">
syntax: Util.DisableGoal(goalname, <optional true>);
example: Util.DisableGoal("FLAG_someflag"); </syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== Util.DisableGroup ====

<syntaxhighlight lang="java">
syntax: Util.DisableGroup(groupname, team);
example: Util.DisableGroup( "somegroupname", TEAM.ALLIES );</syntaxhighlight>

used to disable a set of goals in the given group for a given team

==== Util.EnableGoal ====

<syntaxhighlight lang="java">
syntax: Util.EnableGoal(goalname);
example: Util.EnableGoal("FLAG_someflag");</syntaxhighlight>

enables the goal for both teams.

==== Util.EnableGroup ====

<syntaxhighlight lang="java">
syntax: Util.EnableGroup(groupname, team);
example: Util.EnableGroup( "somegroupname", TEAM.SOMETEAM );</syntaxhighlight>

used to enable a set of goals in the given group for a given team

==== Util.ExcludeClass ====

<syntaxhighlight lang="java">
syntax: Util.ExcludeClass( goalname, team, class1, class2, class3, class4 );
example: Util.ExcludeClass( "DEFEND_somegoal.*", TEAM.AXIS, CLASS.MEDIC );
example: Util.ExcludeClass( "MOUNTMG42_.*", TEAM.ALLIES, CLASS.FIELDOPS, CLASS.ENGINEER );
</syntaxhighlight>

limit given goal usage to specific classes by team. class2, class3, and class4 are optional.

==== Util.ForceRouting ====

<syntaxhighlight lang="java">
syntax: Util.ForceRouting(goalName, true/false);
example: Util.ForceRouting( "BUILD_Tank", true );</syntaxhighlight>

disables BUILD goal offsets and enables routes to the goal. You should set ForceRouting to true only when a vehicle is at known position (in OnMapLoad or at tank barriers). You must set it to false when a vehicle is repaired.

==== Util.GetEntHealth ====

<syntaxhighlight lang="java">
syntax: Util.GetEntHealth(entity);
example: health = Util.GetEntHealth(this.TargetEntity);</syntaxhighlight>

returns entity health.

==== Util.GetGroup ====

<syntaxhighlight lang="java">
syntax: Util.GetGroup(groupname);
example: Util.GetGroup("somegroupname");</syntaxhighlight>

this function will return a table of goals belonging to the given group name

==== Util.GetRandomFromTable ====

<syntaxhighlight lang="java">
syntax: Util.GetRandomFromTable( tbl );
example: index = Util.GetRandomFromTable( someTable );
</syntaxhighlight>

used to get a randomly selected index from a given table. Returns -1 if invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GetRandomTableValue====

<syntaxhighlight lang="java">
syntax: Util.GetRandomTableValue( tbl );
example: value = Util.GetRandomTableValue( someTable );
</syntaxhighlight>

used to get a randomly selected value from a given table. Returns null if the table is empty or invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GoalTable ====

<syntaxhighlight lang="java">
syntax: Util.GoalTable( <optional expression>, <optional teamId> );
example: goals = Util.GoalTable("PLANT_Back_Door");
example: goals = Util.GoalTable("FLAG.*", TEAM.AXIS);
</syntaxhighlight>

returns table of map goals that match a regular expression.

==== Util.IgnoreTargetGoal ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IgnoreTargetGoalTable ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IsBot ====

<syntaxhighlight lang="java">
syntax: Util.IsBot(entity);
example: bot = Util.IsBot(ent);
</syntaxhighlight>

returns Bot object from entity or null if entity is not a bot. Usually used in region triggers if the TriggerOnClass is CLASS.ANYPLAYER.

==== Util.LimitToClass ====

<syntaxhighlight lang="java">
syntax: Util.LimitToClass(goalname, team, class1, class2, class3, class4);
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER); //only soldiers on the allied team
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER, CLASS.MEDIC); //only soldiers and medics</syntaxhighlight>

used to limit specific goals to a specific class or classes

==== Util.LimitToTeam ====

<syntaxhighlight lang="java">
syntax: Util.LimitToTeam(team, goal);
example: Util.LimitToTeam(TEAM.AXIS, "SWITCH_gate_depot");
</syntaxhighlight>

limits goals to a certain team without the need to disable for 1 team

==== Util.MapDebugPrint ====

<syntaxhighlight lang="java">
syntax: Util.MapDebugPrint( "Text", <optional message only> );
example: Util.MapDebugPrint( "East_Barrier_Destroyed" );
example: Util.MapDebugPrint( "East_Barrier_Destroyed", true ); // only print the message
</syntaxhighlight>

used to print text & list of available goals in the console when in debug mode

see also: [[Debugging_tips]]

==== Util.OnTriggerPosition ====

<syntaxhighlight lang="java">
syntax: Util.OnTriggerPosition( goalname, wpname or position, tolerance, wpfunction );
example: Util.OnTriggerPosition( "MOVER_train1", "depotyard", 200.0, Map.tug_depotyard );</syntaxhighlight>

note: used for setting up positional triggers for movers.

==== Util.RandomBotSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RandomSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RemoveGoal ====

<syntaxhighlight lang="java">
syntax: Util.RemoveGoal( goalnames );
example: Util.RemoveGoal( "MOVER_truck" );</syntaxhighlight>

removes the goals from the map goal table. It should only be used for invalid goals which are badly detected by the game.

==== Util.Routes ====

<syntaxhighlight lang="java">
syntax: Util.Routes( <table> );
example: Util.Routes(MapRoutes);</syntaxhighlight>

initializes routes

see also: [[Template:Baserouting|Routing]]

==== Util.SetGoalOffset ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalOffset( x, y, z, GoalName );
info x = North, -x = South y = East, -y = West, z = Up, -z =Down
example: Util.SetGoalOffset( 0, -20, -10, "MOUNTMG42_boat" );</syntaxhighlight>

the x y and z parameters are added to the origin of the goal to move the location of where bots will look for the goal. It is sometimes needed for MOUNTMG42 and REPAIRMG42 goals because some mg42 cannot be mounted or repaired if it's position is not corrected.

==== Util.SetGoalPosition ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalPosition( x, y, z, GoalName );
example: Util.SetGoalPosition( 4534, 2168, -199, "BUILD_construct" )</syntaxhighlight>

used to give the goal a new origin.

note: it's usually much better to use function Util.AddUsePoint to set position of BUILD or PLANT goals.

note: console command "/bot mypos" prints your body position, command "/viewpos" prints your eye position rounded to integer.

==== Util.SetGoalRange ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalRange( goalNames, distance );
example: Util.SetGoalRange("GRENADE_tower.*", 800);</syntaxhighlight>

sets the range for map goals. The goals will not be available for bots that are out of range. Default range for all goals is 0 which means unlimited.

==== Util.SetGroup ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetGroupForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetMaxUsers ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsers( botnum, goal );
example: Util.SetMaxUsers( 1, "ATTACK_.*" );
</syntaxhighlight>

used to limit number of bots using a particular goal(s). this function sets both In_Use and In_Progress

==== Util.SetMaxUsersInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInProgress( Users, GoalNames );
example: Util.SetMaxUsersInProgress( 15, "CHECKPOINT.*" );</syntaxhighlight>

used to set the maximum number of bots going for a particular goal(s).

==== Util.SetMaxUsersInUse ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInUse( Users, GoalNames );
example: Util.SetMaxUsersInUse( 1, "MOUNT_.*" );
</syntaxhighlight>

used to set the maximum number of bots using a particular goal(s).

==== Util.SetPercentInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetPercentInProgress(%, goal);
example: Util.SetPercentInProgress(70, "FLAG_docs");
</syntaxhighlight>

sets a percentage of bots to use a particular goal(s).

note: number of bots is calculated only once when this function is called. It does not work well after bots are added or kicked.

==== Util.SetPositionGoal ====

<syntaxhighlight lang="java">
syntax: Util.SetPositionGoal( goalname1, goalname2 );
example: Util.SetPositionGoal( "BUILD_Tank", "MOVER_tank" );</syntaxhighlight>

sets the origin of one goal to match the origin of another. This function was used in Omni-bot 0.66. Current Omni-bot version automatically sets positions of BUILD goals.

==== Util.SetRoleForGoals ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

==== Util.SetRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.SetRoleForGroup( <goal group>, <role or table> );
example: Util.SetRoleForGroup( "myGroup", ROLE.DEFENDER );
</syntaxhighlight>

sets the given roles for the given group of goals.

==== Util.SetRoleForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

see also: [[Roles]] Page

==== Util.ShowGroup ====

<syntaxhighlight lang="java">
syntax: Util.ShowGroup(groupname);
example: Util.ShowGroup("somegroupname");</syntaxhighlight>

this function will list all goals in the given group in the console.

==== Util.UpdateSwitchData ====

This function is deprecated. Use [[Switch_Goal]]

==== Util.WpNameInfo ====

<syntaxhighlight lang="java">
syntax: Util.WpNameInfo(waypointName);
example: wpInfo = Util.WpNameInfo("rNadeHall");</syntaxhighlight>

finds waypoint by name and returns table which contains position, facing, radius, flags, property. It is often used in paththrough navigation.

=== ETUtil ===
These functions are available only in the Enemy Territory game.

==== ETUtil.ChangeToPanzer ====

<syntaxhighlight lang="java">
syntax: ETUtil.ChangeToPanzer( bot );</syntaxhighlight>

called from OnBotJoin on panzer maps.

see also: [[Sniper_and_Panzer_maps]]

==== ETUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: ETUtil.CountClass( team, class );
example: ETUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== ETUtil.GetReinforceTime ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetReinforceTime(TEAM.AXIS);
</syntaxhighlight>

returns time to next respawn, or null if no bot exists in the team.

==== ETUtil.GetTimeElapsed ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetTimeElapsed();
</syntaxhighlight>

returns time since map start.

==== ETUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamClassDead( team, class );
example: ETUtil.IsTeamClassDead( TEAM.AXIS, CLASS.MEDIC );
</syntaxhighlight>

returns true if all the players of the given class on the given team are dead.

==== ETUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamDead( team );
example: ETUtil.IsTeamDead( TEAM.AXIS );
</syntaxhighlight>

returns true if all players on the given team are dead.

==== ETUtil.LosingChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.LosingChat(team);
example: ETUtil.LosingChat( TEAM.AXIS );
</syntaxhighlight>

See [[Talking_bots]] page

==== ETUtil.SelectWeapon ====

This function does not work since version 0.82. Now you have to use [[Utility_Functions#WeaponTable|WeaponTable.SetWeaponAvailability]].

==== ETUtil.SetAimModeForMount====

<syntaxhighlight lang="java">
syntax: ETUtil.SetAimModeForMount(goalName, aimType);
example: ETUtil.SetAimModeForMount("MOUNT_ship", Vec3(-340, 1530, 90));</syntaxhighlight>

Sets AimMode property of MOUNT goal. Valid values are "velocity", "opposite", "random" or Vector3.

==== ETUtil.SetCabinets ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetCabinets();
</syntaxhighlight>

disables health & ammo cabinets for Medic & FieldOp Classes

==== ETUtil.SetExcludeIndexes ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetExcludeIndexes( goal, { offset } );
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", { 4, 5, 6 } ); // Disable offset 4, 5 & 6
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", {} ); // Removes Disabled offsets
</syntaxhighlight>

disables vehicle offsets, used when an offset cannot be reached. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SetStartIndex ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetStartIndex(goal, offset);
example: ETUtil.SetStartIndex("ESCORT_tank", 2); // Use Offset 2
example: ETUtil.SetStartIndex("ESCORT_tank", -1); // Random
</syntaxhighlight>

used to make a bot start from a certain vehicle offset in mover goals that have offsets defined. Normally set in OnMapLoad then reset inside a trigger. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SuicideSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.SuicideSpawn( team, spawn, numbots, class);
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, 1, CLASS.ENGINEER ); // 2 bots spawn at spawnpoint 2
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, -1, CLASS.ENGINEER ); // all axis engineer bots spawn at spawnpoint 2
</syntaxhighlight>

used to make bots self kill and change to a new spawn, often used in maps to defend areas when players have sneaked past.

==== ETUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: ETUtil.SwitchWeapon(weapon);
example: ETUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer</syntaxhighlight>

This function is deprecated since version 0.82 because it only kills bot and does not change his weapon.

==== ETUtil.WaitForSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.WaitForSpawn(Team);
example: ETUtil.WaitForSpawn( TEAM.ALLIES );
</syntaxhighlight>

Sleeps until next respawn of the team. Returns 0.15 seconds before respawn.

==== ETUtil.WinningChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.WinningChat(Team);
example: ETUtil.WinningChat( TEAM.ALLIES );
</syntaxhighlight>

See [[Talking_bots]] page

=== RTCWUtil ===
These functions are available only in the Return to Castle Wolfenstein game.

==== RTCWUtil.BotDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.BotDisableCombatCrouch( bot, bool enable );
example: RTCWUtil.BotDisableCombatCrouch( bot, true );
</syntaxhighlight>

used to disable crouching in combat for the given bot

==== RTCWUtil.ChangeClass ====

This function is deprecated. Use Server.MinClassCount.

==== RTCWUtil.ChangeSpawnNoDefenders ====

This function is deprecated. See [[Changing spawns]].

==== RTCWUtil.ClearMainGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearMainGoals();</syntaxhighlight>

This function will deactivate all main goals for both teams.

goals deactivated: PLANT MOUNTMG42 MOVER CHECKPOINT FLAG

==== RTCWUtil.ClearSecondaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearSecondaryGoals();</syntaxhighlight>

This function will deactivate all secondary goals for both teams.

goals deactivated: ARTILLERY REPAIR

==== RTCWUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.CountClass( team, class );
example: RTCWUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== RTCWUtil.CountTeam ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.DisableGoal(goalname, <optional true>);
example: RTCWUtil.DisableGoal("FLAG_someflag");
</syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== RTCWUtil.IsPlantGoalAvailable ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsPlantGoalAvailable();
example: RTCWUtil.IsPlantGoalAvailable();
</syntaxhighlight>

returns true if there is a plant goal available

==== RTCWUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamClassDead( team, class );
example: RTCWUtil.IsTeamClassDead( TEAM.AXIS, CLASS.ENGINEER )
</syntaxhighlight>

returns true if there are no living players or bots of a given class on the given team

==== RTCWUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamDead( team, minbots );
example: RTCWUtil.IsTeamDead( TEAM.AXIS, 2 );
</syntaxhighlight>

returns true if the number of living players on the given team is less than minbots.

note: minbots is optional as it defaults to 1

==== RTCWUtil.KillEntities ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.KillEntities( table or int );
example: RTCWUtil.KillEntities( 123 );
example: RTCWUtil.KillEntities( {123, 124} );
</syntaxhighlight>

used to remove entities from the map. typically called from OnMapLoad

==== RTCWUtil.NoSnipe ====

<syntaxhighlight lang="java">
syntax: syntax: RTCWUtil.NoSnipe(bot);</syntaxhighlight>
soldier bots will not choose a mauser when selecting a weapon

note: this is typically called in OnBotJoin

==== RTCWUtil.SelectSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in OnBotJoin to have soldiers choose between given weapons
example: RTCWUtil.SelectSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SelectSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser</syntaxhighlight>

==== RTCWUtil.SelectWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectWeapon(bot, weapon, isFog);
example: RTCWUtil.SelectWeapon(bot, WEAPON.MAUSER);

</syntaxhighlight>

the given bot will switch to the given weapon if it is the correct class for the weapon

note: typically used in OnBotJoin to have soldiers choose a specific weapon
the isFog parameter is optional and disables extra view distance given to snipers

==== RTCWUtil.SetPrimaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetPrimaryGoals(priority);
</syntaxhighlight>

used for setting priorities of common goals.

note: this is typically called in OnMapLoad and effects the following goals (in order of priority):
CAPPOINT FLAGRETURN PLANT CHECKPOINT FLAG

==== RTCWUtil.SetSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, class, suicide, persistant);
sets all classes on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.SetTeamSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, suicide, persistant);
sets all bots on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.StopSniping ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.StopSniping();</syntaxhighlight>
all bots currently using a sniper weapon will switch to a different weapon

note: this is typically called inside trigger functions

==== RTCWUtil.SwitchSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in triggers to have soldiers choose between given weapons
example: RTCWUtil.SwitchSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SwitchSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser
</syntaxhighlight>

==== RTCWUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchWeapon(weapon);
all qualifying bots will switch to the given weapon

example: RTCWUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer
note: typically used in trigger functions</syntaxhighlight>

==== RTCWUtil.TeamDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.TeamDisableCombatCrouch( team );
example: RTCWUtil.TeamDisableCombatCrouch( TEAM.AXIS );
</syntaxhighlight>

disables combat crouching for the given team

==== RTCWUtil.ToggleFlag ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ToggleFlag( goal, time in seconds );
example: thread(RTCWUtil.ToggleFlag, "CHECKPOINT.someFlag", 300);
</syntaxhighlight>

used in dual objective maps like mp_depot to set availability of the checkpoint goal for the opposite team in the given interval
note: this should be called as a gm thread.

=== WeaponTable ===

==== WeaponTable.ListWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.ListWeaponAvailability();
</syntaxhighlight>

prints current availability of all weapons

==== WeaponTable.SetWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponAvailability( class, weapon, <true/false>);
example: WeaponTable.SetWeaponAvailability( CLASS.SOLDIER, WEAPON.FLAMETHROWER, false );</syntaxhighlight>

enables or disables specified weapon for class. The weapon parameter can be table.
The class parameter can be null to set availability for all classes.

note: allied PANZERFAUST is automatically converted to BAZOOKA or LAW in Noquarter or ETnam

note: bots select random available weapon every spawn (in limbo)

==== WeaponTable.SetWeaponTeamAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponTeamAvailability( team, class, weapon, <true/false>);
example: WeaponTable.SetWeaponTeamAvailability( TEAM.AXIS, CLASS.ENGINEER, WEAPON.KAR98, false );</syntaxhighlight>

enables or disables weapon for team and class.

==== WeaponTable.Shotgun ====

The Shotgun property has value WEAPON.SHOTGUN, WEAPON.ITHACA, WEAPON.M97 or null.

Utility Functions

2025-05-25T17:07:46Z

Palota: /* ETUtil.SelectWeapon */

{{process header
| title = Utility Functions
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

{{TOCright}}

=== Util ===

==== Util.AddUsePoint ====

<syntaxhighlight lang="java">
syntax: Util.AddUsePoint(goalname, <Vector3 or table>);
example: Util.AddUsePoint("PLANT_wall",{Vec3(12,34,5),Vec3(23,5,67)});</syntaxhighlight>

used to add use points for a goal at given positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AddUseWp ====

<syntaxhighlight lang="java">
syntax: Util.AddUseWp(goalname, <waypointname or table>);
example: Util.AddUseWp( "somegoalname", "somewaypointname" );</syntaxhighlight>

used to add use points for a goal at given waypoints positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AliveCount ====

<syntaxhighlight lang="java">
syntax: Util.AliveCount( team, class );
example: Util.AliveCount( TEAM.AXIS, CLASS.MEDIC ); </syntaxhighlight>

returns the number of bots alive on a team with a given class

==== Util.BotChat ====

<syntaxhighlight lang="java">
syntax: Util.BotChat(Team, msgType, Msg, NumBots);
example: Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_CHEER, 2);
</syntaxhighlight>

See [[Talking_bots]] page

==== Util.BotHasAnyRole ====

This function is deprecated. Use [[Bot#HasRole|HasRole]]

==== Util.CanBotSnipe ====

<syntaxhighlight lang="java">
syntax: Util.CanBotSnipe(bot);
example: if ( Util.CanBotSnipe(bot) ) {
</syntaxhighlight>

returns true if bot has a sniper weapon.

==== Util.CappointForFlag ====
<syntaxhighlight lang="java">
syntax: Util.CappointForFlag( flag_goalname, cappoint_goalname );
example: Util.CappointForFlag( "FLAG_axis_gold", "CAPPOINT_Truck" );
</syntaxhighlight>

used if there are multiple active cappoint goals. It should be called from _Taken triggers.

==== Util.ChangeBotSpawn ====
This function is deprecated. See [[Changing spawns]].

==== Util.ChangeCrucialClassForRole ====
<syntaxhighlight lang="java">
syntax: Util.ChangeCrucialClassForRole ( team, role, class );
example: Util.ChangeCrucialClassForRole(TEAM.AXIS, ROLE.DEFENDER1, CLASS.COVERTOPS);
</syntaxhighlight>

Sets new crucialClass in the Map.Roles table.

==== Util.ChangeSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.ChangeSpawnForRole ====

<syntaxhighlight lang="java">
syntax: Util.ChangeSpawnForRole( <team>, <role>, <spawnpoint> );
example: Util.ChangeSpawnForRole(TEAM.ALLIES, ROLE.ATTACKER, 1);
</syntaxhighlight>

Set the spawn point for all bots on the given team with the given role

see also: [[Roles]] Page

==== Util.ChangeToSniperWeapons ====

<syntaxhighlight lang="java">
syntax: Util.ChangeToSniperWeapons( bot, <optional viewDistance> );
example: Util.ChangeToSniperWeapons(bot);
</syntaxhighlight>

called from OnBotJoin on sniper maps.

see also: [[Sniper_and_Panzer_maps]]

==== Util.ClearRoleForGoals ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.ClearRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.ClearRoleForGroup( group, <role or table> );
example: Util.ClearRoleForGroup( "someGroup", ROLE.DEFENDER );
</syntaxhighlight>

used to remove roles from a given group of goals

see also: [[Roles]] Page

==== Util.ClearRoleForTable ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.DisableGoal ====

<syntaxhighlight lang="java">
syntax: Util.DisableGoal(goalname, <optional true>);
example: Util.DisableGoal("FLAG_someflag"); </syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== Util.DisableGroup ====

<syntaxhighlight lang="java">
syntax: Util.DisableGroup(groupname, team);
example: Util.DisableGroup( "somegroupname", TEAM.ALLIES );</syntaxhighlight>

used to disable a set of goals in the given group for a given team

==== Util.EnableGoal ====

<syntaxhighlight lang="java">
syntax: Util.EnableGoal(goalname);
example: Util.EnableGoal("FLAG_someflag");</syntaxhighlight>

enables the goal for both teams.

==== Util.EnableGroup ====

<syntaxhighlight lang="java">
syntax: Util.EnableGroup(groupname, team);
example: Util.EnableGroup( "somegroupname", TEAM.SOMETEAM );</syntaxhighlight>

used to enable a set of goals in the given group for a given team

==== Util.ExcludeClass ====

<syntaxhighlight lang="java">
syntax: Util.ExcludeClass( goalname, team, class1, class2, class3, class4 );
example: Util.ExcludeClass( "DEFEND_somegoal.*", TEAM.AXIS, CLASS.MEDIC );
example: Util.ExcludeClass( "MOUNTMG42_.*", TEAM.ALLIES, CLASS.FIELDOPS, CLASS.ENGINEER );
</syntaxhighlight>

limit given goal usage to specific classes by team. class2, class3, and class4 are optional.

==== Util.ForceRouting ====

<syntaxhighlight lang="java">
syntax: Util.ForceRouting(goalName, true/false);
example: Util.ForceRouting( "BUILD_Tank", true );</syntaxhighlight>

disables BUILD goal offsets and enables routes to the goal. You should set ForceRouting to true only when a vehicle is at known position (in OnMapLoad or at tank barriers). You must set it to false when a vehicle is repaired.

==== Util.GetEntHealth ====

<syntaxhighlight lang="java">
syntax: Util.GetEntHealth(entity);
example: health = Util.GetEntHealth(this.TargetEntity);</syntaxhighlight>

returns entity health.

==== Util.GetGroup ====

<syntaxhighlight lang="java">
syntax: Util.GetGroup(groupname);
example: Util.GetGroup("somegroupname");</syntaxhighlight>

this function will return a table of goals belonging to the given group name

==== Util.GetRandomFromTable ====

<syntaxhighlight lang="java">
syntax: Util.GetRandomFromTable( tbl );
example: index = Util.GetRandomFromTable( someTable );
</syntaxhighlight>

used to get a randomly selected index from a given table. Returns -1 if invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GetRandomTableValue====

<syntaxhighlight lang="java">
syntax: Util.GetRandomTableValue( tbl );
example: value = Util.GetRandomTableValue( someTable );
</syntaxhighlight>

used to get a randomly selected value from a given table. Returns null if the table is empty or invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GoalTable ====

<syntaxhighlight lang="java">
syntax: Util.GoalTable( <optional expression>, <optional teamId> );
example: goals = Util.GoalTable("PLANT_Back_Door");
example: goals = Util.GoalTable("FLAG.*", TEAM.AXIS);
</syntaxhighlight>

returns table of map goals that match a regular expression.

==== Util.IgnoreTargetGoal ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IgnoreTargetGoalTable ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IsBot ====

<syntaxhighlight lang="java">
syntax: Util.IsBot(entity);
example: bot = Util.IsBot(ent);
</syntaxhighlight>

returns Bot object from entity or null if entity is not a bot. Usually used in region triggers if the TriggerOnClass is CLASS.ANYPLAYER.

==== Util.LimitToClass ====

<syntaxhighlight lang="java">
syntax: Util.LimitToClass(goalname, team, class1, class2, class3, class4);
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER); //only soldiers on the allied team
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER, CLASS.MEDIC); //only soldiers and medics</syntaxhighlight>

used to limit specific goals to a specific class or classes

==== Util.LimitToTeam ====

<syntaxhighlight lang="java">
syntax: Util.LimitToTeam(team, goal);
example: Util.LimitToTeam(TEAM.AXIS, "SWITCH_gate_depot");
</syntaxhighlight>

limits goals to a certain team without the need to disable for 1 team

==== Util.MapDebugPrint ====

<syntaxhighlight lang="java">
syntax: Util.MapDebugPrint( "Text", <optional message only> );
example: Util.MapDebugPrint( "East_Barrier_Destroyed" );
example: Util.MapDebugPrint( "East_Barrier_Destroyed", true ); // only print the message
</syntaxhighlight>

used to print text & list of available goals in the console when in debug mode

see also: [[Debugging_tips]]

==== Util.OnTriggerPosition ====

<syntaxhighlight lang="java">
syntax: Util.OnTriggerPosition( goalname, wpname or position, tolerance, wpfunction );
example: Util.OnTriggerPosition( "MOVER_train1", "depotyard", 200.0, Map.tug_depotyard );</syntaxhighlight>

note: used for setting up positional triggers for movers.

==== Util.RandomBotSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RandomSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RemoveGoal ====

<syntaxhighlight lang="java">
syntax: Util.RemoveGoal( goalnames );
example: Util.RemoveGoal( "MOVER_truck" );</syntaxhighlight>

removes the goals from the map goal table. It should only be used for invalid goals which are badly detected by the game.

==== Util.Routes ====

<syntaxhighlight lang="java">
syntax: Util.Routes( <table> );
example: Util.Routes(MapRoutes);</syntaxhighlight>

initializes routes

see also: [[Template:Baserouting|Routing]]

==== Util.SetGoalOffset ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalOffset( x, y, z, GoalName );
info x = North, -x = South y = East, -y = West, z = Up, -z =Down
example: Util.SetGoalOffset( 0, -20, -10, "MOUNTMG42_boat" );</syntaxhighlight>

the x y and z parameters are added to the origin of the goal to move the location of where bots will look for the goal. It is sometimes needed for MOUNTMG42 and REPAIRMG42 goals because some mg42 cannot be mounted or repaired if it's position is not corrected.

==== Util.SetGoalPosition ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalPosition( x, y, z, GoalName );
example: Util.SetGoalPosition( 4534, 2168, -199, "BUILD_construct" )</syntaxhighlight>

used to give the goal a new origin.

note: it's usually much better to use function Util.AddUsePoint to set position of BUILD or PLANT goals.

note: console command "/bot mypos" prints your body position, command "/viewpos" prints your eye position rounded to integer.

==== Util.SetGoalRange ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalRange( goalNames, distance );
example: Util.SetGoalRange("GRENADE_tower.*", 800);</syntaxhighlight>

sets the range for map goals. The goals will not be available for bots that are out of range. Default range for all goals is 0 which means unlimited.

==== Util.SetGroup ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetGroupForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetMaxUsers ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsers( botnum, goal );
example: Util.SetMaxUsers( 1, "ATTACK_.*" );
</syntaxhighlight>

used to limit number of bots using a particular goal(s). this function sets both In_Use and In_Progress

==== Util.SetMaxUsersInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInProgress( Users, GoalNames );
example: Util.SetMaxUsersInProgress( 15, "CHECKPOINT.*" );</syntaxhighlight>

used to set the maximum number of bots going for a particular goal(s).

==== Util.SetMaxUsersInUse ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInUse( Users, GoalNames );
example: Util.SetMaxUsersInUse( 1, "MOUNT_.*" );
</syntaxhighlight>

used to set the maximum number of bots using a particular goal(s).

==== Util.SetPercentInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetPercentInProgress(%, goal);
example: Util.SetPercentInProgress(70, "FLAG_docs");
</syntaxhighlight>

sets a percentage of bots to use a particular goal(s).

note: number of bots is calculated only once when this function is called. It does not work well after bots are added or kicked.

==== Util.SetPositionGoal ====

<syntaxhighlight lang="java">
syntax: Util.SetPositionGoal( goalname1, goalname2 );
example: Util.SetPositionGoal( "BUILD_Tank", "MOVER_tank" );</syntaxhighlight>

sets the origin of one goal to match the origin of another. This function was used in Omni-bot 0.66. Current Omni-bot version automatically sets positions of BUILD goals.

==== Util.SetRoleForGoals ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

==== Util.SetRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.SetRoleForGroup( <goal group>, <role or table> );
example: Util.SetRoleForGroup( "myGroup", ROLE.DEFENDER );
</syntaxhighlight>

sets the given roles for the given group of goals.

==== Util.SetRoleForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

see also: [[Roles]] Page

==== Util.ShowGroup ====

<syntaxhighlight lang="java">
syntax: Util.ShowGroup(groupname);
example: Util.ShowGroup("somegroupname");</syntaxhighlight>

this function will list all goals in the given group in the console.

==== Util.UpdateSwitchData ====

This function is deprecated. Use [[Switch_Goal]]

==== Util.WpNameInfo ====

<syntaxhighlight lang="java">
syntax: Util.WpNameInfo(waypointName);
example: wpInfo = Util.WpNameInfo("rNadeHall");</syntaxhighlight>

finds waypoint by name and returns table which contains position, facing, radius, flags, property. It is often used in paththrough navigation.

=== ETUtil ===
These functions are available only in the Enemy Territory game.

==== ETUtil.ChangeToPanzer ====

<syntaxhighlight lang="java">
syntax: ETUtil.ChangeToPanzer( bot );</syntaxhighlight>

called from OnBotJoin on panzer maps.

see also: [[Sniper_and_Panzer_maps]]

==== ETUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: ETUtil.CountClass( team, class );
example: ETUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== ETUtil.GetReinforceTime ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetReinforceTime(TEAM.AXIS);
</syntaxhighlight>

returns time to next respawn, or null if no bot exists in the team.

==== ETUtil.GetTimeElapsed ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetTimeElapsed();
</syntaxhighlight>

returns time since map start.

==== ETUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamClassDead( team, class );
example: ETUtil.IsTeamClassDead( TEAM.AXIS, CLASS.MEDIC );
</syntaxhighlight>

returns true if all the players of the given class on the given team are dead.

==== ETUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamDead( team );
example: ETUtil.IsTeamDead( TEAM.AXIS );
</syntaxhighlight>

returns true if all players on the given team are dead.

==== ETUtil.LosingChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.LosingChat(team);
example: ETUtil.LosingChat( TEAM.AXIS );
</syntaxhighlight>

See [[Talking_bots]] page

==== ETUtil.SelectWeapon ====

This function does not work since version 0.82. Now you have to use [[Utility_Functions#WeaponTable|WeaponTable.SetWeaponAvailability]].

==== ETUtil.SetAimModeForMount====

<syntaxhighlight lang="java">
syntax: ETUtil.SetAimModeForMount(goalName, aimType);
example: ETUtil.SetAimModeForMount("MOUNT_ship", Vec3(-340, 1530, 90));</syntaxhighlight>

Sets AimMode property of MOUNT goal. Valid values are "velocity", "opposite", "random" or Vector3.

==== ETUtil.SetCabinets ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetCabinets();
</syntaxhighlight>

disables health & ammo cabinets for Medic & FieldOp Classes

==== ETUtil.SetExcludeIndexes ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetExcludeIndexes( goal, { offset } );
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", { 4, 5, 6 } ); // Disable offset 4, 5 & 6
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", {} ); // Removes Disabled offsets
</syntaxhighlight>

disables vehicle offsets, used when an offset cannot be reached. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SetStartIndex ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetStartIndex(goal, offset);
example: ETUtil.SetStartIndex("ESCORT_tank", 2); // Use Offset 2
example: ETUtil.SetStartIndex("ESCORT_tank", -1); // Random
</syntaxhighlight>

used to make a bot start from a certain vehicle offset in mover goals that have offsets defined. Normally set in OnMapLoad then reset inside a trigger. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SuicideSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.SuicideSpawn( team, spawn, numbots, class);
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, 1, CLASS.ENGINEER ); // 2 bots spawn at spawnpoint 2
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, -1, CLASS.ENGINEER ); // all axis engineer bots spawn at spawnpoint 2
</syntaxhighlight>

used to make bots self kill and change to a new spawn, often used in maps to defend areas when players have sneaked past.

==== ETUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: ETUtil.SwitchWeapon(weapon);
example: ETUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer</syntaxhighlight>

This function is deprecated since version 0.82 because it only kills bot and does not change his weapon.

==== ETUtil.WinningChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.WinningChat(Team);
example: ETUtil.WinningChat( TEAM.ALLIES );
</syntaxhighlight>

See [[Talking_bots]] page

=== RTCWUtil ===
These functions are available only in the Return to Castle Wolfenstein game.

==== RTCWUtil.BotDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.BotDisableCombatCrouch( bot, bool enable );
example: RTCWUtil.BotDisableCombatCrouch( bot, true );
</syntaxhighlight>

used to disable crouching in combat for the given bot

==== RTCWUtil.ChangeClass ====

This function is deprecated. Use Server.MinClassCount.

==== RTCWUtil.ChangeSpawnNoDefenders ====

This function is deprecated. See [[Changing spawns]].

==== RTCWUtil.ClearMainGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearMainGoals();</syntaxhighlight>

This function will deactivate all main goals for both teams.

goals deactivated: PLANT MOUNTMG42 MOVER CHECKPOINT FLAG

==== RTCWUtil.ClearSecondaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearSecondaryGoals();</syntaxhighlight>

This function will deactivate all secondary goals for both teams.

goals deactivated: ARTILLERY REPAIR

==== RTCWUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.CountClass( team, class );
example: RTCWUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== RTCWUtil.CountTeam ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.DisableGoal(goalname, <optional true>);
example: RTCWUtil.DisableGoal("FLAG_someflag");
</syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== RTCWUtil.IsPlantGoalAvailable ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsPlantGoalAvailable();
example: RTCWUtil.IsPlantGoalAvailable();
</syntaxhighlight>

returns true if there is a plant goal available

==== RTCWUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamClassDead( team, class );
example: RTCWUtil.IsTeamClassDead( TEAM.AXIS, CLASS.ENGINEER )
</syntaxhighlight>

returns true if there are no living players or bots of a given class on the given team

==== RTCWUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamDead( team, minbots );
example: RTCWUtil.IsTeamDead( TEAM.AXIS, 2 );
</syntaxhighlight>

returns true if the number of living players on the given team is less than minbots.

note: minbots is optional as it defaults to 1

==== RTCWUtil.KillEntities ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.KillEntities( table or int );
example: RTCWUtil.KillEntities( 123 );
example: RTCWUtil.KillEntities( {123, 124} );
</syntaxhighlight>

used to remove entities from the map. typically called from OnMapLoad

==== RTCWUtil.NoSnipe ====

<syntaxhighlight lang="java">
syntax: syntax: RTCWUtil.NoSnipe(bot);</syntaxhighlight>
soldier bots will not choose a mauser when selecting a weapon

note: this is typically called in OnBotJoin

==== RTCWUtil.SelectSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in OnBotJoin to have soldiers choose between given weapons
example: RTCWUtil.SelectSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SelectSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser</syntaxhighlight>

==== RTCWUtil.SelectWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectWeapon(bot, weapon, isFog);
example: RTCWUtil.SelectWeapon(bot, WEAPON.MAUSER);

</syntaxhighlight>

the given bot will switch to the given weapon if it is the correct class for the weapon

note: typically used in OnBotJoin to have soldiers choose a specific weapon
the isFog parameter is optional and disables extra view distance given to snipers

==== RTCWUtil.SetPrimaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetPrimaryGoals(priority);
</syntaxhighlight>

used for setting priorities of common goals.

note: this is typically called in OnMapLoad and effects the following goals (in order of priority):
CAPPOINT FLAGRETURN PLANT CHECKPOINT FLAG

==== RTCWUtil.SetSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, class, suicide, persistant);
sets all classes on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.SetTeamSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, suicide, persistant);
sets all bots on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.StopSniping ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.StopSniping();</syntaxhighlight>
all bots currently using a sniper weapon will switch to a different weapon

note: this is typically called inside trigger functions

==== RTCWUtil.SwitchSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in triggers to have soldiers choose between given weapons
example: RTCWUtil.SwitchSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SwitchSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser
</syntaxhighlight>

==== RTCWUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchWeapon(weapon);
all qualifying bots will switch to the given weapon

example: RTCWUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer
note: typically used in trigger functions</syntaxhighlight>

==== RTCWUtil.TeamDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.TeamDisableCombatCrouch( team );
example: RTCWUtil.TeamDisableCombatCrouch( TEAM.AXIS );
</syntaxhighlight>

disables combat crouching for the given team

==== RTCWUtil.ToggleFlag ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ToggleFlag( goal, time in seconds );
example: thread(RTCWUtil.ToggleFlag, "CHECKPOINT.someFlag", 300);
</syntaxhighlight>

used in dual objective maps like mp_depot to set availability of the checkpoint goal for the opposite team in the given interval
note: this should be called as a gm thread.

=== WeaponTable ===

==== WeaponTable.ListWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.ListWeaponAvailability();
</syntaxhighlight>

prints current availability of all weapons

==== WeaponTable.SetWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponAvailability( class, weapon, <true/false>);
example: WeaponTable.SetWeaponAvailability( CLASS.SOLDIER, WEAPON.FLAMETHROWER, false );</syntaxhighlight>

enables or disables specified weapon for class. The weapon parameter can be table.
The class parameter can be null to set availability for all classes.

note: allied PANZERFAUST is automatically converted to BAZOOKA or LAW in Noquarter or ETnam

note: bots select random available weapon every spawn (in limbo)

==== WeaponTable.SetWeaponTeamAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponTeamAvailability( team, class, weapon, <true/false>);
example: WeaponTable.SetWeaponTeamAvailability( TEAM.AXIS, CLASS.ENGINEER, WEAPON.KAR98, false );</syntaxhighlight>

enables or disables weapon for team and class.

==== WeaponTable.Shotgun ====

The Shotgun property has value WEAPON.SHOTGUN, WEAPON.ITHACA, WEAPON.M97 or null.

Utility Functions

2025-05-25T16:55:42Z

Palota: /* ETUtil.GetReinforceTime */

{{process header
| title = Utility Functions
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

{{TOCright}}

=== Util ===

==== Util.AddUsePoint ====

<syntaxhighlight lang="java">
syntax: Util.AddUsePoint(goalname, <Vector3 or table>);
example: Util.AddUsePoint("PLANT_wall",{Vec3(12,34,5),Vec3(23,5,67)});</syntaxhighlight>

used to add use points for a goal at given positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AddUseWp ====

<syntaxhighlight lang="java">
syntax: Util.AddUseWp(goalname, <waypointname or table>);
example: Util.AddUseWp( "somegoalname", "somewaypointname" );</syntaxhighlight>

used to add use points for a goal at given waypoints positions. Goals can have multiple use points. You must set RandomUsePoint property to 1, otherwise bots will always choose the nearest use point.

==== Util.AliveCount ====

<syntaxhighlight lang="java">
syntax: Util.AliveCount( team, class );
example: Util.AliveCount( TEAM.AXIS, CLASS.MEDIC ); </syntaxhighlight>

returns the number of bots alive on a team with a given class

==== Util.BotChat ====

<syntaxhighlight lang="java">
syntax: Util.BotChat(Team, msgType, Msg, NumBots);
example: Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_CHEER, 2);
</syntaxhighlight>

See [[Talking_bots]] page

==== Util.BotHasAnyRole ====

This function is deprecated. Use [[Bot#HasRole|HasRole]]

==== Util.CanBotSnipe ====

<syntaxhighlight lang="java">
syntax: Util.CanBotSnipe(bot);
example: if ( Util.CanBotSnipe(bot) ) {
</syntaxhighlight>

returns true if bot has a sniper weapon.

==== Util.CappointForFlag ====
<syntaxhighlight lang="java">
syntax: Util.CappointForFlag( flag_goalname, cappoint_goalname );
example: Util.CappointForFlag( "FLAG_axis_gold", "CAPPOINT_Truck" );
</syntaxhighlight>

used if there are multiple active cappoint goals. It should be called from _Taken triggers.

==== Util.ChangeBotSpawn ====
This function is deprecated. See [[Changing spawns]].

==== Util.ChangeCrucialClassForRole ====
<syntaxhighlight lang="java">
syntax: Util.ChangeCrucialClassForRole ( team, role, class );
example: Util.ChangeCrucialClassForRole(TEAM.AXIS, ROLE.DEFENDER1, CLASS.COVERTOPS);
</syntaxhighlight>

Sets new crucialClass in the Map.Roles table.

==== Util.ChangeSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.ChangeSpawnForRole ====

<syntaxhighlight lang="java">
syntax: Util.ChangeSpawnForRole( <team>, <role>, <spawnpoint> );
example: Util.ChangeSpawnForRole(TEAM.ALLIES, ROLE.ATTACKER, 1);
</syntaxhighlight>

Set the spawn point for all bots on the given team with the given role

see also: [[Roles]] Page

==== Util.ChangeToSniperWeapons ====

<syntaxhighlight lang="java">
syntax: Util.ChangeToSniperWeapons( bot, <optional viewDistance> );
example: Util.ChangeToSniperWeapons(bot);
</syntaxhighlight>

called from OnBotJoin on sniper maps.

see also: [[Sniper_and_Panzer_maps]]

==== Util.ClearRoleForGoals ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.ClearRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.ClearRoleForGroup( group, <role or table> );
example: Util.ClearRoleForGroup( "someGroup", ROLE.DEFENDER );
</syntaxhighlight>

used to remove roles from a given group of goals

see also: [[Roles]] Page

==== Util.ClearRoleForTable ====

This function is deprecated. Use [[Bot_Library#ClearGoalRole|ClearGoalRole]]

==== Util.DisableGoal ====

<syntaxhighlight lang="java">
syntax: Util.DisableGoal(goalname, <optional true>);
example: Util.DisableGoal("FLAG_someflag"); </syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== Util.DisableGroup ====

<syntaxhighlight lang="java">
syntax: Util.DisableGroup(groupname, team);
example: Util.DisableGroup( "somegroupname", TEAM.ALLIES );</syntaxhighlight>

used to disable a set of goals in the given group for a given team

==== Util.EnableGoal ====

<syntaxhighlight lang="java">
syntax: Util.EnableGoal(goalname);
example: Util.EnableGoal("FLAG_someflag");</syntaxhighlight>

enables the goal for both teams.

==== Util.EnableGroup ====

<syntaxhighlight lang="java">
syntax: Util.EnableGroup(groupname, team);
example: Util.EnableGroup( "somegroupname", TEAM.SOMETEAM );</syntaxhighlight>

used to enable a set of goals in the given group for a given team

==== Util.ExcludeClass ====

<syntaxhighlight lang="java">
syntax: Util.ExcludeClass( goalname, team, class1, class2, class3, class4 );
example: Util.ExcludeClass( "DEFEND_somegoal.*", TEAM.AXIS, CLASS.MEDIC );
example: Util.ExcludeClass( "MOUNTMG42_.*", TEAM.ALLIES, CLASS.FIELDOPS, CLASS.ENGINEER );
</syntaxhighlight>

limit given goal usage to specific classes by team. class2, class3, and class4 are optional.

==== Util.ForceRouting ====

<syntaxhighlight lang="java">
syntax: Util.ForceRouting(goalName, true/false);
example: Util.ForceRouting( "BUILD_Tank", true );</syntaxhighlight>

disables BUILD goal offsets and enables routes to the goal. You should set ForceRouting to true only when a vehicle is at known position (in OnMapLoad or at tank barriers). You must set it to false when a vehicle is repaired.

==== Util.GetEntHealth ====

<syntaxhighlight lang="java">
syntax: Util.GetEntHealth(entity);
example: health = Util.GetEntHealth(this.TargetEntity);</syntaxhighlight>

returns entity health.

==== Util.GetGroup ====

<syntaxhighlight lang="java">
syntax: Util.GetGroup(groupname);
example: Util.GetGroup("somegroupname");</syntaxhighlight>

this function will return a table of goals belonging to the given group name

==== Util.GetRandomFromTable ====

<syntaxhighlight lang="java">
syntax: Util.GetRandomFromTable( tbl );
example: index = Util.GetRandomFromTable( someTable );
</syntaxhighlight>

used to get a randomly selected index from a given table. Returns -1 if invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GetRandomTableValue====

<syntaxhighlight lang="java">
syntax: Util.GetRandomTableValue( tbl );
example: value = Util.GetRandomTableValue( someTable );
</syntaxhighlight>

used to get a randomly selected value from a given table. Returns null if the table is empty or invalid. Table keys must be integers from 0 to (count - 1).

==== Util.GoalTable ====

<syntaxhighlight lang="java">
syntax: Util.GoalTable( <optional expression>, <optional teamId> );
example: goals = Util.GoalTable("PLANT_Back_Door");
example: goals = Util.GoalTable("FLAG.*", TEAM.AXIS);
</syntaxhighlight>

returns table of map goals that match a regular expression.

==== Util.IgnoreTargetGoal ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IgnoreTargetGoalTable ====

This function is deprecated. Use [[Bot#IgnoreTarget|IgnoreTarget]]

==== Util.IsBot ====

<syntaxhighlight lang="java">
syntax: Util.IsBot(entity);
example: bot = Util.IsBot(ent);
</syntaxhighlight>

returns Bot object from entity or null if entity is not a bot. Usually used in region triggers if the TriggerOnClass is CLASS.ANYPLAYER.

==== Util.LimitToClass ====

<syntaxhighlight lang="java">
syntax: Util.LimitToClass(goalname, team, class1, class2, class3, class4);
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER); //only soldiers on the allied team
example: Util.LimitToClass("CHECKPOINT.*", TEAM.ALLIES, CLASS.SOLDIER, CLASS.MEDIC); //only soldiers and medics</syntaxhighlight>

used to limit specific goals to a specific class or classes

==== Util.LimitToTeam ====

<syntaxhighlight lang="java">
syntax: Util.LimitToTeam(team, goal);
example: Util.LimitToTeam(TEAM.AXIS, "SWITCH_gate_depot");
</syntaxhighlight>

limits goals to a certain team without the need to disable for 1 team

==== Util.MapDebugPrint ====

<syntaxhighlight lang="java">
syntax: Util.MapDebugPrint( "Text", <optional message only> );
example: Util.MapDebugPrint( "East_Barrier_Destroyed" );
example: Util.MapDebugPrint( "East_Barrier_Destroyed", true ); // only print the message
</syntaxhighlight>

used to print text & list of available goals in the console when in debug mode

see also: [[Debugging_tips]]

==== Util.OnTriggerPosition ====

<syntaxhighlight lang="java">
syntax: Util.OnTriggerPosition( goalname, wpname or position, tolerance, wpfunction );
example: Util.OnTriggerPosition( "MOVER_train1", "depotyard", 200.0, Map.tug_depotyard );</syntaxhighlight>

note: used for setting up positional triggers for movers.

==== Util.RandomBotSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RandomSpawn ====

This function is deprecated. See [[Changing spawns]].

==== Util.RemoveGoal ====

<syntaxhighlight lang="java">
syntax: Util.RemoveGoal( goalnames );
example: Util.RemoveGoal( "MOVER_truck" );</syntaxhighlight>

removes the goals from the map goal table. It should only be used for invalid goals which are badly detected by the game.

==== Util.Routes ====

<syntaxhighlight lang="java">
syntax: Util.Routes( <table> );
example: Util.Routes(MapRoutes);</syntaxhighlight>

initializes routes

see also: [[Template:Baserouting|Routing]]

==== Util.SetGoalOffset ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalOffset( x, y, z, GoalName );
info x = North, -x = South y = East, -y = West, z = Up, -z =Down
example: Util.SetGoalOffset( 0, -20, -10, "MOUNTMG42_boat" );</syntaxhighlight>

the x y and z parameters are added to the origin of the goal to move the location of where bots will look for the goal. It is sometimes needed for MOUNTMG42 and REPAIRMG42 goals because some mg42 cannot be mounted or repaired if it's position is not corrected.

==== Util.SetGoalPosition ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalPosition( x, y, z, GoalName );
example: Util.SetGoalPosition( 4534, 2168, -199, "BUILD_construct" )</syntaxhighlight>

used to give the goal a new origin.

note: it's usually much better to use function Util.AddUsePoint to set position of BUILD or PLANT goals.

note: console command "/bot mypos" prints your body position, command "/viewpos" prints your eye position rounded to integer.

==== Util.SetGoalRange ====

<syntaxhighlight lang="java">
syntax: Util.SetGoalRange( goalNames, distance );
example: Util.SetGoalRange("GRENADE_tower.*", 800);</syntaxhighlight>

sets the range for map goals. The goals will not be available for bots that are out of range. Default range for all goals is 0 which means unlimited.

==== Util.SetGroup ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetGroupForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalGroup|SetGoalGroup]]

==== Util.SetMaxUsers ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsers( botnum, goal );
example: Util.SetMaxUsers( 1, "ATTACK_.*" );
</syntaxhighlight>

used to limit number of bots using a particular goal(s). this function sets both In_Use and In_Progress

==== Util.SetMaxUsersInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInProgress( Users, GoalNames );
example: Util.SetMaxUsersInProgress( 15, "CHECKPOINT.*" );</syntaxhighlight>

used to set the maximum number of bots going for a particular goal(s).

==== Util.SetMaxUsersInUse ====

<syntaxhighlight lang="java">
syntax: Util.SetMaxUsersInUse( Users, GoalNames );
example: Util.SetMaxUsersInUse( 1, "MOUNT_.*" );
</syntaxhighlight>

used to set the maximum number of bots using a particular goal(s).

==== Util.SetPercentInProgress ====

<syntaxhighlight lang="java">
syntax: Util.SetPercentInProgress(%, goal);
example: Util.SetPercentInProgress(70, "FLAG_docs");
</syntaxhighlight>

sets a percentage of bots to use a particular goal(s).

note: number of bots is calculated only once when this function is called. It does not work well after bots are added or kicked.

==== Util.SetPositionGoal ====

<syntaxhighlight lang="java">
syntax: Util.SetPositionGoal( goalname1, goalname2 );
example: Util.SetPositionGoal( "BUILD_Tank", "MOVER_tank" );</syntaxhighlight>

sets the origin of one goal to match the origin of another. This function was used in Omni-bot 0.66. Current Omni-bot version automatically sets positions of BUILD goals.

==== Util.SetRoleForGoals ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

==== Util.SetRoleForGroup ====

<syntaxhighlight lang="java">
syntax: Util.SetRoleForGroup( <goal group>, <role or table> );
example: Util.SetRoleForGroup( "myGroup", ROLE.DEFENDER );
</syntaxhighlight>

sets the given roles for the given group of goals.

==== Util.SetRoleForTable ====

This function is deprecated. Use [[Bot_Library#SetGoalRole|SetGoalRole]]

see also: [[Roles]] Page

==== Util.ShowGroup ====

<syntaxhighlight lang="java">
syntax: Util.ShowGroup(groupname);
example: Util.ShowGroup("somegroupname");</syntaxhighlight>

this function will list all goals in the given group in the console.

==== Util.UpdateSwitchData ====

This function is deprecated. Use [[Switch_Goal]]

==== Util.WpNameInfo ====

<syntaxhighlight lang="java">
syntax: Util.WpNameInfo(waypointName);
example: wpInfo = Util.WpNameInfo("rNadeHall");</syntaxhighlight>

finds waypoint by name and returns table which contains position, facing, radius, flags, property. It is often used in paththrough navigation.

=== ETUtil ===
These functions are available only in the Enemy Territory game.

==== ETUtil.ChangeToPanzer ====

<syntaxhighlight lang="java">
syntax: ETUtil.ChangeToPanzer( bot );</syntaxhighlight>

called from OnBotJoin on panzer maps.

see also: [[Sniper_and_Panzer_maps]]

==== ETUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: ETUtil.CountClass( team, class );
example: ETUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== ETUtil.GetReinforceTime ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetReinforceTime(TEAM.AXIS);
</syntaxhighlight>

returns time to next respawn, or null if no bot exists in the team.

==== ETUtil.GetTimeElapsed ====

<syntaxhighlight lang="java">
syntax: ETUtil.GetTimeElapsed();
</syntaxhighlight>

returns time since map start.

==== ETUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamClassDead( team, class );
example: ETUtil.IsTeamClassDead( TEAM.AXIS, CLASS.MEDIC );
</syntaxhighlight>

returns true if all the players of the given class on the given team are dead.

==== ETUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: ETUtil.IsTeamDead( team );
example: ETUtil.IsTeamDead( TEAM.AXIS );
</syntaxhighlight>

returns true if all players on the given team are dead.

==== ETUtil.LosingChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.LosingChat(team);
example: ETUtil.LosingChat( TEAM.AXIS );
</syntaxhighlight>

See [[Talking_bots]] page

==== ETUtil.SelectWeapon ====

<syntaxhighlight lang="java">
syntax: ETUtil.SelectWeapon(bot, weapon);
example: ETUtil.SelectWeapon(bot, WEAPON.PANZERFAUST);</syntaxhighlight>

This function is deprecated since version 0.82 because it only kills bot and does not change his weapon.

==== ETUtil.SetAimModeForMount====

<syntaxhighlight lang="java">
syntax: ETUtil.SetAimModeForMount(goalName, aimType);
example: ETUtil.SetAimModeForMount("MOUNT_ship", Vec3(-340, 1530, 90));</syntaxhighlight>

Sets AimMode property of MOUNT goal. Valid values are "velocity", "opposite", "random" or Vector3.

==== ETUtil.SetCabinets ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetCabinets();
</syntaxhighlight>

disables health & ammo cabinets for Medic & FieldOp Classes

==== ETUtil.SetExcludeIndexes ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetExcludeIndexes( goal, { offset } );
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", { 4, 5, 6 } ); // Disable offset 4, 5 & 6
example: ETUtil.SetExcludeIndexes( "BUILD_Truck", {} ); // Removes Disabled offsets
</syntaxhighlight>

disables vehicle offsets, used when an offset cannot be reached. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SetStartIndex ====

<syntaxhighlight lang="java">
syntax: ETUtil.SetStartIndex(goal, offset);
example: ETUtil.SetStartIndex("ESCORT_tank", 2); // Use Offset 2
example: ETUtil.SetStartIndex("ESCORT_tank", -1); // Random
</syntaxhighlight>

used to make a bot start from a certain vehicle offset in mover goals that have offsets defined. Normally set in OnMapLoad then reset inside a trigger. Used only by goals BUILD, ESCORT, MOUNT, RIDE.

==== ETUtil.SuicideSpawn ====

<syntaxhighlight lang="java">
syntax: ETUtil.SuicideSpawn( team, spawn, numbots, class);
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, 1, CLASS.ENGINEER ); // 2 bots spawn at spawnpoint 2
example: ETUtil.SuicideSpawn( TEAM.AXIS, 2, -1, CLASS.ENGINEER ); // all axis engineer bots spawn at spawnpoint 2
</syntaxhighlight>

used to make bots self kill and change to a new spawn, often used in maps to defend areas when players have sneaked past.

==== ETUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: ETUtil.SwitchWeapon(weapon);
example: ETUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer</syntaxhighlight>

This function is deprecated since version 0.82 because it only kills bot and does not change his weapon.

==== ETUtil.WinningChat ====

<syntaxhighlight lang="java">
syntax: ETUtil.WinningChat(Team);
example: ETUtil.WinningChat( TEAM.ALLIES );
</syntaxhighlight>

See [[Talking_bots]] page

=== RTCWUtil ===
These functions are available only in the Return to Castle Wolfenstein game.

==== RTCWUtil.BotDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.BotDisableCombatCrouch( bot, bool enable );
example: RTCWUtil.BotDisableCombatCrouch( bot, true );
</syntaxhighlight>

used to disable crouching in combat for the given bot

==== RTCWUtil.ChangeClass ====

This function is deprecated. Use Server.MinClassCount.

==== RTCWUtil.ChangeSpawnNoDefenders ====

This function is deprecated. See [[Changing spawns]].

==== RTCWUtil.ClearMainGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearMainGoals();</syntaxhighlight>

This function will deactivate all main goals for both teams.

goals deactivated: PLANT MOUNTMG42 MOVER CHECKPOINT FLAG

==== RTCWUtil.ClearSecondaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ClearSecondaryGoals();</syntaxhighlight>

This function will deactivate all secondary goals for both teams.

goals deactivated: ARTILLERY REPAIR

==== RTCWUtil.CountClass ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.CountClass( team, class );
example: RTCWUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER ); </syntaxhighlight>

can be used to determine if a team has enough of a critical class for the map

==== RTCWUtil.CountTeam ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.DisableGoal(goalname, <optional true>);
example: RTCWUtil.DisableGoal("FLAG_someflag");
</syntaxhighlight>

disables the goal for both teams. the optional true parameter is used to disable all goals except for ROUTE goals.

==== RTCWUtil.IsPlantGoalAvailable ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsPlantGoalAvailable();
example: RTCWUtil.IsPlantGoalAvailable();
</syntaxhighlight>

returns true if there is a plant goal available

==== RTCWUtil.IsTeamClassDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamClassDead( team, class );
example: RTCWUtil.IsTeamClassDead( TEAM.AXIS, CLASS.ENGINEER )
</syntaxhighlight>

returns true if there are no living players or bots of a given class on the given team

==== RTCWUtil.IsTeamDead ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.IsTeamDead( team, minbots );
example: RTCWUtil.IsTeamDead( TEAM.AXIS, 2 );
</syntaxhighlight>

returns true if the number of living players on the given team is less than minbots.

note: minbots is optional as it defaults to 1

==== RTCWUtil.KillEntities ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.KillEntities( table or int );
example: RTCWUtil.KillEntities( 123 );
example: RTCWUtil.KillEntities( {123, 124} );
</syntaxhighlight>

used to remove entities from the map. typically called from OnMapLoad

==== RTCWUtil.NoSnipe ====

<syntaxhighlight lang="java">
syntax: syntax: RTCWUtil.NoSnipe(bot);</syntaxhighlight>
soldier bots will not choose a mauser when selecting a weapon

note: this is typically called in OnBotJoin

==== RTCWUtil.SelectSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in OnBotJoin to have soldiers choose between given weapons
example: RTCWUtil.SelectSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SelectSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser</syntaxhighlight>

==== RTCWUtil.SelectWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SelectWeapon(bot, weapon, isFog);
example: RTCWUtil.SelectWeapon(bot, WEAPON.MAUSER);

</syntaxhighlight>

the given bot will switch to the given weapon if it is the correct class for the weapon

note: typically used in OnBotJoin to have soldiers choose a specific weapon
the isFog parameter is optional and disables extra view distance given to snipers

==== RTCWUtil.SetPrimaryGoals ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetPrimaryGoals(priority);
</syntaxhighlight>

used for setting priorities of common goals.

note: this is typically called in OnMapLoad and effects the following goals (in order of priority):
CAPPOINT FLAGRETURN PLANT CHECKPOINT FLAG

==== RTCWUtil.SetSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, class, suicide, persistant);
sets all classes on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetSuicide(TEAM.ALLIES, CLASS.LIEUTENANT, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.SetTeamSuicide ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SetSuicide(team, suicide, persistant);
sets all bots on the given team so they commit suicide two seconds before the next spawn
the persistant parameter if set will have them do it every spawn until it is turned off ( or round ends)

example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 1, 1); //commit suicide 2 seconds before every spawn
example: RTCWUtil.SetTeamSuicide(TEAM.ALLIES, 0, 0); //disable the suicide flag for them</syntaxhighlight>

==== RTCWUtil.StopSniping ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.StopSniping();</syntaxhighlight>
all bots currently using a sniper weapon will switch to a different weapon

note: this is typically called inside trigger functions

==== RTCWUtil.SwitchSoldierWeapons ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchSoldierWeapons(team, bot, weap1, weap2, weap3);
soldiers will only select weapons passed in as parameters

note: typically used in triggers to have soldiers choose between given weapons
example: RTCWUtil.SwitchSoldierWeapons(TEAM.AXIS, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //axis soldiers randomly select panzer or mauser
example: RTCWUtil.SwitchSoldierWeapons(0, bot, WEAPON.MAUSER, WEAPON.PANZERFAUST); //all soldiers randomly select panzer or mauser
</syntaxhighlight>

==== RTCWUtil.SwitchWeapon ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.SwitchWeapon(weapon);
all qualifying bots will switch to the given weapon

example: RTCWUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer
note: typically used in trigger functions</syntaxhighlight>

==== RTCWUtil.TeamDisableCombatCrouch ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.TeamDisableCombatCrouch( team );
example: RTCWUtil.TeamDisableCombatCrouch( TEAM.AXIS );
</syntaxhighlight>

disables combat crouching for the given team

==== RTCWUtil.ToggleFlag ====

<syntaxhighlight lang="java">
syntax: RTCWUtil.ToggleFlag( goal, time in seconds );
example: thread(RTCWUtil.ToggleFlag, "CHECKPOINT.someFlag", 300);
</syntaxhighlight>

used in dual objective maps like mp_depot to set availability of the checkpoint goal for the opposite team in the given interval
note: this should be called as a gm thread.

=== WeaponTable ===

==== WeaponTable.ListWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.ListWeaponAvailability();
</syntaxhighlight>

prints current availability of all weapons

==== WeaponTable.SetWeaponAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponAvailability( class, weapon, <true/false>);
example: WeaponTable.SetWeaponAvailability( CLASS.SOLDIER, WEAPON.FLAMETHROWER, false );</syntaxhighlight>

enables or disables specified weapon for class. The weapon parameter can be table.
The class parameter can be null to set availability for all classes.

note: allied PANZERFAUST is automatically converted to BAZOOKA or LAW in Noquarter or ETnam

note: bots select random available weapon every spawn (in limbo)

==== WeaponTable.SetWeaponTeamAvailability ====

<syntaxhighlight lang="java">
syntax: WeaponTable.SetWeaponTeamAvailability( team, class, weapon, <true/false>);
example: WeaponTable.SetWeaponTeamAvailability( TEAM.AXIS, CLASS.ENGINEER, WEAPON.KAR98, false );</syntaxhighlight>

enables or disables weapon for team and class.

==== WeaponTable.Shotgun ====

The Shotgun property has value WEAPON.SHOTGUN, WEAPON.ITHACA, WEAPON.M97 or null.

ScriptGoal

2025-05-25T16:51:04Z

Palota: /* AlwaysRecieveEvents */

{{process header
| title = Script Goal
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
[[Category:ET|Script Goals]]
[[Category:Doom 3|Script Goals]]
[[Category:Quake 4|Script Goals]]
[[Category:RTCW|Script Goals]]

==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]]

<syntaxhighlight lang="java">this.Name = "MyGoalName";</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Parent = "HighLevel";</syntaxhighlight>

===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]]

<syntaxhighlight lang="java">this.Disable = true;</syntaxhighlight>

===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.

Since version 0.92 events are not sent to bots with wrong class if LimitToClass was set.

<syntaxhighlight lang="java">this.AlwaysRecieveEvents = true;</syntaxhighlight>

===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 [[ScriptGoal#AlwaysRecieveEvents| AlwaysRecieveEvents]], which will allow goals to receive events even when not active.
<syntaxhighlight lang="java">
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) );
};</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Bot.Say("Wassup");</syntaxhighlight>

===Priority===
Priority is a property rather than a return value of [[ScriptGoal#GetPriority| GetPriority]] in order to support the useful threading nature of script goals. It is possible to completely leave out a [[ScriptGoal#GetPriority| 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.

<syntaxhighlight lang="java">this.Priority = 1;</syntaxhighlight>

===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.
<syntaxhighlight lang="java">
this.Commands["command_name"] = {
Func = function( _params )
{
},
Help = { "description" },
};
</syntaxhighlight>

==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:''' <syntaxhighlight lang="java">
this.Initialize() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.OnSpawn() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.GetPriority() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.Enter() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.Exit() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]]
----
===Update===
This function is the meat of a script goal. Once a goal is chosen to run, and [[ScriptGoal#Enter| Enter]] is called, the Update function begins getting called at frequent regular intervals. The state stays active until another goal overrides it, or until [[ScriptGoal#Finished| Finished]] is called, after which the [[ScriptGoal#Exit| Exit]] function is called.

'''Example:''' <syntaxhighlight lang="java">
this.Update() = function()
{
// do stuff
this.Finished(); // when we're done running
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]], [[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.OnPathThrough = function(data)
{
navigation = Map.Navigation[data];
if(navigation)
{
this.CurrentNavigation = data;
return true;
}
this.CurrentNavigation = null;
return false;
};
</syntaxhighlight>

==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
{| align="center" border="1"
!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)
|-
|mapgoalavailable
|No
|MapGoal object or name
|}

=====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
<syntaxhighlight lang="java">
this.AddFinishCriteria(this.TargetEntity,"not hasentflag",ENTFLAG.DEAD); // as soon as the entity does not have the dead flag
</syntaxhighlight>

'''Returns:''' true if criteria was created, false if not

'''Example:''' <syntaxhighlight lang="java">
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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.Finished();</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
//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
};</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToClass(CLASS.MEDIC);
this.LimitToClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoClass(CLASS.MEDIC);
this.LimitToNoClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTeam(TEAM.BLUE);
this.LimitToTeam(TEAM.BLUE, TEAM.RED);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToEntityFlag(ENTFLAG.INWATER);
this.LimitToEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoEntityFlag(ENTFLAG.INWATER);
this.LimitToNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE); </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function takes no parameters.
this.LimitToNoTarget(); </syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToWeapon(WEAPON.MOBILE_MG42);
this.LimitToWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// 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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetTeam(TEAM.RED); // don't run unless our target is on red team</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42);
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.LimitToRole(ROLE.DEFENDER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.GetPriority = function()
{
if(this.IsActive())
{
return 1.0;
}
else
{
// do some other check
}
}; </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
wpinfo = table();
wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
if( this.Goto(wpinfo.position, wpinfo.radius) == EVENT.PATH_SUCCESS )
{
print("Made it!");
}</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
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!");
}</syntaxhighlight>

----

===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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathSucceed())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathFail())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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 - LookAround
* Priority.Low - CAMP, ESCORT, RIDE, MOUNT, ...
* 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:''' <syntaxhighlight lang="java">
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
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseAimRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseAimRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddAimRequest| 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[optional], weapon Id)

====Priority====
The first parameter is optional since version 0.92. Default value is Priority.High, 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:''' <syntaxhighlight lang="java">
this.AddWeaponRequest(WEAPON.MEDKIT);
this.AddWeaponRequest(Priority.Low, WEAPON.KNIFE); </syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseWeaponRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.BlockForWeaponChange(WEAPON.MEDKIT);
this.Say("Medkit Equipped!");</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
count = this.QueryGoals(this.Bot.QueryGoalsTable, 0xc9326a43);
count = this.QueryGoals(this.Bot.QueryGoalsTable, "BUILD_.*");</syntaxhighlight>

----

===BlackboardDelay===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.BlackboardDelay(10);</syntaxhighlight>

----

===BlackboardIsDelayed===

'''Parameters:''' (mapGoal or serialNumber)

'''Returns:''' true if goal has been found on blackboard

'''Example:''' <syntaxhighlight lang="java">
if (this.BlackboardIsDelayed(serial))</syntaxhighlight>

----

===MarkInProgress===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
this.MarkInProgress(); //finish if no slot is available

if (!this.MarkInProgress(this.MapGoal)) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===MarkInUse===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
this.MarkInUse(); //finish if no slot is available

if (!this.MarkInUse(this.MapGoal)) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===WatchForMapGoalsInRadius===

----

===ClearWatchForMapGoalsInRadius===

----

===WatchForEntityCategory===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.WatchForEntityCategory({
Radius = 350,
Category = CAT.PROJECTILE,
RequireLOS = TRACE.VISIBLE
});
</syntaxhighlight>

----

===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 [[ScriptGoal#Disable| 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 [[ScriptGoal#BlockForWeaponChange|BlockForWeaponChange]], [[ScriptGoal#Goto|Goto]], [[ScriptGoal#AddAimRequest|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.

System Library

2025-05-25T16:45:00Z

Palota: /* Write */

{{process header
| title = System Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Global FileSystem Functions==
----
===FileDelete===
Deletes a file by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
FileDelete("myfile.txt");</syntaxhighlight>
----

===FileEnumerate===
Enumerates over all files in a directory. This function is restricted to files under the user folder. This function will call the provided script function with all files enumerated.

'''Parameters:''' (folder name, script function)

'''Returns:''' true if success, false if failed

'''Example:''' <syntaxhighlight lang="java">
myfunc = function(filename)
{
}
FileEnumerate("myfolder", myfunc);</syntaxhighlight>
----
===FileExists===
Checks if a file exists by name. This function is restricted to files under the user folder.

'''Parameters:''' (filename)

'''Returns:''' true if exists, false if not

'''Example:''' <syntaxhighlight lang="java">
if(FileExists("myfile.txt"))
{
}</syntaxhighlight>
----
===Newline===
Returns a NewLine custom type. Used for writing newlines in text formatted files. It was a function in Omni-bot 0.71, but now it is a variable in Omni-bot 0.8.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
f.Write("Some test data", System.NewLine);
}
f.Close();</syntaxhighlight>
----

==File==
Creates a new File Object.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f = File();</syntaxhighlight>

----
===Close===
Closes the file object and commits changes to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Close();</syntaxhighlight>

----

===EndOfFile===
Checks if the File Object is at the end of the file. Useful for read operations.

'''Parameters:''' none

'''Returns:''' true if end of file, false if not.

'''Example:''' <syntaxhighlight lang="java">
eof = f.EndOfFile();</syntaxhighlight>

----

===FileSize===
Gets the file size of the file, in bytes.

'''Parameters:''' none

'''Returns:''' size of file in bytes

'''Example:''' <syntaxhighlight lang="java">
size = f.FileSize();</syntaxhighlight>

----

===Flush===
Flushes the file buffer to disk.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Flush();</syntaxhighlight>

----

===IsOpen===
Checks if the file is currently open. Usually used after a call to Open.

'''Parameters:''' none

'''Returns:''' true if file is open, false if not

'''Example:''' <syntaxhighlight lang="java">
if(f.IsOpen())
{
}</syntaxhighlight>

----

===Open===
Creates a new File Object.

'''Parameters:''' (filename, "text"/"binary", readonly<optional>, append<optional>)

'''Returns:''' true if success, false if failed.

'''Example:''' <syntaxhighlight lang="java">
if(f.Open("myfile.txt", "text", false))
{
}</syntaxhighlight>

----

===ReadFloat===
Reads a float from the file.

'''Parameters:''' none

'''Returns:''' float read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadFloat();</syntaxhighlight>

----

===ReadInt===
Reads an integer from the file.

'''Parameters:''' none

'''Returns:''' integer read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
num = f.ReadInt();</syntaxhighlight>

----

===ReadLine===
Reads a string from a file until a newline or end of file is encountered.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadLine();</syntaxhighlight>

----

===ReadString===
Reads a string from a file.

'''Parameters:''' none

'''Returns:''' string read, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
str = f.ReadString();</syntaxhighlight>

----

===Seek===
Seeks the read/write position to a specified offset.

'''Parameters:''' (byte offset to seek to)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
f.Seek(100); // seek 100 bytes into file</syntaxhighlight>

----

===Tell===
Returns the current offset of the read/write position in the file.

'''Parameters:''' none

'''Returns:''' byte position in file

'''Example:''' <syntaxhighlight lang="java">
t = f.Tell();</syntaxhighlight>

----

===Write===
Writes a value of varying types to the file, in whatever file mode was used to open the file.

'''Parameters:''' (...)

This function can take any number of parameters, of types integer, float, string, or System.NewLine.

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
f = File();
f.Open("myfile.txt", "text", false);
if(f.IsOpen())
{
assert( f.Write("Some test data", System.NewLine) );
}
f.Close();</syntaxhighlight>
----

ScriptGoal

2025-05-25T16:41:20Z

Palota: /* AddWeaponRequest */

{{process header
| title = Script Goal
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
[[Category:ET|Script Goals]]
[[Category:Doom 3|Script Goals]]
[[Category:Quake 4|Script Goals]]
[[Category:RTCW|Script Goals]]

==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]]

<syntaxhighlight lang="java">this.Name = "MyGoalName";</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Parent = "HighLevel";</syntaxhighlight>

===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]]

<syntaxhighlight lang="java">this.Disable = true;</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.AlwaysRecieveEvents = true;</syntaxhighlight>

===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 [[ScriptGoal#AlwaysRecieveEvents| AlwaysRecieveEvents]], which will allow goals to receive events even when not active.
<syntaxhighlight lang="java">
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) );
};</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Bot.Say("Wassup");</syntaxhighlight>

===Priority===
Priority is a property rather than a return value of [[ScriptGoal#GetPriority| GetPriority]] in order to support the useful threading nature of script goals. It is possible to completely leave out a [[ScriptGoal#GetPriority| 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.

<syntaxhighlight lang="java">this.Priority = 1;</syntaxhighlight>

===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.
<syntaxhighlight lang="java">
this.Commands["command_name"] = {
Func = function( _params )
{
},
Help = { "description" },
};
</syntaxhighlight>

==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:''' <syntaxhighlight lang="java">
this.Initialize() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.OnSpawn() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.GetPriority() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.Enter() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.Exit() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]]
----
===Update===
This function is the meat of a script goal. Once a goal is chosen to run, and [[ScriptGoal#Enter| Enter]] is called, the Update function begins getting called at frequent regular intervals. The state stays active until another goal overrides it, or until [[ScriptGoal#Finished| Finished]] is called, after which the [[ScriptGoal#Exit| Exit]] function is called.

'''Example:''' <syntaxhighlight lang="java">
this.Update() = function()
{
// do stuff
this.Finished(); // when we're done running
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]], [[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.OnPathThrough = function(data)
{
navigation = Map.Navigation[data];
if(navigation)
{
this.CurrentNavigation = data;
return true;
}
this.CurrentNavigation = null;
return false;
};
</syntaxhighlight>

==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
{| align="center" border="1"
!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)
|-
|mapgoalavailable
|No
|MapGoal object or name
|}

=====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
<syntaxhighlight lang="java">
this.AddFinishCriteria(this.TargetEntity,"not hasentflag",ENTFLAG.DEAD); // as soon as the entity does not have the dead flag
</syntaxhighlight>

'''Returns:''' true if criteria was created, false if not

'''Example:''' <syntaxhighlight lang="java">
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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.Finished();</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
//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
};</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToClass(CLASS.MEDIC);
this.LimitToClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoClass(CLASS.MEDIC);
this.LimitToNoClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTeam(TEAM.BLUE);
this.LimitToTeam(TEAM.BLUE, TEAM.RED);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToEntityFlag(ENTFLAG.INWATER);
this.LimitToEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoEntityFlag(ENTFLAG.INWATER);
this.LimitToNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE); </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function takes no parameters.
this.LimitToNoTarget(); </syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToWeapon(WEAPON.MOBILE_MG42);
this.LimitToWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// 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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetTeam(TEAM.RED); // don't run unless our target is on red team</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42);
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.LimitToRole(ROLE.DEFENDER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.GetPriority = function()
{
if(this.IsActive())
{
return 1.0;
}
else
{
// do some other check
}
}; </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
wpinfo = table();
wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
if( this.Goto(wpinfo.position, wpinfo.radius) == EVENT.PATH_SUCCESS )
{
print("Made it!");
}</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
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!");
}</syntaxhighlight>

----

===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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathSucceed())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathFail())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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 - LookAround
* Priority.Low - CAMP, ESCORT, RIDE, MOUNT, ...
* 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:''' <syntaxhighlight lang="java">
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
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseAimRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseAimRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddAimRequest| 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[optional], weapon Id)

====Priority====
The first parameter is optional since version 0.92. Default value is Priority.High, 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:''' <syntaxhighlight lang="java">
this.AddWeaponRequest(WEAPON.MEDKIT);
this.AddWeaponRequest(Priority.Low, WEAPON.KNIFE); </syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseWeaponRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.BlockForWeaponChange(WEAPON.MEDKIT);
this.Say("Medkit Equipped!");</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
count = this.QueryGoals(this.Bot.QueryGoalsTable, 0xc9326a43);
count = this.QueryGoals(this.Bot.QueryGoalsTable, "BUILD_.*");</syntaxhighlight>

----

===BlackboardDelay===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.BlackboardDelay(10);</syntaxhighlight>

----

===BlackboardIsDelayed===

'''Parameters:''' (mapGoal or serialNumber)

'''Returns:''' true if goal has been found on blackboard

'''Example:''' <syntaxhighlight lang="java">
if (this.BlackboardIsDelayed(serial))</syntaxhighlight>

----

===MarkInProgress===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
this.MarkInProgress(); //finish if no slot is available

if (!this.MarkInProgress(this.MapGoal)) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===MarkInUse===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
this.MarkInUse(); //finish if no slot is available

if (!this.MarkInUse(this.MapGoal)) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===WatchForMapGoalsInRadius===

----

===ClearWatchForMapGoalsInRadius===

----

===WatchForEntityCategory===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.WatchForEntityCategory({
Radius = 350,
Category = CAT.PROJECTILE,
RequireLOS = TRACE.VISIBLE
});
</syntaxhighlight>

----

===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 [[ScriptGoal#Disable| 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 [[ScriptGoal#BlockForWeaponChange|BlockForWeaponChange]], [[ScriptGoal#Goto|Goto]], [[ScriptGoal#AddAimRequest|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.

Bot Library

2025-05-25T16:37:45Z

Palota: /* EntityIsValid */

{{process header
| title = Bot Library
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
== Global Bot Functions ==

=== AddBot ===
Adds a bot to the game, and optionally specifies team, class, and name for the bot.

'''Parameters:''' ()

'''Parameters:''' (team)

'''Parameters:''' (team, class)

'''Parameters:''' (team, class, name)

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
AddBot();
// OR
AddBot(TEAM.AXIS);
// OR
AddBot(TEAM.AXIS, CLASS.SOLDIER);
// OR
AddBot(TEAM.AXIS, CLASS.SOLDIER, "SomeDude");
// OR
// not all fields are valid for all games, here's a quake 4 example
// not all fields are required. any left out will use sensible default values
tbl =
{
name="SomeDude",
team=TEAM.STROGG,
class=CLASS.PLAYER,
spawnpoint="somespawnpointname",
model="model_player_kane_strogg",
skin="base",
};
AddBot(tbl);</syntaxhighlight>

'''See Also:'''
[[Bot Library#KickBot| KickBot]], [[Bot Library#KickAll| KickAll]]
----

=== AllocGoalSerialNum ===
Gets unique goal serial number.

'''Parameters:''' none

'''Returns:''' integer

----

=== CalcTrajectory ===
Calculates a projectile trajectory, and returns the results in a table, or null if no trajectory exists for the parameters given.

'''Parameters:''' (Vector3 start position, Vector3 target position, projectile speed, projectile gravity)

'''Returns:''' table or null

'''Example:''' <syntaxhighlight lang="java">
mypos = Vector3(10,10,10); // get a valid position from somewhere
targpos = Vector3(20,20,20); // get a valid position from somewhere
projVel = 1000;
projGrav = 0.5;
traj = CalcTrajectory(mypos, targpos, projVel, projGrav);
if(traj)
{
// if a table was returned, there can be 1 or 2 trajectories stored in it.
// the 1st trajectory is the most direct trajectory
// the 2nd trajectory is normally a mortar trajectory with a high degree of arc.
// both trajectories are a unit length facing vector
b.TurnToFacing(traj[0]);
// OR
b.TurnToFacing(traj[1]);
}</syntaxhighlight>

----

=== CheatsEnabled ===
Checks if cheat mode is enabled in the game. Useful for debug or development scripts that use functions that are only available in cheat mode.

'''Parameters:''' none

'''Returns:''' true if cheats are enabled, false if not

'''Example:''' <syntaxhighlight lang="java">
if(CheatsEnabled())
{
// do something
}</syntaxhighlight>

'''See Also:'''
[[Bot Library#EntityKill| EntityKill]], [[Bot Library#ServerCommand| ServerCommand]]
----

=== CheckEntityBoundsIntersect ===
Checks if entities intersect.

'''Parameters:''' (entity1, entity2)

'''Returns:''' true/false

----

=== ClearGoalRole ===
Clears one or more roles of one or more MapGoals.

'''Parameters:''' (expression or table, role or table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
example: ClearGoalRole( "FLAG_Gold", ROLE.ATTACKER ); //1 goal, 1 role
example: ClearGoalRole( "DEFEND_City[4567]", { ROLE.DEFENDER2, ROLE.DEFENDER3}); //4 goals, 2 roles
</syntaxhighlight>

'''See Also:''' [[Roles]]
----

=== ConfigGet ===
Gets a config value from omni-bot.cfg. Sets a config value if it does not exist yet and if the third parameter is not null.

Type of the return value is string, int or float according to the third parameter. If you call ConfigGet with only 2 parameters, it will return string.

'''Parameters:''' (section, config parameter name, config parameter value[optional])

'''Returns:''' config parameter value

'''Example:'''
<syntaxhighlight lang="java">
ft = ConfigGet("FireTeam", "enabled", 1);
</syntaxhighlight>

'''See Also:'''
[[Bot Library#ConfigSet|ConfigSet]]
----

=== ConfigSet ===
Sets a config value in omni-bot.cfg.

'''Parameters:''' (section, config parameter name, config parameter value)

'''Returns:''' none

'''Example:'''
<syntaxhighlight lang="java">ConfigSet("FireTeam", "enabled", 0);</syntaxhighlight>

'''See Also:'''
[[Bot Library#ConfigGet|ConfigGet]]
----

=== CreateMapGoal ===
Creates a new goal.

'''Parameters:''' (type)

'''Returns:''' MapGoal object

----

=== Debug Functions ===
----

==== DrawAABB ====
'''See:'''
[[Bot Library#DrawDebugAABB | DrawDebugAABB]]
----

==== DrawArrow ====
Draws an arrow. Used for facing or AimVectors.

'''Parameters:''' (Vector3 start, Vector3 end, color, duration)

'''Returns:''' none

----

==== DrawDebugAABB ====
Draws a box.

'''Parameters:''' (AABB, color, duration)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
AABB box; // initialize it with something
// draw it in red for 5 seconds
DrawDebugAABB(box, COLOR.RED, 5);</syntaxhighlight>

'''See Also:'''
[[Bot Library#DrawDebugLine | DrawDebugLine]], [[Bot Library#GetEntWorldAABB | GetEntWorldAABB]]
----

==== DrawDebugLine ====
Draws a line in the environment. Useful for debugging.

'''Parameters:''' (Vector3 start, Vector3 end, color, duration)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
start = Vector3(0,0,0);
end = Vector3(20,20,20);
// draw it in red for 5 seconds
DrawDebugLine(start, end, COLOR.RED, 5);</syntaxhighlight>

'''See Also:'''
[[Bot Library#DrawDebugAABB | DrawDebugAABB]], [[Bot Library#GetEntWorldAABB | GetEntWorldAABB]]

----

==== DrawEntityAABB ====
Draws a bounding box around an entity. The box is usually much bigger than the entity.

'''Parameters:''' (entity, duration, color)

'''Returns:''' true/false

----

==== DrawEntityOBB ====
Draws an oriented box around an entity.

'''Parameters:''' (entity, duration, color)

'''Returns:''' true/false

----

==== DrawLine ====
'''See:'''
[[Bot Library#DrawDebugLine | DrawDebugLine]]
----

==== DrawRadius ====
Draws radius.

'''Parameters:''' (position, radius, color, duration)

'''Returns:''' none

----

==== DrawText3d ====
Draws text.

'''Parameters:''' (position, string, color, duration, maxDistanceFromPlayer[optional, default 1024])

'''Returns:''' none

----

==== DrawTrajectory ====
Draws trajectory of grenade, mortar, airstrike or smokebomb.

'''Parameters:''' ( {Position, Velocity, Interval, Duration, BounceLoss, GravityMultiplier, StopAtHit, TraceBounce }, color, duration)

'''Returns:''' target position

----

==== DumpConsoleToFile ====
Saves debug console, only if debug window is enabled.

'''Parameters:''' (file name)

'''Returns:''' none

----

==== EchoToScreen ====
Prints a message to the screen.

'''Parameters:''' (duration, message)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
EchoToScreen(5,"Hello World!");</syntaxhighlight>

----

==== EnableDebugWindow ====
Enables or disables [[Debug_Window|debug window]]. Does not work in release build of omnibot dynamic link library. You must use omnibot_et.dll from dw_enabled subfolder on [[Assembla]].

'''Parameters:''' (true/false, width[optional, default 1024], height[optional, default 768], bitsPerPixel[optional, default 32])

'''Returns:''' none

----

==== Error ====
Prints an error to the games output console.

'''Parameters:''' (error message)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
Error("Somethin bad happened");</syntaxhighlight>

----

==== Log ====
Writes a string to the omnibot log file.

The second parameter: 0=info, 1=warning, 2=error, 3=critical

'''Note:''' logs are disabled if cvar omnibot_logsize is zero or negative

'''Note:''' logs can also be disabled in omni-bot.cfg

'''Parameters:''' (string, level[optinal, default 0])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
Log("Something cool happened");
Log("Something bad happened", 2);</syntaxhighlight>

----

==== ShowPaths ====
Debug Information function. Prints Omni-bot version, revision, and revision date, along with file system paths.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
ShowPaths();</syntaxhighlight>

----

==== TransformAndDrawLineList ====

'''Parameters:''' (veclist, color, duration, position, euler)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
TransformAndDrawLineList({Vec3(20,80,0), Vec3(20,-60,0), Vec3(-90,70,30), Vec3(-90,-50,30)},
COLOR.RED, 5, GetLocalPosition(), Vec3(DegToRad(45),0,0));</syntaxhighlight>

----

=== DeleteTriggerRegion ===
Deletes a trigger region previously created with [[Bot Library#OnTriggerRegion| OnTriggerRegion]]. Because regions aren't required to have unique names, DeleteTriggerRegion will delete all regions that match the provided name. This allows grouping of different trigger regions by shared names.

'''Parameters:''' (name)

'''Parameters:''' (serial #)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// creates a sphere trigger 256 units in radius around 0,0,0, then delete it immediately.
triggerInfo =
{
Name="TestTrigger",
TriggerOnClass=CLASS.ANYPLAYER,
OnEnter = function(ent)
{
print(GetEntName(ent),"entered aabb trigger");
},
OnExit = function(ent)
{
print(GetEntName(ent),"exited aabb trigger");
},
};
serial = OnTriggerRegion(Vector3(0,0,0),256,triggerInfo);

DeleteTriggerRegion(serial);
// OR
DeleteTriggerRegion("TestTrigger");

</syntaxhighlight>

'''See Also:'''
[[Bot Library#OnTriggerRegion| OnTriggerRegion]]
----

=== DistanceBetween ===
Utility function for checking distances between 2 objects. This function takes 2 parameters, but the parameter types can vary.

'''Parameters:''' (object1, object2)

For this function, each parameter can be one of the following types.
* Vector3
* GameEntity
* GameId
* MapGoal

This provides a flexible and fast function that allows a script to check the distance between a variety of source and destination object, and reduces the need for the script to convert between GameEntity or GameId, or to get the position of the GameEntity itself.

'''Returns:''' distance between the objects

'''Example:''' <syntaxhighlight lang="java">
// assume entity1 is a GameEntity from another source, such as GetAllType
if(DistanceBetween(b.GetGameEntity(), entity1))
{
}
// OR
if(DistanceBetween(b.GetGameEntity(), Vector3(10,20,30))
{
}</syntaxhighlight>

----

=== DynamicPathsUpdated ===
Finds new path for bots in teams specified if paths go through waypoint which has dynamic flag.

'''Parameters:''' (teamId, ...)

'''Returns:''' none

----

=== Entity Functions ===

==== EntityIsOutside ====
Checks if a given entity is outside. Added in 0.83

'''Parameters:''' (entity)

'''Returns:''' true/false

----

==== EntityIsValid ====
Checks if a given entity exists. Parameter can be entity handle or entity ID.
Since 0.92 it does not throw exception but returns false if parameter is null.

'''Parameters:''' (entity)

'''Returns:''' true/false

----

==== EntityKill ====
Kills an entity. Requires cheats to be enabled.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
EntityKill(GetEntityByName("truck"));</syntaxhighlight>

'''See Also:'''
[[Bot Library#CheatsEnabled | CheatsEnabled ]]

----

==== GetEntBonePosition ====
Gets the world position of a specific bone on an entity.

'''Note:''' This function may not be implemented for all games. It's not implemented in ET.

'''Parameters:''' (GameEntity/GameId, BoneId)

'''Returns:''' Vector3 world bone position, or null if bone not found

'''Example:''' <syntaxhighlight lang="java">
headpos = GetEntBonePosition(someent, BONE.HEAD);
if(headpos)
{
// got head position
}</syntaxhighlight>

----

==== GetEntCategory ====
Checks if the entity belongs to one or more entity categories. This function takes one or more categories, and returns true if the entity belongs to all the provided categories.

'''Parameters:''' (GameEntity/GameId, Category, ...)

'''Returns:''' true if the entity belongs to all provided categories.

'''Example:''' <syntaxhighlight lang="java">
if(GetEntCategory(someent, CAT.PROJECTILE))
{
}
if(GetEntCategory(someent, CAT.PLAYER, CAT.VEHICLE))
{
} </syntaxhighlight>

'''See also:''' [[CAT]]
----

==== GetEntClass ====
Gets the class of the entity.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' class of entity, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
if(GetEntClass(someent) == CLASS.SOLDIER)
{
}</syntaxhighlight>

'''See also:''' [[CLASS]]
----

==== GetEntEquippedWeapon ====
Gets current weapon of a player.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' weaponId

'''Example:''' <syntaxhighlight lang="java">
weapon = GetEntEquippedWeapon(this.TargetEntity);
</syntaxhighlight>

----

==== GetEntEyePosition ====
Gets the world eye position of an entity.

Note: position is not correct if bot is looking up or down

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 eye position, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
eyepos = GetEntEyePosition(someent);
if(eyepos)
{
// got eye position
}</syntaxhighlight>

----

==== GetEntFacing ====
Gets the world facing vector of an entity

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 facing, or null if there was an error

'''Example:''' <syntaxhighlight lang="java">
face = GetEntFacing(someent);
if(face)
{
// got face vector, as a direction vector
}</syntaxhighlight>

----

==== GetEntFlags ====
Checks if the entity has one or more entity flags.

'''Parameters:''' (GameEntity/GameId, Entity Flag, ...)

'''Returns:''' true if the entity has any of provided entity flags.

'''Example:''' <syntaxhighlight lang="java">
if(GetEntFlags(someent, ENTFLAG.CROUCHED))
{
}
if(GetEntFlags(someent, ENTFLAG.CROUCHED, ENTFLAG.RELOADING))
{
} </syntaxhighlight>

'''See also:''' [[ENTFLAG]]
----

==== GetEntHealthAndArmor ====
Gets health and armor of an entity.

'''Parameters:''' (GameEntity/GameId, table)

'''Returns:''' true if successful, false if not

Properties stored into table:
* Health - Current Health
* MaxHealth - Max Health
* Armor - Current Armor
* MaxArmor - Max Armor

'''Example:''' <syntaxhighlight lang="java">
healthArmor = {};
if(GetEntHealthAndArmor(someentity, healthArmor))
{
if(healthArmor.Health < 20)
{
b.Say("I'm Hurt!");
}
} </syntaxhighlight>

'''See also:''' [[Utility_Functions#Util.GetEntHealth|Util.GetEntHealth]]
----

==== GetEntName ====
'''See:'''
[[Bot Library#GetEntityName | GetEntityName]]
----

==== GetEntOwner ====
Gets the owner of an entity. Typically used for entities that can be held or carried.

Note: If player who is carrying objective is kicked, GetEntOwner will return invalid entity till end of match. This bug is in all ET mods (except the last version of omnibot mod).

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' GameId of owner, or null if none or error

'''Example:''' <syntaxhighlight lang="java">
owner = GetEntOwner(someent);</syntaxhighlight>

----

==== GetEntPosition ====
Gets the world position of an entity.

Note: old mods return wrong position (NoQuarter 1.2.5, ETpub 0.9.0, Jaymod 2.1.7, ...).

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 world position, or null if error

'''Example:''' <syntaxhighlight lang="java">
p = GetEntPosition(someent);</syntaxhighlight>
----

==== GetEntPowerups ====
Checks if the entity has one or more powerups. This function takes one or more powerups, and returns true if the entity has all of them.

'''Parameters:''' (GameEntity/GameId, PowerUp, ...)

'''Returns:''' true if the entity has all powerups.

'''Example:''' <syntaxhighlight lang="java">
if(GetEntPowerups(someent, POWERUP.INVINCIBLE))
{
}
if(GetEntPowerups(someent, POWERUP.QUADDAMAGE, POWERUP.BERSERK))
{
} </syntaxhighlight>

----

==== GetEntRotationMatrix ====
Gets the Matrix3 full transform of an entity.

'''Parameters:''' (GameEntity/GameId, Matrix3<optional>)

If you pass an Matrix3 as the 2nd parameter, that object will be filled in instead of a new Matrix3 returned. This can save memory allocations in a script that calls the function often by re-using the same object.

'''Returns:''' true if Matrix3 passed as 2nd parameter and filled in successfully, if no Matrix3 provided, returns Matrix3 for entity. Both return null on an error.

'''Example:''' <syntaxhighlight lang="java">
entMat = GetEntRotationMatrix(someent);
if(entMat)
{
// do something
}
// re-use the same Matrix3 later
if(GetEntRotationMatrix(someent, entMat))
{
} </syntaxhighlight>

----

==== GetEntTeam ====
Gets the team id that the entity belongs to.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Team Id of entity, or null if error

'''Example:''' <syntaxhighlight lang="java">
if(GetEntTeam(someent) == TEAM.RED)
{
}</syntaxhighlight>

'''See also:''' [[TEAM]]
----

==== GetEntVelocity ====
Gets the world velocity of an entity.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' Vector3 world velocity, or null if error

'''Example:''' <syntaxhighlight lang="java">
vel = GetEntVelocity(someent);</syntaxhighlight>
----

==== GetEntWorldAABB ====
Gets the bounding box for an entity. The box is usually much bigger than the entity. Center of the box is not equal to entity position.

'''Parameters:''' (GameEntity/GameId, AABB<optional>)

If you pass an AABB as the 2nd parameter, that object will be filled in instead of a new AABB returned. This can save memory allocations in a script that calls the function often by re-using the same object.

'''Returns:''' true if AABB passed as 2nd parameter and filled in successfully, if no AABB provided, returns AABB for entity. Both return null on an error.

'''Example:''' <syntaxhighlight lang="java">
entAABB = GetEntWorldAABB(someent);
if(entAABB)
{
// do something
}
// re-use the same AABB later
if(GetEntWorldAABB(someent, entAABB))
{
} </syntaxhighlight>

----

==== GetEntityByName ====
Finds entity by target name. In ET you can use command '''/entitylist''' to see entity names.

Unfortunately this functions can't find entities which have only script name, but don't have target name.

'''Parameters:''' (name)

'''Returns:''' GameEntity found, or null if none found

----

==== GetEntityInSphere ====
Finds an entity within a radius around a point that matches a particular class Id. It is set up so that it can be used in a loop to find all entities.

'''Parameters:''' (Vector3 position, radius, classid, start entity)

'''Returns:''' GameEntity found, or null if none found

'''Example:''' <syntaxhighlight lang="java">
p = Vector3(10,10,10);
radius = 20;
ent = GetEntityInSphere(p, radius, CLASS.ANYPLAYER, null);
while(ent)
{
// do something with it?
// get the next one found
ent = GetEntityInSphere(p, radius, CLASS.ANYPLAYER, ent);
}</syntaxhighlight>
----

==== GetEntityLocalSpace ====
Converts a world position into a local space position of a specified entity.

'''Parameters:''' (GameEntity/GameId, Vector3 world position)

'''Returns:''' Vector3 local space position, or null if error

'''Example:''' <syntaxhighlight lang="java">
worldpos = Vector3(10,10,10);
localpos = GetEntityLocalSpace(someent, worldpos); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetEntityWorldSpace | GetEntityWorldSpace]]
----

==== GetEntityName ====
Gets the name of an entity. In ET you can use command '''/entitylist''' to see all entity names.

If entity has defined both script name and target name, GetEntityName returns script name.

'''Parameters:''' (GameEntity/GameId)

'''Returns:''' name of entity, or null if error

'''Example:''' <syntaxhighlight lang="java">
entName = GetEntityName(someent);
if(entName == "SomeName")
{
// do something
}
</syntaxhighlight>

----

==== GetEntityStat ====
Generic function for getting information about an entity, by name.

'''Parameters:''' (GameEntity/GameId, stat name)

'''Returns:''' stat, or null if error or stat doesn't exist. The type depends on the stat.

'''Example:''' <syntaxhighlight lang="java">
kills = GetEntityStat(someent, "kills");
deaths = GetEntityStat(someent, "deaths");
xp = GetEntityStat(bot.GetGameEntity(), "xp");
</syntaxhighlight>
----

==== GetEntityWorldSpace ====
Converts a local space position into a world space position of a specified entity.

'''Parameters:''' (GameEntity/GameId, Vector3 local position)

'''Returns:''' Vector3 world space position, or null if error

'''Example:''' <syntaxhighlight lang="java">
localpos = Vector3(10,10,10);
worldpos = GetEntityWorldSpace(someent, localpos); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetEntityLocalSpace | GetEntityLocalSpace]]
----

==== GetGameEntityFromId ====
Converts a GameId to a GameEntity.

'''Parameters:''' (GameId)

'''Returns:''' GameEntity

'''Example:''' <syntaxhighlight lang="java">
ent = GetGameEntityFromId(2); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetGameIdFromEntity | GetGameIdFromEntity ]]
----

==== GetGameIdFromEntity ====
Converts a GameEntity to a GameId.

'''Parameters:''' (GameEntity)

'''Returns:''' GameId

'''Example:''' <syntaxhighlight lang="java">
id = GetGameIdFromEntity(someent); </syntaxhighlight>

'''See Also:'''
[[Bot Library#GetGameEntityFromId | GetGameEntityFromId ]]
----

=== ExecCommand ===
This function executes a bot command as if it came from the games input console.

'''Parameters:''' (command string)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
ExecCommand("addbot 1 2")</syntaxhighlight>

----

=== ExecCommandOnClient ===
Executes a command for the entity. Usually equivilent to console commands.

'''Parameters:''' (GameEntity/GameId, command string)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
ExecCommandOnClient(bot.GetGameEntity(), "setviewpos 1200 2300 150 0");</syntaxhighlight>
----

=== ExecScript ===
Attempts to execute a script file. File is searched in scripts folder, global_scripts folder or game folder (omni-bot/et).

'''Parameters:''' (filename)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
ExecScript("myscript.gm");</syntaxhighlight>

----

=== GetClassNameFromId ===
Gets the current class name from a class id.

'''Parameters:''' (classId)

'''Returns:''' string

----

=== GetGameName ===
Gets the name of the currently running game.

'''Parameters:''' none

'''Returns:''' name of game

'''Example:''' <syntaxhighlight lang="java">
if(GetGameName() == "Enemy Territory")
{
}
else if(GetGameName() == "Quake 4")
{
}
</syntaxhighlight>

----

=== GetGameState ===
Gets the current state of the game (Playing, Warm-up, Warm-up Countdown, Intermission, Waiting for Players, Paused, Invalid).

'''Parameters:''' none

'''Returns:''' name of game state

'''Example:''' <syntaxhighlight lang="java">
if(GetGameState() == "Playing")
{
}</syntaxhighlight>

----

=== GetGameTimeLeft ===
Gets the current amount of time remaining in the game round.

'''Parameters:''' none

'''Returns:''' time left, in seconds

'''Example:''' <syntaxhighlight lang="java">
if(GetGameTimeLeft() < 30)
{
}</syntaxhighlight>

----

=== GetGoal ===
Gets a reference to a map goal by name. The goal name is case sensitive.

'''Parameters:''' (name of map goal to get)

'''Returns:''' MapGoal if found, null if not

'''Example:''' <syntaxhighlight lang="java">
mg = GetGoal("MAP_FLAG_redflag");</syntaxhighlight>

'''See Also:'''
[[MapGoal]]
----

=== GetGoals ===
Gets any number of map goals that match a regular expression. Stores the matching reference in the first table parameter. The previous table content is cleared since omni-bot 0.84. It's not possible to call GetGoals multiple times to accumulate results. The last optional parameter is table of parameters to filter result (Group, Role, SkipNoInProgress, SkipNoInUse, SkipInUse) or sort result (parameter Sort, values are "none", "priority", "name", "priority_name", "random").

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
goals = {};
GetGoals(goals, TEAM.AXIS, "FLAG.*", { Sort="priority" });</syntaxhighlight>

'''See Also:'''
[[Utility_Functions#Util.GoalTable|Util.GoalTable]], [[Bot Library#GetGoal| GetGoal]]
----

=== GetGravity ===
Gets the current gravity of the game.

'''Parameters:''' none

'''Returns:''' gravity

'''Example:''' <syntaxhighlight lang="java">
grav = GetGravity();</syntaxhighlight>

----

=== GetLocalAABB ===
Gets bounding box of local player.

'''Parameters:''' none

'''Returns:''' AABB

----

=== GetLocalAimNormal ===
Gets normal at aim position of local player.

'''Parameters:''' (collision mask[optional, default floodfill])

'''Returns:''' Vector3

----

=== GetLocalAimPosition ===
Gets aim position of local player.

'''Parameters:''' (collision mask[optional, default floodfill])

'''Returns:''' Vector3

----

=== GetLocalEntity ===
Gets local player.

'''Parameters:''' none

'''Returns:''' GameEntity

----

=== GetLocalEyePosition ===
Gets eye position of local player.

'''Parameters:''' none

'''Returns:''' Vector3

----

=== GetLocalCommand ===
Gets name of just running console command. It is useful if you use same script for multiple commands.

'''Parameters:''' none

'''Returns:''' string or null

----
=== GetLocalFacing ===
Gets facing vector of local player.

'''Parameters:''' none

'''Returns:''' Vector3

----

=== GetLocalGroundPosition ===
Gets ground position of local player.

'''Parameters:''' none

'''Returns:''' Vector3 or null

----

=== GetLocalPosition ===
Gets position of local player.

'''Parameters:''' none

'''Returns:''' Vector3

----

=== GetMapExtents ===
Gets the AABB map extents. Map extends are the bounds of the entire map.

'''Parameters:''' (AABB<optional>)

'''Returns:''' If no AABB passed as parameter, function will return the map AABB, otherwise the AABB parameter will be filled in with the results, and the function will return nothing.

'''Example:''' <syntaxhighlight lang="java">
aabb = GetMapExtents();
// or
AABB aabb;
GetMapExtents(aabb);</syntaxhighlight>

----

=== GetMapName ===
Get the name of the current map.

'''Parameters:''' none

'''Returns:''' name of map

'''Example:''' <syntaxhighlight lang="java">
if(GetMapName() == "oasis")
{
}</syntaxhighlight>

----

=== GetModName ===
Gets the name of the currently running mod.

'''Parameters:''' none

'''Returns:''' name of mod

'''Example:''' <syntaxhighlight lang="java">
if(GetModName() == "etpub")
{
}</syntaxhighlight>

----

=== GetModVersion ===
Gets the version of the current mod.

'''Parameters:''' none

'''Returns:''' version of mod

'''Example:''' <syntaxhighlight lang="java">
if(GetModVersion() == "DOOM 1.3")
{
}</syntaxhighlight>

----

=== GetNearestNonSolid ===
This function is similar to TraceLine, but ignores solids.

'''Parameters:''' (start, end, trace mask[optional])

'''Returns:''' position

----

=== GetPointContents ===
Gets the contents bits for a given position.

'''Parameters:''' (Vector3 position)

'''Returns:''' contents bits. Use bitwise manipulators along with constants from the global [[CONTENT]] table to check for specific content bits.

'''Example:''' <syntaxhighlight lang="java">
contents = GetPointContents(Vector3(10,10,10));
if(contents & CONTENT.WATER)
{
}</syntaxhighlight>

----

=== GetTeamStat ===
Generic function for getting information about a team, by name. It's not implemented in ET.

'''Parameters:''' (Team Id, stat name)

'''Returns:''' stat, or null if error or stat doesn't exist. The type depends on the stat.

'''Example:''' <syntaxhighlight lang="java">
score = GetTeamStat(TEAM.RED, "score");</syntaxhighlight>
----

=== GetTime ===
Gets the current time elapsed in the game.

'''Parameters:''' none

'''Returns:''' time, in seconds

'''Example:''' <syntaxhighlight lang="java">
if(GetTime() > 30)
{
}</syntaxhighlight>

----

=== GetWeapon ===
Gets weapon object by ID.

'''Parameters:''' (weaponId)

'''Returns:''' [[Weapon]]

----

=== GetWeaponIdFromClassId ===
Converts classId to weaponId.

'''Parameters:''' (classId)

'''Returns:''' weaponId

----

=== GroundPoint ===
Returns a point on the ground directly below the provided point.

'''Parameters:''' (position)

'''Returns:''' ground position

----

=== KickAll ===
Kicks all bots from the game.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
KickAll();</syntaxhighlight>

----

=== KickBot ===
Kicks a bot by name.

'''Parameters:''' (name)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
KickBot("Fred");</syntaxhighlight>

----

=== KickBotFromTeam ===
Kicks last bot from team.

'''Parameters:''' (teamId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
KickBot(TEAM.AXIS);</syntaxhighlight>

----

=== MoveBotToAnotherTeam ===
Moves a bot from a team to another team.

'''Parameters:''' (source teamId, destination teamId)

'''Returns:''' none

----

=== OnTrigger ===
Registers a script function callback for a given trigger string.

'''Parameters:''' (trigger string, script function)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
global Map =
{
myfunc = function(trigger)
{
direction = ToVector(trigger.Action);
entityName = GetEntName(trigger.Entity);
}
};
global OnMapLoad = function()
{
OnTrigger( "cargo_lift_goto", Map.myfunc);
};
</syntaxhighlight>

'''See Also:'''
[[Triggers]]
----

=== OnTriggerRegion===
Creates one of several types of trigger regions. A trigger region is an area that watches for entities of certain types to touch them and calls script callback functions for enter and exit. Useful if you want an easy way to be notified when certain entities go to certain areas of the map.

This function takes a table as the last parameter to define a number of flexible options for the trigger region. Here is a list of available key/value options for the table.
* Name - Optional name to give the region. Does not need to be unique.
* OnEnter - script function to call when an entity touches the region.
* OnExit - script function to call when an entity stops touching the region.
* TriggerOnClass - Define the class id you want the region to trigger on. This field may also be an indexed table with up to 8 class ids.
* TriggerOnCategory - Category of entities to watch for. This field may also be an indexed table with as many categories as you want to limit the trigger to.
* TriggerOnEntity - A specific entity to trigger on. This field may also be an indexed table with up to 8 entities you want to limit the trigger to.

The following region types are supported. The type is dependent on which parameters of the function are used.
* AABB - Axis aligned bounding box.
* Sphere - A radius around a position.

Triggers may be rendered for reference with ''/bot drawtriggers 1''

'''Parameters:''' (AABB, table)

'''Parameters:''' (position, radius, table)

'''Returns:''' unique serial number of region

'''Example:''' <syntaxhighlight lang="java">
// creates a sphere trigger 256 units in radius around 0,0,0
triggerInfo =
{
Name="TestTrigger",
TriggerOnClass=CLASS.ANYPLAYER,
OnEnter = function(ent)
{
print(GetEntName(ent),"entered aabb trigger");
},
OnExit = function(ent)
{
print(GetEntName(ent),"exited aabb trigger");
},
};
serial = OnTriggerRegion(Vector3(0,0,0),256,triggerInfo);
</syntaxhighlight>

'''See Also:'''
[[Bot Library#DeleteTriggerRegion| DeleteTriggerRegion]]
----

=== RegisterDefaultProfile ===
Registers a default profile that will be loaded for any bot that joins a specified class.

'''Parameters:''' (Class Id, script name)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
RegisterDefaultProfile(CLASS.SOLDIER, "def_bot.gm");</syntaxhighlight>

----

=== ReloadGoalScripts ===
Executes all goal scripts. You must also kick all bots because any changes will be applied to newly added bots.

'''Parameters:''' none

'''Returns:''' none

----

=== RunScript ===
'''See:'''
[[Bot Library#ExecScript| ExecScript]]
----

=== SendTrigger ===
It is used by goal scripts to call function in map script.
Parameter TagName is string which must be same as the first parameter of function [[Bot Library#OnTrigger|OnTrigger]].

'''Parameters:''' ( { TagName, Entity, Activator, Action } )

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
SendTrigger({
Entity = ent,
Activator = null,
TagName = GetEntName(ent) + " at location",
Action = "arrived"
});
</syntaxhighlight>
----

=== ServerCommand ===
Executes a server command. Requires cheats to be enabled.

'''Parameters:''' none

'''Returns:''' true if cheats are enabled, false if not

'''Example:''' <syntaxhighlight lang="java">
ServerCommand("map oasis");</syntaxhighlight>

'''See Also:'''
[[Bot Library#CheatsEnabled | CheatsEnabled ]]
----

=== ServerScriptFunction ===
Not implemented in ET.

'''Parameters:''' (entity name, function name, parameters[optinal])

'''Returns:''' none

----

=== SetAvailableMapGoals ===
Enables/Disables the available status of one or more map goals that match a regular expression, for a specific team.

'''Parameters:''' (Team Id, enable/disable, mapgoal expression string)

'''Parameters:''' (Team Id, enable/disable, table of mapgoal expressions) (added in 0.84)

'''Returns:''' number of goals that match regular expression

'''Example:''' <syntaxhighlight lang="java">
SetAvailableMapGoals( TEAM.ALLIES, false, "ATTACK.*" );
SetAvailableMapGoals( TEAM.AXIS, true, { "DEFEND_gate.*", "MOUNTMG42_bunker", "SNIPE_tower.*" } );</syntaxhighlight>

'''See Also:'''
[[Availability]], [[Bot Library#GetGoal| GetGoal]], [[Bot Library#GetGoals| GetGoals]]
----

=== SetGoalGroup ===
Sets the goal or table of goals group name.

'''Parameters:''' (goalname or table, groupname)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
SetGoalGroup( "SomeGoalName", "SomeGroupName" );
SetGoalGroup( { "ROUTE_route1", "ROUTE_route2", "someothergoal" }, "MyGroup" );
</syntaxhighlight>

'''See Also:'''
[[Utility Functions#Util.DisableGroup| Util.DisableGroup]],
[[Utility Functions#Util.EnableGroup| Util.EnableGroup]],
[[Utility Functions#Util.GetGroup| Util.GetGroup]],
[[Utility Functions#Util.SetGroup| Util.SetGroup]],
[[Utility Functions#Util.ShowGroup| Util.ShowGroup]]

----

=== SetGoalPriority===
Sets priority of one or more MapGoals for specified team and class. The last parameter must be true for dynamically created goals (FLAG_dropped, FLAGRETURN, DEFUSE ...).

'''Parameters:''' (expression or table, priority, teamId[optional, default 0], classId[optional, default 0], persistent[optional])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
example: SetGoalPriority( "FLAG_Gold", 0.7 ); //all teams and all classes
example: SetGoalPriority( "CHECKPOINT_City", 0.8, TEAM.AXIS); //axis only all classes
example: SetGoalPriority( "DEFUSE_somedyno.*", 0.0, TEAM.AXIS, CLASS.ENGINEER, true ); //the persistent parameter is used for dynamic goals that may not have been created yet </syntaxhighlight>

'''See Also:''' [[Priority]]
----

=== SetGoalRole ===
Sets one or more roles of one or more MapGoals. The last parameter must be true for dynamically created goals (FLAG_dropped, FLAGRETURN, DEFUSE ...).

'''Parameters:''' (expression or table, role or table, persistent[optional])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
example: SetGoalRole( "FLAG_Gold", ROLE.ATTACKER ); //1 goal, 1 role
example: SetGoalRole( "DEFEND_City[4567]", { ROLE.DEFENDER2, ROLE.DEFENDER3}); //4 goals, 2 roles
example: SetGoalRole( "DEFUSE_somedyno.*", ROLE.DEFENDER2, true ); //the persistent parameter is used for dynamic goals that may not have been created yet </syntaxhighlight>

'''See Also:''' [[Roles]]
----

=== SetMapGoalProperties===
Passes a table full of properties along to all matching map goals to attempt to set their properties.

'''Parameters:''' (expression or table, table of properties)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Set the camp time for all attack and defend goals
SetMapGoalProperties( "ATTACK_.*", {mincamptime=15, maxcamptime=30});
SetMapGoalProperties( "DEFEND_.*", {mincamptime=15, maxcamptime=30});</syntaxhighlight>

'''See Also:'''
[[Goal specific instructions]] for a list of properties for each map goal type.
----

=== TraceLine ===
Performs a traceline collision test, and returns the results in a table. TraceLine calls are useful for testing visibility, line of sight, or for getting a collision point along a line.

'''Parameters:''' (Vector3 start, Vector3 end, AABB, collision mask, ignore user GameId, use PVS)

* Vector3 start - Start position of trace line.
* Vector3 end - End position of trace line.
* AABB - Pass an AABB if you with the line to have volume, otherwise pass null.
* Collision Mask - Mask of collision types to test. See global [[TRACE]] table.
* GameId - Ignore this GameId in the traceline. Usually the entity or bot it originates from.
* UsePVS - true to use PVS (Potentially visible set), false to ignore PVS

Always pass false to not UsePVS if you need collision information from the call to TraceLine. UsePVS=true is useful when all you need to know is whether or not something is blocking the path from start to end, it will not give you the collision position. It is slightly faster in most cases to use PVS as an early out test, but doing so limits the amount of useful information you get back from the function. In many cases you don't need this information, so the extra speed is useful.

'''Returns:''' table of results

Results table contains the following information.
* fraction - 0.0 to 1.0 The ratio along the line the collision took place. Not always valid if UsePVS=true. Example: 0.5 means ray hit half way between the start and end.
* startsolid - true/false The traceline started inside a solid object. Not always valid if UsePVS=true

Additional properties are available if UsePVS=false and there was a collision.
* entity - May be null, the GameEntity that was hit in the collision.
* normal - The Vector3 normal of the collision point.
* end - The Vector3 world position of the collision.
* contents - water etc., see global [[CONTENT]] table.
* surface - ice, ladder, see global [[SURFACE]] table.

'''Example:''' <syntaxhighlight lang="java">
// Do a traceline along a bots facing 1024 units out
start = b.GetEyePosition();
end = start + b.GetFacing() * 1024;
tr = TraceLine(start, end, null, TRACE.SHOT, b.GetGameId(), false);

// the fraction value tells us of a collision or not. If it's 1, there was no collision. If less than 1 there was a collision.
if(tr.fraction < 1)
{
// tr.startsolid
// tr.entity
// tr.normal
// tr.end
// tr.contents
// tr.surface
}
</syntaxhighlight>

----

== Enemy Territory Addendum ==

=== GetCabinetData ===
Gets information about health or ammo cabinet. Properties CurrentAmount, MaxAmount, Rate are stored into table.

'''Parameters:''' (entity, table)

'''Returns:''' true if successful, null if not

'''Example:''' <syntaxhighlight lang="java">
cab = {};
if (GetCabinetData( GetGoal("AMMOCAB_north").GetEntity(), cab)){
print( cab.CurrentAmount );
}
</syntaxhighlight>

----

=== GetCvar ===
Gets a game cvar. Returns zero if the cvar does not exists or if its value cannot be converted to integer.

'''Parameters:''' (name)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
friendlyFire = GetCvar("g_friendlyfire");</syntaxhighlight>
----

=== GetGameType ===
Gets the current game type:

2 - single-map objective, 3 - stopwatch, 4 - campaign, 5 - last man standing

'''Parameters:''' none

'''Returns:''' integer
----

=== IsWaitingForMedic ===
Deprecated.
----

=== SetCvar ===
Sets a game cvar.

'''Parameters:''' (name, value)

'''Returns:''' true if successful, false if not
----

ScriptGoal

2025-05-25T16:31:46Z

Palota: /* MarkInProgress */

{{process header
| title = Script Goal
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
[[Category:ET|Script Goals]]
[[Category:Doom 3|Script Goals]]
[[Category:Quake 4|Script Goals]]
[[Category:RTCW|Script Goals]]

==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]]

<syntaxhighlight lang="java">this.Name = "MyGoalName";</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Parent = "HighLevel";</syntaxhighlight>

===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]]

<syntaxhighlight lang="java">this.Disable = true;</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.AlwaysRecieveEvents = true;</syntaxhighlight>

===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 [[ScriptGoal#AlwaysRecieveEvents| AlwaysRecieveEvents]], which will allow goals to receive events even when not active.
<syntaxhighlight lang="java">
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) );
};</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Bot.Say("Wassup");</syntaxhighlight>

===Priority===
Priority is a property rather than a return value of [[ScriptGoal#GetPriority| GetPriority]] in order to support the useful threading nature of script goals. It is possible to completely leave out a [[ScriptGoal#GetPriority| 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.

<syntaxhighlight lang="java">this.Priority = 1;</syntaxhighlight>

===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.
<syntaxhighlight lang="java">
this.Commands["command_name"] = {
Func = function( _params )
{
},
Help = { "description" },
};
</syntaxhighlight>

==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:''' <syntaxhighlight lang="java">
this.Initialize() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.OnSpawn() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.GetPriority() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.Enter() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.Exit() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]]
----
===Update===
This function is the meat of a script goal. Once a goal is chosen to run, and [[ScriptGoal#Enter| Enter]] is called, the Update function begins getting called at frequent regular intervals. The state stays active until another goal overrides it, or until [[ScriptGoal#Finished| Finished]] is called, after which the [[ScriptGoal#Exit| Exit]] function is called.

'''Example:''' <syntaxhighlight lang="java">
this.Update() = function()
{
// do stuff
this.Finished(); // when we're done running
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]], [[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.OnPathThrough = function(data)
{
navigation = Map.Navigation[data];
if(navigation)
{
this.CurrentNavigation = data;
return true;
}
this.CurrentNavigation = null;
return false;
};
</syntaxhighlight>

==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
{| align="center" border="1"
!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)
|-
|mapgoalavailable
|No
|MapGoal object or name
|}

=====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
<syntaxhighlight lang="java">
this.AddFinishCriteria(this.TargetEntity,"not hasentflag",ENTFLAG.DEAD); // as soon as the entity does not have the dead flag
</syntaxhighlight>

'''Returns:''' true if criteria was created, false if not

'''Example:''' <syntaxhighlight lang="java">
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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.Finished();</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
//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
};</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToClass(CLASS.MEDIC);
this.LimitToClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoClass(CLASS.MEDIC);
this.LimitToNoClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTeam(TEAM.BLUE);
this.LimitToTeam(TEAM.BLUE, TEAM.RED);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToEntityFlag(ENTFLAG.INWATER);
this.LimitToEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoEntityFlag(ENTFLAG.INWATER);
this.LimitToNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE); </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function takes no parameters.
this.LimitToNoTarget(); </syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToWeapon(WEAPON.MOBILE_MG42);
this.LimitToWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// 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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetTeam(TEAM.RED); // don't run unless our target is on red team</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42);
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.LimitToRole(ROLE.DEFENDER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.GetPriority = function()
{
if(this.IsActive())
{
return 1.0;
}
else
{
// do some other check
}
}; </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
wpinfo = table();
wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
if( this.Goto(wpinfo.position, wpinfo.radius) == EVENT.PATH_SUCCESS )
{
print("Made it!");
}</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
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!");
}</syntaxhighlight>

----

===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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathSucceed())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathFail())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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 - LookAround
* Priority.Low - CAMP, ESCORT, RIDE, MOUNT, ...
* 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:''' <syntaxhighlight lang="java">
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
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseAimRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseAimRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddAimRequest| 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:''' <syntaxhighlight lang="java">
this.AddWeaponRequest(Priority.High, WEAPON.MEDKIT); </syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseWeaponRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.BlockForWeaponChange(WEAPON.MEDKIT);
this.Say("Medkit Equipped!");</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
count = this.QueryGoals(this.Bot.QueryGoalsTable, 0xc9326a43);
count = this.QueryGoals(this.Bot.QueryGoalsTable, "BUILD_.*");</syntaxhighlight>

----

===BlackboardDelay===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.BlackboardDelay(10);</syntaxhighlight>

----

===BlackboardIsDelayed===

'''Parameters:''' (mapGoal or serialNumber)

'''Returns:''' true if goal has been found on blackboard

'''Example:''' <syntaxhighlight lang="java">
if (this.BlackboardIsDelayed(serial))</syntaxhighlight>

----

===MarkInProgress===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
this.MarkInProgress(); //finish if no slot is available

if (!this.MarkInProgress(this.MapGoal)) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===MarkInUse===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
this.MarkInUse(); //finish if no slot is available

if (!this.MarkInUse(this.MapGoal)) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===WatchForMapGoalsInRadius===

----

===ClearWatchForMapGoalsInRadius===

----

===WatchForEntityCategory===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.WatchForEntityCategory({
Radius = 350,
Category = CAT.PROJECTILE,
RequireLOS = TRACE.VISIBLE
});
</syntaxhighlight>

----

===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 [[ScriptGoal#Disable| 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 [[ScriptGoal#BlockForWeaponChange|BlockForWeaponChange]], [[ScriptGoal#Goto|Goto]], [[ScriptGoal#AddAimRequest|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.

ScriptGoal

2025-05-25T16:30:54Z

Palota: /* MarkInUse */

{{process header
| title = Script Goal
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
[[Category:ET|Script Goals]]
[[Category:Doom 3|Script Goals]]
[[Category:Quake 4|Script Goals]]
[[Category:RTCW|Script Goals]]

==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]]

<syntaxhighlight lang="java">this.Name = "MyGoalName";</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Parent = "HighLevel";</syntaxhighlight>

===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]]

<syntaxhighlight lang="java">this.Disable = true;</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.AlwaysRecieveEvents = true;</syntaxhighlight>

===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 [[ScriptGoal#AlwaysRecieveEvents| AlwaysRecieveEvents]], which will allow goals to receive events even when not active.
<syntaxhighlight lang="java">
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) );
};</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Bot.Say("Wassup");</syntaxhighlight>

===Priority===
Priority is a property rather than a return value of [[ScriptGoal#GetPriority| GetPriority]] in order to support the useful threading nature of script goals. It is possible to completely leave out a [[ScriptGoal#GetPriority| 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.

<syntaxhighlight lang="java">this.Priority = 1;</syntaxhighlight>

===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.
<syntaxhighlight lang="java">
this.Commands["command_name"] = {
Func = function( _params )
{
},
Help = { "description" },
};
</syntaxhighlight>

==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:''' <syntaxhighlight lang="java">
this.Initialize() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.OnSpawn() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.GetPriority() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.Enter() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.Exit() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]]
----
===Update===
This function is the meat of a script goal. Once a goal is chosen to run, and [[ScriptGoal#Enter| Enter]] is called, the Update function begins getting called at frequent regular intervals. The state stays active until another goal overrides it, or until [[ScriptGoal#Finished| Finished]] is called, after which the [[ScriptGoal#Exit| Exit]] function is called.

'''Example:''' <syntaxhighlight lang="java">
this.Update() = function()
{
// do stuff
this.Finished(); // when we're done running
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]], [[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.OnPathThrough = function(data)
{
navigation = Map.Navigation[data];
if(navigation)
{
this.CurrentNavigation = data;
return true;
}
this.CurrentNavigation = null;
return false;
};
</syntaxhighlight>

==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
{| align="center" border="1"
!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)
|-
|mapgoalavailable
|No
|MapGoal object or name
|}

=====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
<syntaxhighlight lang="java">
this.AddFinishCriteria(this.TargetEntity,"not hasentflag",ENTFLAG.DEAD); // as soon as the entity does not have the dead flag
</syntaxhighlight>

'''Returns:''' true if criteria was created, false if not

'''Example:''' <syntaxhighlight lang="java">
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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.Finished();</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
//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
};</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToClass(CLASS.MEDIC);
this.LimitToClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoClass(CLASS.MEDIC);
this.LimitToNoClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTeam(TEAM.BLUE);
this.LimitToTeam(TEAM.BLUE, TEAM.RED);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToEntityFlag(ENTFLAG.INWATER);
this.LimitToEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoEntityFlag(ENTFLAG.INWATER);
this.LimitToNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE); </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function takes no parameters.
this.LimitToNoTarget(); </syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToWeapon(WEAPON.MOBILE_MG42);
this.LimitToWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// 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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetTeam(TEAM.RED); // don't run unless our target is on red team</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42);
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.LimitToRole(ROLE.DEFENDER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.GetPriority = function()
{
if(this.IsActive())
{
return 1.0;
}
else
{
// do some other check
}
}; </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
wpinfo = table();
wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
if( this.Goto(wpinfo.position, wpinfo.radius) == EVENT.PATH_SUCCESS )
{
print("Made it!");
}</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
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!");
}</syntaxhighlight>

----

===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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathSucceed())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathFail())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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 - LookAround
* Priority.Low - CAMP, ESCORT, RIDE, MOUNT, ...
* 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:''' <syntaxhighlight lang="java">
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
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseAimRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseAimRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddAimRequest| 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:''' <syntaxhighlight lang="java">
this.AddWeaponRequest(Priority.High, WEAPON.MEDKIT); </syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseWeaponRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.BlockForWeaponChange(WEAPON.MEDKIT);
this.Say("Medkit Equipped!");</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
count = this.QueryGoals(this.Bot.QueryGoalsTable, 0xc9326a43);
count = this.QueryGoals(this.Bot.QueryGoalsTable, "BUILD_.*");</syntaxhighlight>

----

===BlackboardDelay===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.BlackboardDelay(10);</syntaxhighlight>

----

===BlackboardIsDelayed===

'''Parameters:''' (mapGoal or serialNumber)

'''Returns:''' true if goal has been found on blackboard

'''Example:''' <syntaxhighlight lang="java">
if (this.BlackboardIsDelayed(serial))</syntaxhighlight>

----

===MarkInProgress===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
if (!this.MarkInProgress()) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===MarkInUse===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
this.MarkInUse(); //finish if no slot is available

if (!this.MarkInUse(this.MapGoal)) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===WatchForMapGoalsInRadius===

----

===ClearWatchForMapGoalsInRadius===

----

===WatchForEntityCategory===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.WatchForEntityCategory({
Radius = 350,
Category = CAT.PROJECTILE,
RequireLOS = TRACE.VISIBLE
});
</syntaxhighlight>

----

===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 [[ScriptGoal#Disable| 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 [[ScriptGoal#BlockForWeaponChange|BlockForWeaponChange]], [[ScriptGoal#Goto|Goto]], [[ScriptGoal#AddAimRequest|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.

MapGoal

2025-05-25T16:22:06Z

Palota: /* ClearRoles */

{{process header
| title = MapGoal Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Map Goal Properties==
----
===CreateOnLoad===
False to not create the goal at load time, but keep the data around for when created by the interface.

----
===DefaultPriority===
Default priority of the goal, if no class/team specific priorities.

----
===DefaultRenderHeight===
Goal height offset where rendering will take place.

----
===DefaultRenderRadius===
Maximal distance from player to display text (goal options).

----
===DisableForControllingTeam===
Goal will be made unavailable for the team which controls it (GetOwner). It is used by CHECKPOINT goal.

----
===DontSave===
Don't save this goal into the map goal script.

----
===DynamicOrientation===
Goal should update its orientation from its entity. It is used by BUILD goal to repair vehicles.

----
===DynamicPosition===
Goal should update its position from its entity. It is used by BUILD goal to repair vehicles.

----
===ExtraDebugText===
Additional debug text to render in RenderDefault function.

----
===GoalState===
Gets the goal state.

----
===GoalStateFunction===
internal

----
===GoalType===
Type of goal.

----
===InUse===
Goal is inuse and should not be chosen.

----
===MarkForRemoval===
Mark the goal for deletion.

----
===MinRadius===
Minimum allowed radius of the goal.

----
===Radius===
Radius of the goal.

----
===RemoveWithEntity===
Goal should be removed if its entity is removed. Default is true. It is used by FLAG, FLAGRETURN, DEFUSE goals.

----
===RenderDefaultCurrentAvailability===
Draw the current availability of the goal.

----
===RenderDefaultGroup===
Draw the group of the goal.

----
===RenderDefaultInitialAvailability===
Draw the initial availability of the goal.

----
===RenderDefaultName===
Draw the name of the goal.

----
===RenderDefaultRadius===
Draw the radius of the goal.

----
===RenderDefaultRole===
Draw the roles for the goal.

----
===RenderGoal===
Enable rendering for this goal. It is set by console command /bot draw_goals

----
===RenderRandomUsePoint===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRangeLimit===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRoutes===
Enable rendering of the routes for this goal. It is set by console command /bot draw_goalroutes

'''See:'''
[[Template:Baserouting|Routing]]

----

===RolePriorityBonus===
Role priority bonus of the goal, for users matching role.

'''See:'''
[[Roles]]

----

===Version===
Gets the goal version. Omni-bot 0.8 sets goal version to 1.

----
===SerialNum===
Auto generated unique serial number of the goal.

----

==Map Goal Callbacks==
----
===InitNewGoal===
Called on goal creation (command /bot goal_create) to initialize any internal variables and set properties to default values.
For example, camping goals can initialize aim vectors to the player facing.

----
===UpgradeVersion===
Called after the goal properties have been loaded from a goals file. This function should validate schema and upgrade the goal to the latest used version.

----
===Render===
Called when draw_goals is enabled for this goal. Used to render itself.

----
===Update===
Called every frame to update the state of the goal if needed. For example, GRENADE goal calls TraceLine function to check if the goal has been destroyed.

----
===SaveToTable===
Called when the goals are saved to a file. Allows the goal to serialize persistent information.

----
===SetProperty===
Called on command /bot goal_setproperty x y, where x is a property name and y is a value or keyword.

----
===Help===
Called on commands /bot goal_help or /bot goal_create to print requirements and available properties for the goal.

----
===HudDisplay===
Called when debug window is enabled and goal is highlighted to create gui elements for debug visualization.

----

==Map Goal Functions==
----
===AddRoute===
'''See:'''
[[Template:Baserouting|Routing]]

'''Parameters:''' (start, end, weight)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddRoute("ROUTE_spawn", "ROUTE_gate", 1.0);</syntaxhighlight>

'''Utility function:''' Util.Routes
----

===AddUsePoint===
Adds a use point to the goal. Use points are used by RouteTo function. The goal can have multiple use points. Bots choose the nearest use point if goal property RandomUsePoint is false.

'''Parameters:''' (Vector3, relative[optional, default false])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddUsePoint(Vector3(10,50,0), true);</syntaxhighlight>

'''Utility functions:''' Util.AddUsePoint, Util.AddUseWp

----
===ClearRoles===
Removes the given roles from this goal.

'''Parameters:''' (roleId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ClearRoles(ROLE.DEFENDER1, ROLE.DEFENDER2);</syntaxhighlight>

'''Utility functions:''' ClearGoalRole, Util.ClearRoleForGroup, Util.ClearRoleForTable

'''See:''' [[Roles]]

----

===ClearUsePoints===
Deletes all use points of the map goal.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ClearUsePoints();</syntaxhighlight>

----

===CreateGuiFromSchema===
Used in HudDisplay callback if debug window is enabled.

'''Example:''' <syntaxhighlight lang="java">
this.CreateGuiFromSchema(this.Schema);</syntaxhighlight>

----
===DeleteIfEntityFlag===
Sets one or more entity flags that will cause the goal to be deleted.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DeleteIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===DisableGoal===
Sets whether the goal is currently disabled.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableGoal(true);</syntaxhighlight>

----
===DisableIfEntityFlag===
Sets one or more entity flags that will cause the goal to be disabled.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===GetCenterBounds===
Gets the center of the bounding box.

'''Parameters:''' none

'''Returns:''' Vector3

'''Example:''' <syntaxhighlight lang="java">
center = mg.GetCenterBounds();</syntaxhighlight>

----
===GetEntity===
Gets the entity of the map goal.

'''Parameters:''' none

'''Returns:''' GameEntity

'''Example:''' <syntaxhighlight lang="java">
ent = mg.GetEntity();</syntaxhighlight>

----
===GetFacing===
Gets the facing of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 facing

'''Example:''' <syntaxhighlight lang="java">
face = mg.GetFacing();</syntaxhighlight>

----
===GetGoalPriority===
Gets the priority for a given class/team. Default priority is returned if class or team is 0.

If the parameter is bot, role priority bonus is added if the bot has any of the goals roles.

'''Parameters:''' (bot)

'''Parameters:''' (teamId, classId)

'''Returns:''' float

'''Example:''' <syntaxhighlight lang="java">
priority = mg.GetGoalPriority(bot);
// OR
priority = mg.GetGoalPriority(TEAM.AXIS,CLASS.MEDIC);</syntaxhighlight>

----
===GetGoalState===
Gets the goal state of the map goal.

'''Parameters:''' none

'''Returns:''' goal state id

'''Example:''' <syntaxhighlight lang="java">
state = mg.GetGoalState();</syntaxhighlight>

----
===GetGoalType===
Gets goal type. Examples: Attack, BUILD, CapPoint, PLANT.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetGoalType();</syntaxhighlight>

----
===GetGroupName===
Gets the current group this goal is assigned to.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
group = mg.GetGroupName();</syntaxhighlight>

----
===GetName===
Gets the name of the map goal.

'''Parameters:''' none

'''Returns:''' name of mapgoal

'''Example:''' <syntaxhighlight lang="java">
name = mg.GetName();</syntaxhighlight>

----
===GetNumUsePoint===
Gets the number of use points the goal has.

'''Parameters:''' none

'''Returns:''' # use points

'''Example:''' <syntaxhighlight lang="java">
n = mg.GetNumUsePoint();</syntaxhighlight>

----
===GetOwner===
Gets the owner of the map goal. Typically someone that is carrying it.

'''Parameters:''' none

'''Returns:''' Owner GameId, or null if no owner

'''Example:''' <syntaxhighlight lang="java">
owner = mg.GetOwner();</syntaxhighlight>

----
===GetPosition===
Gets the position of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 position

'''Example:''' <syntaxhighlight lang="java">
pos = mg.GetPosition();</syntaxhighlight>

----
===GetRadius===
Gets the radius of the map goal.

'''Parameters:''' none

'''Returns:''' float radius

'''Example:''' <syntaxhighlight lang="java">
radius = mg.GetRadius();</syntaxhighlight>

----

===GetRange===
Get current radius limit for the map goal or 0.

'''Parameters:''' none

'''Returns:''' int radius

'''Example:''' <syntaxhighlight lang="java">
range = mg.GetRange();</syntaxhighlight>

----

===GetRangeAABB===
Get current AABB range limit for the map goal or null.

'''Parameters:''' none

'''Returns:''' AABB or null

'''Example:''' <syntaxhighlight lang="java">
range = mg.GetRangeAABB();</syntaxhighlight>

----

===GetTagName===
Gets the tag name of the map goal. This is usually a mash of the entity name and goal type.

'''Parameters:''' none

'''Returns:''' tag name

'''Example:''' <syntaxhighlight lang="java">
tag = mg.GetTagName();</syntaxhighlight>

----
===GetTypeName===
Gets the type name of the map goal.

'''Parameters:''' none

'''Returns:''' type name

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetTypeName();</syntaxhighlight>

----
===GetUsePoint===
Gets a use point, by index. If no index provided, returns a random one.

'''Parameters:''' (index<optional>)

'''Returns:''' Vector3 use point

'''Example:''' <syntaxhighlight lang="java">
pt = mg.GetUsePoint();
// OR
pt = mg.GetUsePoint(2);</syntaxhighlight>

----
===HasRole===
Returns true if the goal has any of the roles provided as parameters.

'''Parameters:''' (roleId, ...)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.HasRole(ROLE.ATTACKER))
{
}</syntaxhighlight>

'''See:''' [[Roles]]

----

===IsAvailable===
Checks if the map goal is currently available to a certain team.

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsAvailable(TEAM.RED))
{
}</syntaxhighlight>

----
===IsAvailableInitial===
Is goal available for team initially (before OnMapLoad is executed).

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if (mg.IsAvailableInitial(TEAM.RED))
{
}</syntaxhighlight>

----
===IsDisabled===
Gets whether the goal is currently disabled.

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsDisabled())
{
}</syntaxhighlight>

----
===LimitToWeapon===
Adds a list of weapons that are required from any user of the goal.

Warning: This function does not work for weapons that have ID greater than 63.

'''Parameters:''' (weaponId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.LimitToWeapon(WEAPON.FG42);</syntaxhighlight>

----
===MaxUsers_InProgress===
Get or set the max number of users that can go to the goal.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InProgress();
// OR
mg.MaxUsers_InProgress(2);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInProgress, Util.GetMaxUsersInProgress, Util.SetPercentInProgress

----
===MaxUsers_InUse===
Get or set the max number of users that can use the goal after they come to the goal position.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InUse();
// OR
mg.MaxUsers_InUse(1);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInUse, Util.GetMaxUsersInUse

----
===RenderDefault===
Draws goal name, radius, availability, use points, ExtraDebugText, ...

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.RenderDefault();</syntaxhighlight>

----
===ResetGoalPriorities===
Clears all the current priorities.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ResetGoalPriorities();</syntaxhighlight>

----
===SetAvailable===
Sets the map goal available for a certain team.

NOTE: Map scripts usually use global function SetAvailableMapGoals instead of calling SetAvailable directly on map goal object.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailable(TEAM.RED, false);</syntaxhighlight>

----
===SetAvailableInitial===
Sets goal available for team initially.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailableInitial(TEAM.AXIS, true);</syntaxhighlight>

----
===SetBaseGoalType===
Clones a base goal type. Should be done first thing in goal script.

'''Parameters:''' (fileName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.SetBaseGoalType("mapgoal_camp.gm");</syntaxhighlight>

----
===SetEntity===
Sets the entity for a map goal. It is usually not needed because most entities are detected automatically.

'''Parameters:''' (entity)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
GetGoal("MOUNTMG42_assault_tower_mg").SetEntity(GetEntityByName("assault_tower_mg"));;</syntaxhighlight>

----
===SetFacing===
Sets the facing for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetFacing(Vector3(1,0,0));</syntaxhighlight>

----
===SetGoalPriority===
Sets the priority for a given class/team. The first parameter can be 0 to set priority for all teams. The second parameter can be 0 to set priority for all classes.

NOTE: Map scripts usually use global function SetGoalPriority instead of calling SetGoalPriority directly on map goal object.

'''Parameters:''' (teamId, classId, priority)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGoalPriority(TEAM.ALLIES, CLASS.SOLDIER, 0.8);</syntaxhighlight>

----
===SetGroupName===
Sets the current group this goal is assigned to.

'''Parameters:''' (groupName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGroupName("group1");</syntaxhighlight>

----
===SetPosition===
Sets the position for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetPosition(Vector3(10,10,10));</syntaxhighlight>

----
===SetRadius===
Sets the radius for a map goal.

'''Parameters:''' (radius)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRadius(65);</syntaxhighlight>

----
===SetRange===
Sets the range for a script based map goal. It can be int radius or AABB box or both. The QueryGoals functions does not return goals which are out of range. Default range for all goals is unlimited. Goals will not be interrupted if the range changes after the bot has already activated the goal.

'''Parameters:''' (int or AABB)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRange(1000);
mg.SetRange(AABB(1369,2165,30, 4100,3700,350));

//reset to unlimited
mg.SetRange(0);
mg.SetRange(AABB());
</syntaxhighlight>

'''Utility function:''' Util.SetGoalRange
----

===SetRemoveFlag===
Marks the goal for removal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRemoveFlag(true);</syntaxhighlight>

----
===SetRoles===
Sets the roles that are allowed to use this goal.

'''Parameters:''' (roleId or table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''Utility functions:''' SetGoalRole, Util.SetRoleForGroup

'''See:''' [[Roles]]

----

==Obsolete Functions==

===GetBounds===
Gets the AABB bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB

'''Example:''' <syntaxhighlight lang="java">
bounds = mg.GetBounds();</syntaxhighlight>

----
===GetLocalBounds===
Gets the local space bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB bounds

'''Example:''' <syntaxhighlight lang="java">
localbounds = mg.GetLocalBounds();</syntaxhighlight>

----
===GetMatrix===
Gets the Matrix3 transform of the map goal.

'''Parameters:''' none

'''Returns:''' Matrix3 transform

'''Example:''' <syntaxhighlight lang="java">
m = mg.GetMatrix();</syntaxhighlight>

----
===SetEnableDraw===
Enables debug rendering for this map goal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetEnableDraw(true);</syntaxhighlight>

----
===SetMatrix===
Sets the matrix for a map goal.

'''Parameters:''' (Matrix3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
m = Matrix3();
// initialize it somehow
mg.SetMatrix(m);</syntaxhighlight>

----

MapGoal

2025-05-25T16:19:26Z

Palota: /* GetRange, GetRangeAABB */

{{process header
| title = MapGoal Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Map Goal Properties==
----
===CreateOnLoad===
False to not create the goal at load time, but keep the data around for when created by the interface.

----
===DefaultPriority===
Default priority of the goal, if no class/team specific priorities.

----
===DefaultRenderHeight===
Goal height offset where rendering will take place.

----
===DefaultRenderRadius===
Maximal distance from player to display text (goal options).

----
===DisableForControllingTeam===
Goal will be made unavailable for the team which controls it (GetOwner). It is used by CHECKPOINT goal.

----
===DontSave===
Don't save this goal into the map goal script.

----
===DynamicOrientation===
Goal should update its orientation from its entity. It is used by BUILD goal to repair vehicles.

----
===DynamicPosition===
Goal should update its position from its entity. It is used by BUILD goal to repair vehicles.

----
===ExtraDebugText===
Additional debug text to render in RenderDefault function.

----
===GoalState===
Gets the goal state.

----
===GoalStateFunction===
internal

----
===GoalType===
Type of goal.

----
===InUse===
Goal is inuse and should not be chosen.

----
===MarkForRemoval===
Mark the goal for deletion.

----
===MinRadius===
Minimum allowed radius of the goal.

----
===Radius===
Radius of the goal.

----
===RemoveWithEntity===
Goal should be removed if its entity is removed. Default is true. It is used by FLAG, FLAGRETURN, DEFUSE goals.

----
===RenderDefaultCurrentAvailability===
Draw the current availability of the goal.

----
===RenderDefaultGroup===
Draw the group of the goal.

----
===RenderDefaultInitialAvailability===
Draw the initial availability of the goal.

----
===RenderDefaultName===
Draw the name of the goal.

----
===RenderDefaultRadius===
Draw the radius of the goal.

----
===RenderDefaultRole===
Draw the roles for the goal.

----
===RenderGoal===
Enable rendering for this goal. It is set by console command /bot draw_goals

----
===RenderRandomUsePoint===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRangeLimit===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRoutes===
Enable rendering of the routes for this goal. It is set by console command /bot draw_goalroutes

'''See:'''
[[Template:Baserouting|Routing]]

----

===RolePriorityBonus===
Role priority bonus of the goal, for users matching role.

'''See:'''
[[Roles]]

----

===Version===
Gets the goal version. Omni-bot 0.8 sets goal version to 1.

----
===SerialNum===
Auto generated unique serial number of the goal.

----

==Map Goal Callbacks==
----
===InitNewGoal===
Called on goal creation (command /bot goal_create) to initialize any internal variables and set properties to default values.
For example, camping goals can initialize aim vectors to the player facing.

----
===UpgradeVersion===
Called after the goal properties have been loaded from a goals file. This function should validate schema and upgrade the goal to the latest used version.

----
===Render===
Called when draw_goals is enabled for this goal. Used to render itself.

----
===Update===
Called every frame to update the state of the goal if needed. For example, GRENADE goal calls TraceLine function to check if the goal has been destroyed.

----
===SaveToTable===
Called when the goals are saved to a file. Allows the goal to serialize persistent information.

----
===SetProperty===
Called on command /bot goal_setproperty x y, where x is a property name and y is a value or keyword.

----
===Help===
Called on commands /bot goal_help or /bot goal_create to print requirements and available properties for the goal.

----
===HudDisplay===
Called when debug window is enabled and goal is highlighted to create gui elements for debug visualization.

----

==Map Goal Functions==
----
===AddRoute===
'''See:'''
[[Template:Baserouting|Routing]]

'''Parameters:''' (start, end, weight)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddRoute("ROUTE_spawn", "ROUTE_gate", 1.0);</syntaxhighlight>

'''Utility function:''' Util.Routes
----

===AddUsePoint===
Adds a use point to the goal. Use points are used by RouteTo function. The goal can have multiple use points. Bots choose the nearest use point if goal property RandomUsePoint is false.

'''Parameters:''' (Vector3, relative[optional, default false])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddUsePoint(Vector3(10,50,0), true);</syntaxhighlight>

'''Utility functions:''' Util.AddUsePoint, Util.AddUseWp

----
===ClearRoles===
Removes the given roles from this goal.

'''Parameters:''' (roleId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ClearRoles(ROLE.DEFENDER1, ROLE.DEFENDER2);</syntaxhighlight>

'''Utility functions:''' ClearGoalRole, Util.ClearRoleForGroup, Util.ClearRoleForTable

'''See:''' [[Roles]]

----

===CreateGuiFromSchema===
Used in HudDisplay callback if debug window is enabled.

'''Example:''' <syntaxhighlight lang="java">
this.CreateGuiFromSchema(this.Schema);</syntaxhighlight>

----
===DeleteIfEntityFlag===
Sets one or more entity flags that will cause the goal to be deleted.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DeleteIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===DisableGoal===
Sets whether the goal is currently disabled.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableGoal(true);</syntaxhighlight>

----
===DisableIfEntityFlag===
Sets one or more entity flags that will cause the goal to be disabled.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===GetCenterBounds===
Gets the center of the bounding box.

'''Parameters:''' none

'''Returns:''' Vector3

'''Example:''' <syntaxhighlight lang="java">
center = mg.GetCenterBounds();</syntaxhighlight>

----
===GetEntity===
Gets the entity of the map goal.

'''Parameters:''' none

'''Returns:''' GameEntity

'''Example:''' <syntaxhighlight lang="java">
ent = mg.GetEntity();</syntaxhighlight>

----
===GetFacing===
Gets the facing of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 facing

'''Example:''' <syntaxhighlight lang="java">
face = mg.GetFacing();</syntaxhighlight>

----
===GetGoalPriority===
Gets the priority for a given class/team. Default priority is returned if class or team is 0.

If the parameter is bot, role priority bonus is added if the bot has any of the goals roles.

'''Parameters:''' (bot)

'''Parameters:''' (teamId, classId)

'''Returns:''' float

'''Example:''' <syntaxhighlight lang="java">
priority = mg.GetGoalPriority(bot);
// OR
priority = mg.GetGoalPriority(TEAM.AXIS,CLASS.MEDIC);</syntaxhighlight>

----
===GetGoalState===
Gets the goal state of the map goal.

'''Parameters:''' none

'''Returns:''' goal state id

'''Example:''' <syntaxhighlight lang="java">
state = mg.GetGoalState();</syntaxhighlight>

----
===GetGoalType===
Gets goal type. Examples: Attack, BUILD, CapPoint, PLANT.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetGoalType();</syntaxhighlight>

----
===GetGroupName===
Gets the current group this goal is assigned to.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
group = mg.GetGroupName();</syntaxhighlight>

----
===GetName===
Gets the name of the map goal.

'''Parameters:''' none

'''Returns:''' name of mapgoal

'''Example:''' <syntaxhighlight lang="java">
name = mg.GetName();</syntaxhighlight>

----
===GetNumUsePoint===
Gets the number of use points the goal has.

'''Parameters:''' none

'''Returns:''' # use points

'''Example:''' <syntaxhighlight lang="java">
n = mg.GetNumUsePoint();</syntaxhighlight>

----
===GetOwner===
Gets the owner of the map goal. Typically someone that is carrying it.

'''Parameters:''' none

'''Returns:''' Owner GameId, or null if no owner

'''Example:''' <syntaxhighlight lang="java">
owner = mg.GetOwner();</syntaxhighlight>

----
===GetPosition===
Gets the position of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 position

'''Example:''' <syntaxhighlight lang="java">
pos = mg.GetPosition();</syntaxhighlight>

----
===GetRadius===
Gets the radius of the map goal.

'''Parameters:''' none

'''Returns:''' float radius

'''Example:''' <syntaxhighlight lang="java">
radius = mg.GetRadius();</syntaxhighlight>

----

===GetRange===
Get current radius limit for the map goal or 0.

'''Parameters:''' none

'''Returns:''' int radius

'''Example:''' <syntaxhighlight lang="java">
range = mg.GetRange();</syntaxhighlight>

----

===GetRangeAABB===
Get current AABB range limit for the map goal or null.

'''Parameters:''' none

'''Returns:''' AABB or null

'''Example:''' <syntaxhighlight lang="java">
range = mg.GetRangeAABB();</syntaxhighlight>

----

===GetTagName===
Gets the tag name of the map goal. This is usually a mash of the entity name and goal type.

'''Parameters:''' none

'''Returns:''' tag name

'''Example:''' <syntaxhighlight lang="java">
tag = mg.GetTagName();</syntaxhighlight>

----
===GetTypeName===
Gets the type name of the map goal.

'''Parameters:''' none

'''Returns:''' type name

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetTypeName();</syntaxhighlight>

----
===GetUsePoint===
Gets a use point, by index. If no index provided, returns a random one.

'''Parameters:''' (index<optional>)

'''Returns:''' Vector3 use point

'''Example:''' <syntaxhighlight lang="java">
pt = mg.GetUsePoint();
// OR
pt = mg.GetUsePoint(2);</syntaxhighlight>

----
===HasRole===
Returns true if the goal has any of the roles provided as parameters.

'''Parameters:''' (roleId, ...)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.HasRole(ROLE.ATTACKER))
{
}</syntaxhighlight>

'''See:''' [[Roles]]

----

===IsAvailable===
Checks if the map goal is currently available to a certain team.

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsAvailable(TEAM.RED))
{
}</syntaxhighlight>

----
===IsAvailableInitial===
Is goal available for team initially (before OnMapLoad is executed).

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if (mg.IsAvailableInitial(TEAM.RED))
{
}</syntaxhighlight>

----
===IsDisabled===
Gets whether the goal is currently disabled.

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsDisabled())
{
}</syntaxhighlight>

----
===LimitToWeapon===
Adds a list of weapons that are required from any user of the goal.

Warning: This function does not work for weapons that have ID greater than 63.

'''Parameters:''' (weaponId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.LimitToWeapon(WEAPON.FG42);</syntaxhighlight>

----
===MaxUsers_InProgress===
Get or set the max number of users that can go to the goal.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InProgress();
// OR
mg.MaxUsers_InProgress(2);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInProgress, Util.GetMaxUsersInProgress, Util.SetPercentInProgress

----
===MaxUsers_InUse===
Get or set the max number of users that can use the goal after they come to the goal position.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InUse();
// OR
mg.MaxUsers_InUse(1);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInUse, Util.GetMaxUsersInUse

----
===RenderDefault===
Draws goal name, radius, availability, use points, ExtraDebugText, ...

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.RenderDefault();</syntaxhighlight>

----
===ResetGoalPriorities===
Clears all the current priorities.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ResetGoalPriorities();</syntaxhighlight>

----
===SetAvailable===
Sets the map goal available for a certain team.

NOTE: Map scripts usually use global function SetAvailableMapGoals instead of calling SetAvailable directly on map goal object.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailable(TEAM.RED, false);</syntaxhighlight>

----
===SetAvailableInitial===
Sets goal available for team initially.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailableInitial(TEAM.AXIS, true);</syntaxhighlight>

----
===SetBaseGoalType===
Clones a base goal type. Should be done first thing in goal script.

'''Parameters:''' (fileName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.SetBaseGoalType("mapgoal_camp.gm");</syntaxhighlight>

----
===SetEntity===
Sets the entity for a map goal. It is usually not needed because most entities are detected automatically.

'''Parameters:''' (entity)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
GetGoal("MOUNTMG42_assault_tower_mg").SetEntity(GetEntityByName("assault_tower_mg"));;</syntaxhighlight>

----
===SetFacing===
Sets the facing for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetFacing(Vector3(1,0,0));</syntaxhighlight>

----
===SetGoalPriority===
Sets the priority for a given class/team. The first parameter can be 0 to set priority for all teams. The second parameter can be 0 to set priority for all classes.

NOTE: Map scripts usually use global function SetGoalPriority instead of calling SetGoalPriority directly on map goal object.

'''Parameters:''' (teamId, classId, priority)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGoalPriority(TEAM.ALLIES, CLASS.SOLDIER, 0.8);</syntaxhighlight>

----
===SetGroupName===
Sets the current group this goal is assigned to.

'''Parameters:''' (groupName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGroupName("group1");</syntaxhighlight>

----
===SetPosition===
Sets the position for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetPosition(Vector3(10,10,10));</syntaxhighlight>

----
===SetRadius===
Sets the radius for a map goal.

'''Parameters:''' (radius)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRadius(65);</syntaxhighlight>

----
===SetRange===
Sets the range for a script based map goal. It can be int radius or AABB box or both. The QueryGoals functions does not return goals which are out of range. Default range for all goals is unlimited. Goals will not be interrupted if the range changes after the bot has already activated the goal.

'''Parameters:''' (int or AABB)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRange(1000);
mg.SetRange(AABB(1369,2165,30, 4100,3700,350));

//reset to unlimited
mg.SetRange(0);
mg.SetRange(AABB());
</syntaxhighlight>

'''Utility function:''' Util.SetGoalRange
----

===SetRemoveFlag===
Marks the goal for removal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRemoveFlag(true);</syntaxhighlight>

----
===SetRoles===
Sets the roles that are allowed to use this goal.

'''Parameters:''' (roleId or table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''Utility functions:''' SetGoalRole, Util.SetRoleForGroup

'''See:''' [[Roles]]

----

==Obsolete Functions==

===GetBounds===
Gets the AABB bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB

'''Example:''' <syntaxhighlight lang="java">
bounds = mg.GetBounds();</syntaxhighlight>

----
===GetLocalBounds===
Gets the local space bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB bounds

'''Example:''' <syntaxhighlight lang="java">
localbounds = mg.GetLocalBounds();</syntaxhighlight>

----
===GetMatrix===
Gets the Matrix3 transform of the map goal.

'''Parameters:''' none

'''Returns:''' Matrix3 transform

'''Example:''' <syntaxhighlight lang="java">
m = mg.GetMatrix();</syntaxhighlight>

----
===SetEnableDraw===
Enables debug rendering for this map goal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetEnableDraw(true);</syntaxhighlight>

----
===SetMatrix===
Sets the matrix for a map goal.

'''Parameters:''' (Matrix3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
m = Matrix3();
// initialize it somehow
mg.SetMatrix(m);</syntaxhighlight>

----

MapGoal

2025-05-25T16:14:44Z

Palota: /* SetRange */

{{process header
| title = MapGoal Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Map Goal Properties==
----
===CreateOnLoad===
False to not create the goal at load time, but keep the data around for when created by the interface.

----
===DefaultPriority===
Default priority of the goal, if no class/team specific priorities.

----
===DefaultRenderHeight===
Goal height offset where rendering will take place.

----
===DefaultRenderRadius===
Maximal distance from player to display text (goal options).

----
===DisableForControllingTeam===
Goal will be made unavailable for the team which controls it (GetOwner). It is used by CHECKPOINT goal.

----
===DontSave===
Don't save this goal into the map goal script.

----
===DynamicOrientation===
Goal should update its orientation from its entity. It is used by BUILD goal to repair vehicles.

----
===DynamicPosition===
Goal should update its position from its entity. It is used by BUILD goal to repair vehicles.

----
===ExtraDebugText===
Additional debug text to render in RenderDefault function.

----
===GoalState===
Gets the goal state.

----
===GoalStateFunction===
internal

----
===GoalType===
Type of goal.

----
===InUse===
Goal is inuse and should not be chosen.

----
===MarkForRemoval===
Mark the goal for deletion.

----
===MinRadius===
Minimum allowed radius of the goal.

----
===Radius===
Radius of the goal.

----
===RemoveWithEntity===
Goal should be removed if its entity is removed. Default is true. It is used by FLAG, FLAGRETURN, DEFUSE goals.

----
===RenderDefaultCurrentAvailability===
Draw the current availability of the goal.

----
===RenderDefaultGroup===
Draw the group of the goal.

----
===RenderDefaultInitialAvailability===
Draw the initial availability of the goal.

----
===RenderDefaultName===
Draw the name of the goal.

----
===RenderDefaultRadius===
Draw the radius of the goal.

----
===RenderDefaultRole===
Draw the roles for the goal.

----
===RenderGoal===
Enable rendering for this goal. It is set by console command /bot draw_goals

----
===RenderRandomUsePoint===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRangeLimit===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRoutes===
Enable rendering of the routes for this goal. It is set by console command /bot draw_goalroutes

'''See:'''
[[Template:Baserouting|Routing]]

----

===RolePriorityBonus===
Role priority bonus of the goal, for users matching role.

'''See:'''
[[Roles]]

----

===Version===
Gets the goal version. Omni-bot 0.8 sets goal version to 1.

----
===SerialNum===
Auto generated unique serial number of the goal.

----

==Map Goal Callbacks==
----
===InitNewGoal===
Called on goal creation (command /bot goal_create) to initialize any internal variables and set properties to default values.
For example, camping goals can initialize aim vectors to the player facing.

----
===UpgradeVersion===
Called after the goal properties have been loaded from a goals file. This function should validate schema and upgrade the goal to the latest used version.

----
===Render===
Called when draw_goals is enabled for this goal. Used to render itself.

----
===Update===
Called every frame to update the state of the goal if needed. For example, GRENADE goal calls TraceLine function to check if the goal has been destroyed.

----
===SaveToTable===
Called when the goals are saved to a file. Allows the goal to serialize persistent information.

----
===SetProperty===
Called on command /bot goal_setproperty x y, where x is a property name and y is a value or keyword.

----
===Help===
Called on commands /bot goal_help or /bot goal_create to print requirements and available properties for the goal.

----
===HudDisplay===
Called when debug window is enabled and goal is highlighted to create gui elements for debug visualization.

----

==Map Goal Functions==
----
===AddRoute===
'''See:'''
[[Template:Baserouting|Routing]]

'''Parameters:''' (start, end, weight)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddRoute("ROUTE_spawn", "ROUTE_gate", 1.0);</syntaxhighlight>

'''Utility function:''' Util.Routes
----

===AddUsePoint===
Adds a use point to the goal. Use points are used by RouteTo function. The goal can have multiple use points. Bots choose the nearest use point if goal property RandomUsePoint is false.

'''Parameters:''' (Vector3, relative[optional, default false])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddUsePoint(Vector3(10,50,0), true);</syntaxhighlight>

'''Utility functions:''' Util.AddUsePoint, Util.AddUseWp

----
===ClearRoles===
Removes the given roles from this goal.

'''Parameters:''' (roleId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ClearRoles(ROLE.DEFENDER1, ROLE.DEFENDER2);</syntaxhighlight>

'''Utility functions:''' ClearGoalRole, Util.ClearRoleForGroup, Util.ClearRoleForTable

'''See:''' [[Roles]]

----

===CreateGuiFromSchema===
Used in HudDisplay callback if debug window is enabled.

'''Example:''' <syntaxhighlight lang="java">
this.CreateGuiFromSchema(this.Schema);</syntaxhighlight>

----
===DeleteIfEntityFlag===
Sets one or more entity flags that will cause the goal to be deleted.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DeleteIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===DisableGoal===
Sets whether the goal is currently disabled.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableGoal(true);</syntaxhighlight>

----
===DisableIfEntityFlag===
Sets one or more entity flags that will cause the goal to be disabled.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===GetCenterBounds===
Gets the center of the bounding box.

'''Parameters:''' none

'''Returns:''' Vector3

'''Example:''' <syntaxhighlight lang="java">
center = mg.GetCenterBounds();</syntaxhighlight>

----
===GetEntity===
Gets the entity of the map goal.

'''Parameters:''' none

'''Returns:''' GameEntity

'''Example:''' <syntaxhighlight lang="java">
ent = mg.GetEntity();</syntaxhighlight>

----
===GetFacing===
Gets the facing of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 facing

'''Example:''' <syntaxhighlight lang="java">
face = mg.GetFacing();</syntaxhighlight>

----
===GetGoalPriority===
Gets the priority for a given class/team. Default priority is returned if class or team is 0.

If the parameter is bot, role priority bonus is added if the bot has any of the goals roles.

'''Parameters:''' (bot)

'''Parameters:''' (teamId, classId)

'''Returns:''' float

'''Example:''' <syntaxhighlight lang="java">
priority = mg.GetGoalPriority(bot);
// OR
priority = mg.GetGoalPriority(TEAM.AXIS,CLASS.MEDIC);</syntaxhighlight>

----
===GetGoalState===
Gets the goal state of the map goal.

'''Parameters:''' none

'''Returns:''' goal state id

'''Example:''' <syntaxhighlight lang="java">
state = mg.GetGoalState();</syntaxhighlight>

----
===GetGoalType===
Gets goal type. Examples: Attack, BUILD, CapPoint, PLANT.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetGoalType();</syntaxhighlight>

----
===GetGroupName===
Gets the current group this goal is assigned to.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
group = mg.GetGroupName();</syntaxhighlight>

----
===GetName===
Gets the name of the map goal.

'''Parameters:''' none

'''Returns:''' name of mapgoal

'''Example:''' <syntaxhighlight lang="java">
name = mg.GetName();</syntaxhighlight>

----
===GetNumUsePoint===
Gets the number of use points the goal has.

'''Parameters:''' none

'''Returns:''' # use points

'''Example:''' <syntaxhighlight lang="java">
n = mg.GetNumUsePoint();</syntaxhighlight>

----
===GetOwner===
Gets the owner of the map goal. Typically someone that is carrying it.

'''Parameters:''' none

'''Returns:''' Owner GameId, or null if no owner

'''Example:''' <syntaxhighlight lang="java">
owner = mg.GetOwner();</syntaxhighlight>

----
===GetPosition===
Gets the position of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 position

'''Example:''' <syntaxhighlight lang="java">
pos = mg.GetPosition();</syntaxhighlight>

----
===GetRadius===
Gets the radius of the map goal.

'''Parameters:''' none

'''Returns:''' float radius

'''Example:''' <syntaxhighlight lang="java">
radius = mg.GetRadius();</syntaxhighlight>

----
===GetTagName===
Gets the tag name of the map goal. This is usually a mash of the entity name and goal type.

'''Parameters:''' none

'''Returns:''' tag name

'''Example:''' <syntaxhighlight lang="java">
tag = mg.GetTagName();</syntaxhighlight>

----
===GetTypeName===
Gets the type name of the map goal.

'''Parameters:''' none

'''Returns:''' type name

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetTypeName();</syntaxhighlight>

----
===GetUsePoint===
Gets a use point, by index. If no index provided, returns a random one.

'''Parameters:''' (index<optional>)

'''Returns:''' Vector3 use point

'''Example:''' <syntaxhighlight lang="java">
pt = mg.GetUsePoint();
// OR
pt = mg.GetUsePoint(2);</syntaxhighlight>

----
===HasRole===
Returns true if the goal has any of the roles provided as parameters.

'''Parameters:''' (roleId, ...)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.HasRole(ROLE.ATTACKER))
{
}</syntaxhighlight>

'''See:''' [[Roles]]

----

===IsAvailable===
Checks if the map goal is currently available to a certain team.

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsAvailable(TEAM.RED))
{
}</syntaxhighlight>

----
===IsAvailableInitial===
Is goal available for team initially (before OnMapLoad is executed).

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if (mg.IsAvailableInitial(TEAM.RED))
{
}</syntaxhighlight>

----
===IsDisabled===
Gets whether the goal is currently disabled.

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsDisabled())
{
}</syntaxhighlight>

----
===LimitToWeapon===
Adds a list of weapons that are required from any user of the goal.

Warning: This function does not work for weapons that have ID greater than 63.

'''Parameters:''' (weaponId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.LimitToWeapon(WEAPON.FG42);</syntaxhighlight>

----
===MaxUsers_InProgress===
Get or set the max number of users that can go to the goal.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InProgress();
// OR
mg.MaxUsers_InProgress(2);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInProgress, Util.GetMaxUsersInProgress, Util.SetPercentInProgress

----
===MaxUsers_InUse===
Get or set the max number of users that can use the goal after they come to the goal position.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InUse();
// OR
mg.MaxUsers_InUse(1);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInUse, Util.GetMaxUsersInUse

----
===RenderDefault===
Draws goal name, radius, availability, use points, ExtraDebugText, ...

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.RenderDefault();</syntaxhighlight>

----
===ResetGoalPriorities===
Clears all the current priorities.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ResetGoalPriorities();</syntaxhighlight>

----
===SetAvailable===
Sets the map goal available for a certain team.

NOTE: Map scripts usually use global function SetAvailableMapGoals instead of calling SetAvailable directly on map goal object.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailable(TEAM.RED, false);</syntaxhighlight>

----
===SetAvailableInitial===
Sets goal available for team initially.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailableInitial(TEAM.AXIS, true);</syntaxhighlight>

----
===SetBaseGoalType===
Clones a base goal type. Should be done first thing in goal script.

'''Parameters:''' (fileName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.SetBaseGoalType("mapgoal_camp.gm");</syntaxhighlight>

----
===SetEntity===
Sets the entity for a map goal. It is usually not needed because most entities are detected automatically.

'''Parameters:''' (entity)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
GetGoal("MOUNTMG42_assault_tower_mg").SetEntity(GetEntityByName("assault_tower_mg"));;</syntaxhighlight>

----
===SetFacing===
Sets the facing for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetFacing(Vector3(1,0,0));</syntaxhighlight>

----
===SetGoalPriority===
Sets the priority for a given class/team. The first parameter can be 0 to set priority for all teams. The second parameter can be 0 to set priority for all classes.

NOTE: Map scripts usually use global function SetGoalPriority instead of calling SetGoalPriority directly on map goal object.

'''Parameters:''' (teamId, classId, priority)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGoalPriority(TEAM.ALLIES, CLASS.SOLDIER, 0.8);</syntaxhighlight>

----
===SetGroupName===
Sets the current group this goal is assigned to.

'''Parameters:''' (groupName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGroupName("group1");</syntaxhighlight>

----
===SetPosition===
Sets the position for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetPosition(Vector3(10,10,10));</syntaxhighlight>

----
===SetRadius===
Sets the radius for a map goal.

'''Parameters:''' (radius)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRadius(65);</syntaxhighlight>

----
===SetRange===
Sets the range for a script based map goal. It can be int radius or AABB box or both. The QueryGoals functions does not return goals which are out of range. Default range for all goals is unlimited. Goals will not be interrupted if the range changes after the bot has already activated the goal.

'''Parameters:''' (int or AABB)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRange(1000);
mg.SetRange(AABB(1369,2165,30, 4100,3700,350));

//reset to unlimited
mg.SetRange(0);
mg.SetRange(AABB());
</syntaxhighlight>

'''Utility function:''' Util.SetGoalRange
----

===SetRemoveFlag===
Marks the goal for removal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRemoveFlag(true);</syntaxhighlight>

----
===SetRoles===
Sets the roles that are allowed to use this goal.

'''Parameters:''' (roleId or table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''Utility functions:''' SetGoalRole, Util.SetRoleForGroup

'''See:''' [[Roles]]

----

==Obsolete Functions==

===GetBounds===
Gets the AABB bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB

'''Example:''' <syntaxhighlight lang="java">
bounds = mg.GetBounds();</syntaxhighlight>

----
===GetLocalBounds===
Gets the local space bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB bounds

'''Example:''' <syntaxhighlight lang="java">
localbounds = mg.GetLocalBounds();</syntaxhighlight>

----
===GetMatrix===
Gets the Matrix3 transform of the map goal.

'''Parameters:''' none

'''Returns:''' Matrix3 transform

'''Example:''' <syntaxhighlight lang="java">
m = mg.GetMatrix();</syntaxhighlight>

----
===SetEnableDraw===
Enables debug rendering for this map goal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetEnableDraw(true);</syntaxhighlight>

----
===SetMatrix===
Sets the matrix for a map goal.

'''Parameters:''' (Matrix3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
m = Matrix3();
// initialize it somehow
mg.SetMatrix(m);</syntaxhighlight>

----

MapGoal

2025-05-25T15:55:39Z

Palota: /* SetBounds */

{{process header
| title = MapGoal Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Map Goal Properties==
----
===CreateOnLoad===
False to not create the goal at load time, but keep the data around for when created by the interface.

----
===DefaultPriority===
Default priority of the goal, if no class/team specific priorities.

----
===DefaultRenderHeight===
Goal height offset where rendering will take place.

----
===DefaultRenderRadius===
Maximal distance from player to display text (goal options).

----
===DisableForControllingTeam===
Goal will be made unavailable for the team which controls it (GetOwner). It is used by CHECKPOINT goal.

----
===DontSave===
Don't save this goal into the map goal script.

----
===DynamicOrientation===
Goal should update its orientation from its entity. It is used by BUILD goal to repair vehicles.

----
===DynamicPosition===
Goal should update its position from its entity. It is used by BUILD goal to repair vehicles.

----
===ExtraDebugText===
Additional debug text to render in RenderDefault function.

----
===GoalState===
Gets the goal state.

----
===GoalStateFunction===
internal

----
===GoalType===
Type of goal.

----
===InUse===
Goal is inuse and should not be chosen.

----
===MarkForRemoval===
Mark the goal for deletion.

----
===MinRadius===
Minimum allowed radius of the goal.

----
===Radius===
Radius of the goal.

----
===RemoveWithEntity===
Goal should be removed if its entity is removed. Default is true. It is used by FLAG, FLAGRETURN, DEFUSE goals.

----
===RenderDefaultCurrentAvailability===
Draw the current availability of the goal.

----
===RenderDefaultGroup===
Draw the group of the goal.

----
===RenderDefaultInitialAvailability===
Draw the initial availability of the goal.

----
===RenderDefaultName===
Draw the name of the goal.

----
===RenderDefaultRadius===
Draw the radius of the goal.

----
===RenderDefaultRole===
Draw the roles for the goal.

----
===RenderGoal===
Enable rendering for this goal. It is set by console command /bot draw_goals

----
===RenderRandomUsePoint===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRangeLimit===
Draw whether or not the goal randomly selects a usepoint.

----
===RenderRoutes===
Enable rendering of the routes for this goal. It is set by console command /bot draw_goalroutes

'''See:'''
[[Template:Baserouting|Routing]]

----

===RolePriorityBonus===
Role priority bonus of the goal, for users matching role.

'''See:'''
[[Roles]]

----

===Version===
Gets the goal version. Omni-bot 0.8 sets goal version to 1.

----
===SerialNum===
Auto generated unique serial number of the goal.

----

==Map Goal Callbacks==
----
===InitNewGoal===
Called on goal creation (command /bot goal_create) to initialize any internal variables and set properties to default values.
For example, camping goals can initialize aim vectors to the player facing.

----
===UpgradeVersion===
Called after the goal properties have been loaded from a goals file. This function should validate schema and upgrade the goal to the latest used version.

----
===Render===
Called when draw_goals is enabled for this goal. Used to render itself.

----
===Update===
Called every frame to update the state of the goal if needed. For example, GRENADE goal calls TraceLine function to check if the goal has been destroyed.

----
===SaveToTable===
Called when the goals are saved to a file. Allows the goal to serialize persistent information.

----
===SetProperty===
Called on command /bot goal_setproperty x y, where x is a property name and y is a value or keyword.

----
===Help===
Called on commands /bot goal_help or /bot goal_create to print requirements and available properties for the goal.

----
===HudDisplay===
Called when debug window is enabled and goal is highlighted to create gui elements for debug visualization.

----

==Map Goal Functions==
----
===AddRoute===
'''See:'''
[[Template:Baserouting|Routing]]

'''Parameters:''' (start, end, weight)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddRoute("ROUTE_spawn", "ROUTE_gate", 1.0);</syntaxhighlight>

'''Utility function:''' Util.Routes
----

===AddUsePoint===
Adds a use point to the goal. Use points are used by RouteTo function. The goal can have multiple use points. Bots choose the nearest use point if goal property RandomUsePoint is false.

'''Parameters:''' (Vector3, relative[optional, default false])

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.AddUsePoint(Vector3(10,50,0), true);</syntaxhighlight>

'''Utility functions:''' Util.AddUsePoint, Util.AddUseWp

----
===ClearRoles===
Removes the given roles from this goal.

'''Parameters:''' (roleId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ClearRoles(ROLE.DEFENDER1, ROLE.DEFENDER2);</syntaxhighlight>

'''Utility functions:''' ClearGoalRole, Util.ClearRoleForGroup, Util.ClearRoleForTable

'''See:''' [[Roles]]

----

===CreateGuiFromSchema===
Used in HudDisplay callback if debug window is enabled.

'''Example:''' <syntaxhighlight lang="java">
this.CreateGuiFromSchema(this.Schema);</syntaxhighlight>

----
===DeleteIfEntityFlag===
Sets one or more entity flags that will cause the goal to be deleted.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DeleteIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===DisableGoal===
Sets whether the goal is currently disabled.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableGoal(true);</syntaxhighlight>

----
===DisableIfEntityFlag===
Sets one or more entity flags that will cause the goal to be disabled.

'''Parameters:''' (entFlagId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.DisableIfEntityFlag(ENTFLAG.DISABLED);</syntaxhighlight>

----
===GetCenterBounds===
Gets the center of the bounding box.

'''Parameters:''' none

'''Returns:''' Vector3

'''Example:''' <syntaxhighlight lang="java">
center = mg.GetCenterBounds();</syntaxhighlight>

----
===GetEntity===
Gets the entity of the map goal.

'''Parameters:''' none

'''Returns:''' GameEntity

'''Example:''' <syntaxhighlight lang="java">
ent = mg.GetEntity();</syntaxhighlight>

----
===GetFacing===
Gets the facing of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 facing

'''Example:''' <syntaxhighlight lang="java">
face = mg.GetFacing();</syntaxhighlight>

----
===GetGoalPriority===
Gets the priority for a given class/team. Default priority is returned if class or team is 0.

If the parameter is bot, role priority bonus is added if the bot has any of the goals roles.

'''Parameters:''' (bot)

'''Parameters:''' (teamId, classId)

'''Returns:''' float

'''Example:''' <syntaxhighlight lang="java">
priority = mg.GetGoalPriority(bot);
// OR
priority = mg.GetGoalPriority(TEAM.AXIS,CLASS.MEDIC);</syntaxhighlight>

----
===GetGoalState===
Gets the goal state of the map goal.

'''Parameters:''' none

'''Returns:''' goal state id

'''Example:''' <syntaxhighlight lang="java">
state = mg.GetGoalState();</syntaxhighlight>

----
===GetGoalType===
Gets goal type. Examples: Attack, BUILD, CapPoint, PLANT.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetGoalType();</syntaxhighlight>

----
===GetGroupName===
Gets the current group this goal is assigned to.

'''Parameters:''' none

'''Returns:''' string

'''Example:''' <syntaxhighlight lang="java">
group = mg.GetGroupName();</syntaxhighlight>

----
===GetName===
Gets the name of the map goal.

'''Parameters:''' none

'''Returns:''' name of mapgoal

'''Example:''' <syntaxhighlight lang="java">
name = mg.GetName();</syntaxhighlight>

----
===GetNumUsePoint===
Gets the number of use points the goal has.

'''Parameters:''' none

'''Returns:''' # use points

'''Example:''' <syntaxhighlight lang="java">
n = mg.GetNumUsePoint();</syntaxhighlight>

----
===GetOwner===
Gets the owner of the map goal. Typically someone that is carrying it.

'''Parameters:''' none

'''Returns:''' Owner GameId, or null if no owner

'''Example:''' <syntaxhighlight lang="java">
owner = mg.GetOwner();</syntaxhighlight>

----
===GetPosition===
Gets the position of the map goal.

'''Parameters:''' none

'''Returns:''' Vector3 position

'''Example:''' <syntaxhighlight lang="java">
pos = mg.GetPosition();</syntaxhighlight>

----
===GetRadius===
Gets the radius of the map goal.

'''Parameters:''' none

'''Returns:''' float radius

'''Example:''' <syntaxhighlight lang="java">
radius = mg.GetRadius();</syntaxhighlight>

----
===GetTagName===
Gets the tag name of the map goal. This is usually a mash of the entity name and goal type.

'''Parameters:''' none

'''Returns:''' tag name

'''Example:''' <syntaxhighlight lang="java">
tag = mg.GetTagName();</syntaxhighlight>

----
===GetTypeName===
Gets the type name of the map goal.

'''Parameters:''' none

'''Returns:''' type name

'''Example:''' <syntaxhighlight lang="java">
type = mg.GetTypeName();</syntaxhighlight>

----
===GetUsePoint===
Gets a use point, by index. If no index provided, returns a random one.

'''Parameters:''' (index<optional>)

'''Returns:''' Vector3 use point

'''Example:''' <syntaxhighlight lang="java">
pt = mg.GetUsePoint();
// OR
pt = mg.GetUsePoint(2);</syntaxhighlight>

----
===HasRole===
Returns true if the goal has any of the roles provided as parameters.

'''Parameters:''' (roleId, ...)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.HasRole(ROLE.ATTACKER))
{
}</syntaxhighlight>

'''See:''' [[Roles]]

----

===IsAvailable===
Checks if the map goal is currently available to a certain team.

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsAvailable(TEAM.RED))
{
}</syntaxhighlight>

----
===IsAvailableInitial===
Is goal available for team initially (before OnMapLoad is executed).

'''Parameters:''' (team id)

'''Returns:''' true if goal is available for team, false if not

'''Example:''' <syntaxhighlight lang="java">
if (mg.IsAvailableInitial(TEAM.RED))
{
}</syntaxhighlight>

----
===IsDisabled===
Gets whether the goal is currently disabled.

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(mg.IsDisabled())
{
}</syntaxhighlight>

----
===LimitToWeapon===
Adds a list of weapons that are required from any user of the goal.

Warning: This function does not work for weapons that have ID greater than 63.

'''Parameters:''' (weaponId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.LimitToWeapon(WEAPON.FG42);</syntaxhighlight>

----
===MaxUsers_InProgress===
Get or set the max number of users that can go to the goal.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InProgress();
// OR
mg.MaxUsers_InProgress(2);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInProgress, Util.GetMaxUsersInProgress, Util.SetPercentInProgress

----
===MaxUsers_InUse===
Get or set the max number of users that can use the goal after they come to the goal position.

'''Parameters:''' none or (integer)

'''Returns:''' integer

'''Example:''' <syntaxhighlight lang="java">
num = mg.MaxUsers_InUse();
// OR
mg.MaxUsers_InUse(1);</syntaxhighlight>

'''Utility functions:''' Util.SetMaxUsers, Util.SetMaxUsersInUse, Util.GetMaxUsersInUse

----
===RenderDefault===
Draws goal name, radius, availability, use points, ExtraDebugText, ...

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.RenderDefault();</syntaxhighlight>

----
===ResetGoalPriorities===
Clears all the current priorities.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.ResetGoalPriorities();</syntaxhighlight>

----
===SetAvailable===
Sets the map goal available for a certain team.

NOTE: Map scripts usually use global function SetAvailableMapGoals instead of calling SetAvailable directly on map goal object.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailable(TEAM.RED, false);</syntaxhighlight>

----
===SetAvailableInitial===
Sets goal available for team initially.

'''Parameters:''' (team id, true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetAvailableInitial(TEAM.AXIS, true);</syntaxhighlight>

----
===SetBaseGoalType===
Clones a base goal type. Should be done first thing in goal script.

'''Parameters:''' (fileName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.SetBaseGoalType("mapgoal_camp.gm");</syntaxhighlight>

----
===SetEntity===
Sets the entity for a map goal. It is usually not needed because most entities are detected automatically.

'''Parameters:''' (entity)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
GetGoal("MOUNTMG42_assault_tower_mg").SetEntity(GetEntityByName("assault_tower_mg"));;</syntaxhighlight>

----
===SetFacing===
Sets the facing for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetFacing(Vector3(1,0,0));</syntaxhighlight>

----
===SetGoalPriority===
Sets the priority for a given class/team. The first parameter can be 0 to set priority for all teams. The second parameter can be 0 to set priority for all classes.

NOTE: Map scripts usually use global function SetGoalPriority instead of calling SetGoalPriority directly on map goal object.

'''Parameters:''' (teamId, classId, priority)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGoalPriority(TEAM.ALLIES, CLASS.SOLDIER, 0.8);</syntaxhighlight>

----
===SetGroupName===
Sets the current group this goal is assigned to.

'''Parameters:''' (groupName)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetGroupName("group1");</syntaxhighlight>

----
===SetPosition===
Sets the position for a map goal.

'''Parameters:''' (Vector3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetPosition(Vector3(10,10,10));</syntaxhighlight>

----
===SetRadius===
Sets the radius for a map goal.

'''Parameters:''' (radius)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRadius(65);</syntaxhighlight>

----
===SetRange===
Sets the range for a script based map goal. The QueryGoals functions does not return goals which are out of range. Default range for all goals is 0 which means unlimited. Goals will not be interrupted if the range changes after the bot has activated the goal.

'''Parameters:''' (range)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRange(1000);</syntaxhighlight>

'''Utility function:''' Util.SetGoalRange
----
===SetRemoveFlag===
Marks the goal for removal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRemoveFlag(true);</syntaxhighlight>

----
===SetRoles===
Sets the roles that are allowed to use this goal.

'''Parameters:''' (roleId or table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''Utility functions:''' SetGoalRole, Util.SetRoleForGroup

'''See:''' [[Roles]]

----

==Obsolete Functions==

===GetBounds===
Gets the AABB bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB

'''Example:''' <syntaxhighlight lang="java">
bounds = mg.GetBounds();</syntaxhighlight>

----
===GetLocalBounds===
Gets the local space bounds of the map goal.

'''Parameters:''' none

'''Returns:''' AABB bounds

'''Example:''' <syntaxhighlight lang="java">
localbounds = mg.GetLocalBounds();</syntaxhighlight>

----
===GetMatrix===
Gets the Matrix3 transform of the map goal.

'''Parameters:''' none

'''Returns:''' Matrix3 transform

'''Example:''' <syntaxhighlight lang="java">
m = mg.GetMatrix();</syntaxhighlight>

----
===SetEnableDraw===
Enables debug rendering for this map goal.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
mg.SetEnableDraw(true);</syntaxhighlight>

----
===SetMatrix===
Sets the matrix for a map goal.

'''Parameters:''' (Matrix3)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
m = Matrix3();
// initialize it somehow
mg.SetMatrix(m);</syntaxhighlight>

----

Template:Configuration

2025-05-25T13:48:34Z

Palota: /* Waypoints folder */

== Number of bots ==

/bot maxbots 15

Sets maximum number of bots. It must be less than number of slots (sv_maxclients). The server manager script will automatically kick one bot when a human player connects to server and joins axis or allied team. Similarly, it will add a new bot if some player disconnects.

/bot minbots 2

Sets minimum number of bots. Default value is -1. You should set minbots only if you want some bots to be always playing even if your server is full.

If you want to add bots manually, you must set maxbots and minbots to -1. Then you can add bots by commands [[Omni-bot_Command_Reference#ab|/bot ab]] or [[Omni-bot_Command_Reference#addbot|/bot addbot]].

== Difficulty levels ==

/bot difficulty 4

Difficulty ranges from 0 to 6 (0 is easy, 6 is hard).

If you change difficulty, bots' properties will be adjusted (reaction time, field of view, aim error, view distance, ...). Advanced users can adjust bot properties for each difficulty level in the file omni-bot/et/scripts/goals/goal_difficulty.gm.

== Combat movement skill ==

/bot moveskill 4

Moveskill ranges from 0 to 3. Specifying 4 for moveskill will have each bot choose a random moveskill.

It affects bot's behaviour during combat (crouch, strafe left or right, ...).

== Balance teams ==

/bot balanceteams 1

If you enable balanceteams, bots will move between teams in order to keep same number of players in both teams.

== Log files ==

Log files are written to folder omni-bot/et/logs. If the folder does not exists, log files are written to Enemy Territory game folder. File name is omnibot_<mapname>.log.

/seta omnibot_logsize 0

* Value -1 disables logging.
* Default value 0 enables logging, but files will be overwritten every match.
* Value greater than 0 means maximal file size in KB and also allows appending more matches to a single file.

== Configuration file ==

You can find the file '''omni-bot.cfg''' in the folder omni-bot/et/user. You usually don't need to modify this file because most settings can be changed from the console. Nevertheless, some advanced settings are not accessible from the console: CountSpectators, SleepBots, SaveConfigChanges, AdjustAim, DumpFileEnable, DumpFileDialog, LiveUpdate, Debug, EnableInterProcess, LogInfo, LogWarnings, LogErrors, LogCriticalErrors.

Documentation can be found in file omni-bot.txt.

== Changing bot names ==

You need to go into the omni-bot/et/scripts folder. In Omni-bot 0.82 or later open file "'''et_botnames_ext.gm'''". In Omni-bot 0.81 or 0.8 open file "et_botnames.gm". In Omni-bot 0.71 or older open file "et_autoexec.gm". Bots' names are in quotes. Do not change other commands in that scripts.

== Waypoints folder ==

Waypoints and map scripts can be found in the '''omni-bot/et/nav''' and '''omni-bot/et/incomplete_navs''' folders. New waypoints should be added into this folder. You can add new waypoints in a zip or 7z file (they must be at the root level of the zip file, not in a folder) or you can just add the files directly.

ScriptGoal

2025-05-25T13:46:17Z

Palota: /* Expression */

{{process header
| title = Script Goal
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
[[Category:ET|Script Goals]]
[[Category:Doom 3|Script Goals]]
[[Category:Quake 4|Script Goals]]
[[Category:RTCW|Script Goals]]

==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]]

<syntaxhighlight lang="java">this.Name = "MyGoalName";</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Parent = "HighLevel";</syntaxhighlight>

===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]]

<syntaxhighlight lang="java">this.Disable = true;</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.AlwaysRecieveEvents = true;</syntaxhighlight>

===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 [[ScriptGoal#AlwaysRecieveEvents| AlwaysRecieveEvents]], which will allow goals to receive events even when not active.
<syntaxhighlight lang="java">
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) );
};</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Bot.Say("Wassup");</syntaxhighlight>

===Priority===
Priority is a property rather than a return value of [[ScriptGoal#GetPriority| GetPriority]] in order to support the useful threading nature of script goals. It is possible to completely leave out a [[ScriptGoal#GetPriority| 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.

<syntaxhighlight lang="java">this.Priority = 1;</syntaxhighlight>

===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.
<syntaxhighlight lang="java">
this.Commands["command_name"] = {
Func = function( _params )
{
},
Help = { "description" },
};
</syntaxhighlight>

==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:''' <syntaxhighlight lang="java">
this.Initialize() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.OnSpawn() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.GetPriority() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.Enter() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.Exit() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]]
----
===Update===
This function is the meat of a script goal. Once a goal is chosen to run, and [[ScriptGoal#Enter| Enter]] is called, the Update function begins getting called at frequent regular intervals. The state stays active until another goal overrides it, or until [[ScriptGoal#Finished| Finished]] is called, after which the [[ScriptGoal#Exit| Exit]] function is called.

'''Example:''' <syntaxhighlight lang="java">
this.Update() = function()
{
// do stuff
this.Finished(); // when we're done running
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]], [[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.OnPathThrough = function(data)
{
navigation = Map.Navigation[data];
if(navigation)
{
this.CurrentNavigation = data;
return true;
}
this.CurrentNavigation = null;
return false;
};
</syntaxhighlight>

==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
{| align="center" border="1"
!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)
|-
|mapgoalavailable
|No
|MapGoal object or name
|}

=====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
<syntaxhighlight lang="java">
this.AddFinishCriteria(this.TargetEntity,"not hasentflag",ENTFLAG.DEAD); // as soon as the entity does not have the dead flag
</syntaxhighlight>

'''Returns:''' true if criteria was created, false if not

'''Example:''' <syntaxhighlight lang="java">
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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.Finished();</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
//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
};</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToClass(CLASS.MEDIC);
this.LimitToClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoClass(CLASS.MEDIC);
this.LimitToNoClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTeam(TEAM.BLUE);
this.LimitToTeam(TEAM.BLUE, TEAM.RED);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToEntityFlag(ENTFLAG.INWATER);
this.LimitToEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoEntityFlag(ENTFLAG.INWATER);
this.LimitToNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE); </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function takes no parameters.
this.LimitToNoTarget(); </syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToWeapon(WEAPON.MOBILE_MG42);
this.LimitToWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// 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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetTeam(TEAM.RED); // don't run unless our target is on red team</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42);
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.LimitToRole(ROLE.DEFENDER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.GetPriority = function()
{
if(this.IsActive())
{
return 1.0;
}
else
{
// do some other check
}
}; </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
wpinfo = table();
wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
if( this.Goto(wpinfo.position, wpinfo.radius) == EVENT.PATH_SUCCESS )
{
print("Made it!");
}</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
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!");
}</syntaxhighlight>

----

===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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathSucceed())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathFail())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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 - LookAround
* Priority.Low - CAMP, ESCORT, RIDE, MOUNT, ...
* 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:''' <syntaxhighlight lang="java">
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
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseAimRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseAimRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddAimRequest| 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:''' <syntaxhighlight lang="java">
this.AddWeaponRequest(Priority.High, WEAPON.MEDKIT); </syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseWeaponRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.BlockForWeaponChange(WEAPON.MEDKIT);
this.Say("Medkit Equipped!");</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
count = this.QueryGoals(this.Bot.QueryGoalsTable, 0xc9326a43);
count = this.QueryGoals(this.Bot.QueryGoalsTable, "BUILD_.*");</syntaxhighlight>

----

===BlackboardDelay===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.BlackboardDelay(10);</syntaxhighlight>

----

===BlackboardIsDelayed===

'''Parameters:''' (mapGoal or serialNumber)

'''Returns:''' true if goal has been found on blackboard

'''Example:''' <syntaxhighlight lang="java">
if (this.BlackboardIsDelayed(serial))</syntaxhighlight>

----

===MarkInProgress===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
if (!this.MarkInProgress()) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===MarkInUse===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
if (!this.MarkInUse()) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===WatchForMapGoalsInRadius===

----

===ClearWatchForMapGoalsInRadius===

----

===WatchForEntityCategory===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.WatchForEntityCategory({
Radius = 350,
Category = CAT.PROJECTILE,
RequireLOS = TRACE.VISIBLE
});
</syntaxhighlight>

----

===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 [[ScriptGoal#Disable| 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 [[ScriptGoal#BlockForWeaponChange|BlockForWeaponChange]], [[ScriptGoal#Goto|Goto]], [[ScriptGoal#AddAimRequest|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.

Roles

2025-05-25T13:35:53Z

Palota: /* Bots */

{{process header
| title = Roles
| section =
| previous = [[Omni-Bot_Map_Scripting| Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

== Intro ==

Bot roles were added in version 0.8 as a method to focus specific bots on specific goals. Any goal that has a role defined will be ignored by bots that do not have the same role defined. This is particularly useful when there are multiple defense points in a map that are simultaneously active or in large dual objective maps.

The Enemy Territory map Radar is one such example as the last stage of the map has two separate objectives for the Allied team to steal; the East and West Radar Parts. The defense has been setup so that one group of defenders will focus on the West Parts and another will focus on the East Parts. Since the defend goals have an equal priority, setting roles ensures that the bots won't be wandering between locations; which results in a much weaker defense.

Another very specific usage of roles is for Covert Ops bots in Enemy Territory that have the ability to steal an enemies uniform. Once in uniform, the bot is automatically assigned an Infiltrator role; which makes certain goals available that normally would not be reachable.

A more common use of roles would be for the Capture the Flag type maps seen in Doom 3 and Quake 4 as there is a need for dedicated base defenders.

Roles however are not limited to the scenarios given. Any time there is a need for specific goals to be limited in usage to one or more bots, setting roles is a simple way to solve the problem.

== Setup ==

Setup requires that both bots and goals are given the desired roles with one of the predefined roles. Valid roles are as follows:

<syntaxhighlight lang="java">
ROLE.ATTACKER
ROLE.ATTACKER1
ROLE.ATTACKER2
ROLE.ATTACKER3
ROLE.OFFENSECAPTAIN
ROLE.DEFENDER
ROLE.DEFENDER1
ROLE.DEFENDER2
ROLE.DEFENDER3
ROLE.DEFENSECAPTAIN
ROLE.TEAMCAPTAIN
ROLE.FIRETEAMCAPTAIN
ROLE.AMBUSHER
ROLE.INFILTRATOR
ROLE.ROAMER
ROLE.SNIPER
ROLE.ESCORT
</syntaxhighlight>

=== Goals ===

Roles can be added to goals either in the editor or in a map script. To add a role in the editor, simply use the following commands:
/bot goal_edit
/bot goal_setproperty roles DEFENDER
/bot goal_finish

You can set multiple roles on a goal by using the | operator:
/bot goal_setproperty roles DEFENDER|DEFENDER1

Once completed, /bot goal_save will commit the changes to the goals file.

Setting roles in the editor is preferred since it reduces script size, but users wishing to set them in the map script can use the following helper functions:

<syntaxhighlight lang="java">
SetGoalRole( <goal expression or table>, <roles>, <persistent> );
Util.SetRoleForGroup( <goal group>, <roles> );
ClearGoalRole( <goal expression or table>, <roles> );
Util.ClearRoleForGroup( <goal group>, <roles> );
</syntaxhighlight>

For example:

<syntaxhighlight lang="java">
SetGoalRole("DEFEND_East.*", ROLE.DEFENDER); //set the defender role on goals that have a name starting with DEFEND_East
SetGoalRole("DEFUSE_wall.*", ROLE.DEFENDER2, true); //set role for dynamically created goal
SetGoalRole("MOUNTMG42_bank", { ROLE.DEFENDER2, ROLE.DEFENDER3 }); //set multiple roles to one goal
SetGoalRole({ "DEFEND_docs.*", "MOUNTMG42_docs" }, ROLE.DEFENDER1); //set role on multiple goals
</syntaxhighlight>

=== Priority ===

Almost every map goal has property RolePriorityBonus which is added to priority if the goal has any role. That's why bots prefer goals which have role. Camp goals (attack/defend/camp/snipe) have RolePriorityBonus only 0.01. Other goals have RolePriorityBonus 0.1.

Sometimes the default RolePriorityBonus is not enough and it's necessary to use function SetGoalPriority to change priorities. For example, if some CHECKPOINT goal without role is active, all DEFEND goals are ignored and all bots go to capture checkpoint. Even if the DEFEND goals have DEFENDER role and some bots have DEFENDER role, nobody will use DEFEND goals if they have default priority.

=== Bots ===

The simplest way to assign bot roles is to set up the map script to use the Role Manager. The Role Manager will automatically assign the bots' roles based on a Map.Roles table in the map script.

A commented example of the Role Manager setup:

<syntaxhighlight lang="java">
global Map =
{
Roles =
{
AXIS = // Team
{
AllBots = true, // each bot is considered for a role
DEFENDER = // the DEFENDER role
{
voice = "defend", // signals voice chat to randomly announce
spawnpt = 2, // users of this role will choose spawnpt 2
numbots = 4, // maximum of 4 bots
crucialClass = CLASS.ENGINEER, // class for the first bot
MinBotsForRole = 4, // only assign this role if there are already 4 bots in game
},
ATTACKER =
{
voice = "attack",
numbots = 4,
crucialClass = {CLASS.ENGINEER, CLASS.COVERTOPS}, //the first is engineer, the second is covertops
},
},

ALLIES =
{
AllBots = false, // default: every other bot
DEFENDER =
{
AllBots = true, //allow more than 3
numbots = 3,
},
ATTACKER =
{
numbots = 4,
},
},
},
};
</syntaxhighlight>

In this example, each team will have bots assigned to two different roles. For each role there can be a maximum number of bots set, a spawn point defined, a crucial class given, and even a voice chat for the bot to randomly use when assigned the role. All of the role flags are optional except for numbots:

numbots - the number of bots the role manager will attempt to keep assigned the role
AllBots - allow more than numbots for the role
crucialClass - the first bot assigned the role will switch to this class, can be a table of classes for more bots
spawnpt - bots with this role will choose this spawn point
voice - "attack" and "defend" are the two valid values
MinBotsForRole - the number of bots required to be in game before assigning the role.

=== Region triggers ===

If some goals are behind a door or gate which can be opened or destroyed by one team, and closed or rebuilt by the other team, then it is recommended to use region triggers. It will prevent path failed errors. It is usually possible to create one large region which covers entire area behind door (see maps mml_minastirith_fp3, nod_temple). Bots inside the region will have a role, but bots outside the region will not have the role. Goals behind door or gate will have the role only if the door is closed or gate is built.

<syntaxhighlight lang="java">
Rocket_room =
{
Name = "Rocket_room",
TriggerOnClass = CLASS.ANYPLAYER,
OnEnter = function(ent)
{
bot = Util.IsBot(ent);
if(bot){ bot.SetRoles(ROLE.ATTACKER); }
},
OnExit = function(ent)
{
bot = Util.IsBot(ent);
if(bot){ bot.ClearRoles(ROLE.ATTACKER); }
},
},

Door_Open = function()
{
ClearGoalRole({ "PLANT_rocket", "ATTACK_rocket.*" }, ROLE.ATTACKER);
},

Door_Close = function()
{
SetGoalRole({ "PLANT_rocket", "ATTACK_rocket.*" }, ROLE.ATTACKER);
},
</syntaxhighlight>

Sometimes it's not possible to create one large region (see map sfx_endor). Then it is necessary to create the first region just behind the gate (OnEnter function sets bot's role) and other regions in front of the gate and at every spawn (OnEnter function clears bot's role).

ScriptGoal

2025-05-24T18:18:33Z

Palota: /* Priority */

{{process header
| title = Script Goal
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
[[Category:ET|Script Goals]]
[[Category:Doom 3|Script Goals]]
[[Category:Quake 4|Script Goals]]
[[Category:RTCW|Script Goals]]

==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]]

<syntaxhighlight lang="java">this.Name = "MyGoalName";</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Parent = "HighLevel";</syntaxhighlight>

===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]]

<syntaxhighlight lang="java">this.Disable = true;</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.AlwaysRecieveEvents = true;</syntaxhighlight>

===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 [[ScriptGoal#AlwaysRecieveEvents| AlwaysRecieveEvents]], which will allow goals to receive events even when not active.
<syntaxhighlight lang="java">
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) );
};</syntaxhighlight>

===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.

<syntaxhighlight lang="java">this.Bot.Say("Wassup");</syntaxhighlight>

===Priority===
Priority is a property rather than a return value of [[ScriptGoal#GetPriority| GetPriority]] in order to support the useful threading nature of script goals. It is possible to completely leave out a [[ScriptGoal#GetPriority| 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.

<syntaxhighlight lang="java">this.Priority = 1;</syntaxhighlight>

===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.
<syntaxhighlight lang="java">
this.Commands["command_name"] = {
Func = function( _params )
{
},
Help = { "description" },
};
</syntaxhighlight>

==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:''' <syntaxhighlight lang="java">
this.Initialize() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.OnSpawn() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.GetPriority() = function()
{
};</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
this.Enter() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.Exit() = function()
{
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]]
----
===Update===
This function is the meat of a script goal. Once a goal is chosen to run, and [[ScriptGoal#Enter| Enter]] is called, the Update function begins getting called at frequent regular intervals. The state stays active until another goal overrides it, or until [[ScriptGoal#Finished| Finished]] is called, after which the [[ScriptGoal#Exit| Exit]] function is called.

'''Example:''' <syntaxhighlight lang="java">
this.Update() = function()
{
// do stuff
this.Finished(); // when we're done running
};</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Enter| Enter]], [[ScriptGoal#Exit| 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:''' <syntaxhighlight lang="java">
this.OnPathThrough = function(data)
{
navigation = Map.Navigation[data];
if(navigation)
{
this.CurrentNavigation = data;
return true;
}
this.CurrentNavigation = null;
return false;
};
</syntaxhighlight>

==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
{| align="center" border="1"
!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
<syntaxhighlight lang="java">
this.AddFinishCriteria(this.TargetEntity,"not hasentflag",ENTFLAG.DEAD); // as soon as the entity does not have the dead flag
</syntaxhighlight>

'''Returns:''' true if criteria was created, false if not

'''Example:''' <syntaxhighlight lang="java">
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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.Finished();</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
//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
};</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToClass(CLASS.MEDIC);
this.LimitToClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoClass(CLASS.MEDIC);
this.LimitToNoClass(CLASS.MEDIC, CLASS.ENGINEER);</syntaxhighlight>
----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTeam(TEAM.BLUE);
this.LimitToTeam(TEAM.BLUE, TEAM.RED);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToEntityFlag(ENTFLAG.INWATER);
this.LimitToEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoEntityFlag(ENTFLAG.INWATER);
this.LimitToNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToNoPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE); </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function takes no parameters.
this.LimitToNoTarget(); </syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToPowerUp(ENTFLAG.INVINCIBLE);
this.LimitToPowerUp(ENTFLAG.INVINCIBLE, ENTFLAG.QUADDAMAGE);</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToWeapon(WEAPON.MOBILE_MG42);
this.LimitToWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// 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</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetTeam(TEAM.RED); // don't run unless our target is on red team</syntaxhighlight>
----

===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----
===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:''' <syntaxhighlight lang="java">
// 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);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER);
this.LimitToTargetNoEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
// This function can take any number of parameters.
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42);
this.LimitToTargetWeapon(WEAPON.MOBILE_MG42, WEAPON.MORTAR);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.LimitToRole(ROLE.DEFENDER);</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
this.GetPriority = function()
{
if(this.IsActive())
{
return 1.0;
}
else
{
// do some other check
}
}; </syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
wpinfo = table();
wp = Wp.GetWaypointByName("somewaypoint", wpinfo);
if( this.Goto(wpinfo.position, wpinfo.radius) == EVENT.PATH_SUCCESS )
{
print("Made it!");
}</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
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!");
}</syntaxhighlight>

----

===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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathSucceed())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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. [[ScriptGoal#DidPathSucceed| DidPathSucceed]] and [[ScriptGoal#DidPathFail| 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:''' <syntaxhighlight lang="java">
if(this.DidPathFail())
{
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#Goto| Goto]], [[ScriptGoal#DidPathSucceed| 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 - LookAround
* Priority.Low - CAMP, ESCORT, RIDE, MOUNT, ...
* 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:''' <syntaxhighlight lang="java">
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
}</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseAimRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseAimRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddAimRequest| 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:''' <syntaxhighlight lang="java">
this.AddWeaponRequest(Priority.High, WEAPON.MEDKIT); </syntaxhighlight>

'''See Also:'''
[[ScriptGoal#ReleaseWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.ReleaseWeaponRequest();</syntaxhighlight>

'''See Also:'''
[[ScriptGoal#AddWeaponRequest | 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:''' <syntaxhighlight lang="java">
this.BlockForWeaponChange(WEAPON.MEDKIT);
this.Say("Medkit Equipped!");</syntaxhighlight>

----

===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:''' <syntaxhighlight lang="java">
count = this.QueryGoals(this.Bot.QueryGoalsTable, 0xc9326a43);
count = this.QueryGoals(this.Bot.QueryGoalsTable, "BUILD_.*");</syntaxhighlight>

----

===BlackboardDelay===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.BlackboardDelay(10);</syntaxhighlight>

----

===BlackboardIsDelayed===

'''Parameters:''' (mapGoal or serialNumber)

'''Returns:''' true if goal has been found on blackboard

'''Example:''' <syntaxhighlight lang="java">
if (this.BlackboardIsDelayed(serial))</syntaxhighlight>

----

===MarkInProgress===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
if (!this.MarkInProgress()) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===MarkInUse===

'''Parameters:''' (mapGoal[optional])

'''Returns:''' true if empty slot has been found and marked

'''Example:''' <syntaxhighlight lang="java">
if (!this.MarkInUse()) {
this.BlackboardDelay(5);
this.Finished();
}</syntaxhighlight>

----

===WatchForMapGoalsInRadius===

----

===ClearWatchForMapGoalsInRadius===

----

===WatchForEntityCategory===

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

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
this.WatchForEntityCategory({
Radius = 350,
Category = CAT.PROJECTILE,
RequireLOS = TRACE.VISIBLE
});
</syntaxhighlight>

----

===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 [[ScriptGoal#Disable| 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 [[ScriptGoal#BlockForWeaponChange|BlockForWeaponChange]], [[ScriptGoal#Goto|Goto]], [[ScriptGoal#AddAimRequest|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.

Omni-bot Command Reference

2025-05-20T12:33:51Z

Palota: /* navsystem */

{{process header
| title = Omni-bot Command Reference
| section =
| previous = [[Main_Page | Main Page]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
[[Category:ET|Command Reference]]
[[Category:Doom 3|Command Reference]]
[[Category:Quake 4|Command Reference]]
{{TOCright}}
===Console Commands===

Omni-bot comes with a wide range of utilities in the form of console commands for general purpose usage as well as debugging tools for waypointing.
You can also add/write your own commands into file et_autoexec_user.gm or rtcw_autoexec_user.gm in scripts folder.

* [[Console|How to open console and execute command]]
* [[Goal Commands]]
* [[Waypoint Commands]]

====addbot====
Do NOT use this command on dedicated servers. Command [[Omni-bot_Command_Reference#maxbots | maxbots]] must be used on servers.
If you play game on your home computer and you want bots to be added automatically, you can use command [[Omni-bot_Command_Reference#maxbots | maxbots]] too. If you want to add bots manually every time you start the game, you should use command [[Omni-bot_Command_Reference#ab | ab]]. Command addbot is useful only if you need unbalanced teams.

syntax: bot addbot <optional team> <optional class> <optional name>
example: /bot addbot 2 1 bob will add a soldier named bob to the allied team in ET

team: 1 = Axis, 2 = Allies

class: 1 = Soldier, 2 = Medic, 3 = Engineer, 4 = Field Ops, 5 = Covert Ops

Note: Command addbot chooses bot's name randomly. Command [[Omni-bot_Command_Reference#ab | ab]] chooses names according to team and class as defined in file et_botnames_ext.gm.

Note: Bots select their class every time they spawn. If you want to set classes manually, you must change DisableClassManager value to 1 in file et_autoexec.gm.

====debugbot====
Enables debugging output on a specific bot or all bots.

syntax: bot debugbot botname debugtype
example: bot debugbot all fpinfo

debug types: log, move, script, fpinfo, planner, events, failedpaths, aim, sensory, steer, target

Debug type can also be a ScriptGoal name to toggle Debug property.

====debugtriggers====
Prints triggers to console.

syntax: bot debugtriggers <optional 1/0/on/off> <optional regular expression>
usage: used for checking or identifying trigger names to be used with map scripting. when turned on, you will see
messages about events as they occur in the map:

<+++> Trigger: TagName: The Tank has been repaired! Action: announce Entity: 0x7016dd8c Activator: 0

<+++> means that a callback (trigger) is set up and has been called, while <---> means no callback is associated
TagName is the string to use for the OnTrigger function in the map script
Action is the category in which the event is recognized

notes: this is a toggle. issuing the command a second time will turn it off.

====dontshoot====
Enables/disables all bot shooting ability.

syntax: bot dontshoot true/false/1/0/yes/no
example: bot dontshoot 1 will stop all bots from shooting.

====draw_goalrange====
Renders all goals range radius and prints it to the console.

syntax: bot draw_goalrange

====draw_goalroutes====
Renders route paths.

syntax: bot draw_goalroutes on/off goalname
example: bot draw_goalroutes on will draw route paths to all goals set up for routing

notes: the goalname parameter is optional and supports expressions. i.e. bot draw_goalroutes on ATTACK.* will draw route to all of
the attack goals in the map that are set up for routing
this command was added in version 0.7

====draw_goals====
Draws debug information for all mapgoals.

syntax: bot draw_goals on/off goalname
example: bot draw_goals on will draw squares around all objective goals and highlight the radius of attack / defend goals

notes: the goalname parameter is optional and supports expressions. i.e. bot draw_goals on ATTACK.* will highlight all of
the attack goals in the map.

====drawblocktests====
Enables drawing of blockable line tests.

syntax: bot drawblocktests 1/0
example: bot drawblocktests 1 turns on drawing of block tests

useage: will draw block test lines in addition to the ones drawn in waypoint mode.

====drawtriggers====
Renders any active trigger zones.

syntax: bot drawtriggers <optional 1/0>

====help====
List all bot commands available in console.

syntax: bot help

====kickall====
Kick all bots from the game by name.

syntax: bot kickall

====kickbot====
Removes a bot from the game.

syntax: bot kickbot <botname>
example: bot kickbot [BOT]Aimless

====nav_benchmarkgetnavpoint====
Development tool. Performs a GetClosestWaypoint test with every waypoint. Used to test the speed of nearest waypoint lookups.

====nav_benchmarkpathfinder====
Development tool. Executes a path search between every waypoint and every other waypoint. Used to test the speed of the path finding system.

====nav_logfailedpath====
Saves info about failed path attempts for debugging.

====nav_resaveall====
Re-save all nav files to the newest file format.

====nav_showfailedpath====
Render a failed path by its index.

====print_filesystem====
Prints files from file system.

====printfs====
Prints the whole file system.

====reload_weapons====
Reloads the weapon database from script files on disc.

====revision====
Shows the revision the bot dll was built from.

====script_collect====
Performs a garbage collection.

====script_debug====
Enables/disables debug messages in the scripting system.

syntax: bot script_debug 1/0/on/off
example: bot script_debug 1 turns on debugging information in the script system.

usage: when enabled, if an error occurs in script execution, it will be printed to the console.

====script_docs====
Dumps a file of gm bound type info.

====script_run====
Executes a string as a script snippet.
Apostrophes are converted to quotation marks.

syntax: bot script_run <string>
example: bot script_run "print('Time left:'); print(GetGameTimeLeft())"

====script_runfile====
Executes a specified script file.

syntax: bot script_runfile <filename>
example: bot script_runfile testing.gm

====script_stats====
Shows scripting system memory usage/stats.

syntax: bot script_stats

usage: displays memory use and garbage collection stats in console

====show_bb====
Shows the contents of the global blackboard.

syntax: bot show_bb

====show_goalroutes====
Prints route info for matching map goals.

====show_goals====
Prints out the names of each goal.

syntax: bot show_goals <optional expression> <optional p>
example: bot show_goals DEFEND.* will list all defend goals in console
example: bot show_goals .* p will list all goals and their sub priorities (for >= 0.7)

notes: this command supports expressions for the optional parameter

Explanation of goal-list-entry by example:

33: FLAG_the_War_Documents -> 0100 serial 3 priority 0.55
ALLIES AXIS SOLDIER MEDIC ENGINEER LIEUTENANT 1.80

<goal-no>: <goal-name> -> <team-availability> serial <serial> priority <priority>

goal-no: number of goal
goal-name: name of goal
team-availability: availability team1 team2 team3 team4
serial: serial number
priority: default priority

The optional p parameter displays properties set with the SetGoalPriority function which
enables Team and Class properties to be set.

notes: team-availability shows boolean value for each team
team3 and team4 are obsoleted in ET, since ET only has 2 teams:
TEAM.AXIS and TEAM.ALLIES or TEAM.TEAM1 and TEAM.TEAM2.

====showprocesses====
Shows a NavMesh or Recast process by its name.

syntax: bot showprocesses

usage: for debug use only

====stopprocess====
Stops a process by its name.

syntax: bot stopprocess

usage: for debug use only

====version====
Prints out the bot version number.

syntax: bot version

====ab====
Add Bots, add a given number of bots
Usage: /bot ab <numbots>

====addroute====
Add Route, adds a route node at players current position
Usage: bot ar <name> <optional radius>
Version note: RTCW only

====aim_debug_reload====
Aim Debug Reload, reloads each bots profile
Usage: /bot aim_debug_reload

====aim_pos====
Aim Position, lists the players current aim position
Usage: /bot aim_pos

====ar====
Add Route, adds a route node at players current position
Usage: bot ar <name> <optional radius>
Version note: RTCW only

====autosave====
Enables waypoint view and autosave.

====balanceteams====
Forces bots to keep teams balanced.

syntax: bot balanceteams 1/0
example: bot balanceteams 1 turns on bot balancing

notes: by default, omni-bot will keep teams balanced when adding bots unless bots are added specifically to a team

====botgoal====
Bot Goal, used for debugging a bots goal on remote server.

====botsperhuman====
Set the team the ratio of bots per humans in a humans vs bots game.

====botteam====
Set the team the bots should be on in a humans vs bots game.

====botwar====
Enable or disable bots vs human teams.
syntax: bot botwar <botTeam> <humanTeam> <botsPerHuman>
example: bot botwar 2 1 3 // set bots to be on allies with a 3 to 1 ratio compared to humans on axis team
bot botwar -1 // disable it

====bvp====
Build Vehicle Path, assists the waypointer in creating the vehicle path
Usage: /bot bvp <goalname> <optional seconds>
goalname should be set to the MOVER or BUILD goal of the vehicle
seconds can be optionally set to adjust the interval between the vehicle being damaged
run the command again to turn it off
Version note: ET only

====campnext====
Advance to the next camp goal position. It will automatically select the goal. Waypoint tool for adding camp facings.
Version note: ET only

====campstart====
Start iterating through the camp goals in the map (CAMP, DEFEND, ATTACK, SNIPE). Waypoint tool for adding camp facings. Binding a key to /bot goal_setproperty facing 99 will make things fast!
Version note: ET only

====cg====
Clear Goal, disables the given goalname for the given team
Usage: /bot cg <goalname> <team>
====cleargoalflags====
Removes all deprecated waypoint flags (defend, snipe, ...) which were used in Omni-bot 0.71.

====cvp====
Check Vehicle Path, test bots ability to repair the vehicle along its entire path
Usage: /bot cvp <goalname> <optional seconds>
goalname should be set to the BUILD goal of the vehicle
seconds can be optionally set to adjust the interval between the vehicle being damaged
run the command again to turn it off
Version note: ET only

====cwn====
Clear Waypoint Names, remove all waypoint names
Usage: /bot cwn <optional true>
Note: the true parameter will list each waypoint that has been cleared

====dbg_goalavailability====
Toggle goal availability debugging. It will print all active goals to the console when Util.MapDebugPrint is called.

====dbg_mapscripts====
Toggle map script debugging (Util.MapDebugPrint messages).

====dbg_scriptgoals====
Toggle script goals debugging (pathfailed, timedout, ...).

====dg====
Display Goal, runs a thread that lists the given goals name, position, and facing
Usage: /bot dg <goalname> <true|false>
Note: useful for mover type goals

====difficulty====
Sets the bots difficulty. 0 is easy, 4 is default, 6 is hard, -1 is random
Usage: /bot difficulty 3
Difficulty can also be set from the referee menu in ET:Legacy.

====dist====
Distance View, gives distance to a players aim position
Usage: /bot dist, /bot dist off

====draw_oids====
Draw Objective Info Displays, waypoint tool. draws the bounds of all OID's in the map.

====draw_paththrough====
Render 3d text over paththrough node locations.

====draw_spawns====
Draw spawn points, waypoint tool. draws the bounds of all spawn points in the map.

====dstats====
Dump Stats, writes each bots current round stats to user<mapname>_stats.gm
Usage: /bot dstats
Version note: RTCW only

====dump_autocomplete====
Creates an xml file for autocompletion with Notepad++

====dumpglobals====
Dump Globals, writes all functions and references to files in the ~user directory
Usage: /bot dumpglobals

====dwoff====
Debug Window Off, closes the debug window.
Usage: /bot dwoff

====dwon====
Debug Window On, opens up the debug window.
Not implemented in release version of omni-bot.
You can download debug version from assembla SVN repository from dw_enabled folder.
Usage: /bot dwon

====eob====
Exec on Bots, executes the given command on all bots
Usage: /bot eob <command>

====humanteam====
Set the team the humans should be on in a humans vs bots game.

====initialdelaytime====
Sets delay time for server manager to execute on map changes.

====ip====
Ignore Player, bots won't shoot player
Usage: /bot ip <on|off>

====keepbot====
Keep Bot, remove all bots without the given partial name
Usage: /bot keepbot <partial botname>

====kg====
Kill Goal, damage a given goal if cheats are allowed
Usage: /bot kg <goalname>

====kt====
Kill Team, kills all bots on the given team
Usage: /bot kt <teamname>

====makegm====
Make GM, creates a map script and test map script for the current map
Usage: /bot makegm

====makemapgm====
Make Map GM, creates a map script for the current map
Usage: /bot makemapgm

====makemapgoallist====
Make Map Goal List, creates a map goal list for the current map
Usage: /bot makemapgoallist

====maketestmapgm====
Make Test Map GM, creates a test map script for the current map
Usage: /bot maketestmapgm

====maxbots====
The maximum bots to keep in play. It is the number of all players (bots + humans). The MaxBots value is saved to file omni-bot.cfg (but only if SaveConfigChanges = 1). Bots automatically join game if there are not enough human players. Bots leave game after new human player selects team (if CountSpectators = 0), or when new player connects to the server (if CountSpectators = 1). If you want to add bots or kick bots manually, you can set maxbots to -1.

Usage: bot maxbots 20
It can be also set in the referee menu in the legacy mod.

====maxxp====
Max xp before bots should reset.
Version note: ET Only

====minbots====
The minimum players to keep in play.

syntax: bot minbots #
example: bot minbots 2

====minformobilemg====
set the minimum number of players playing in order for bots to choose the mobile mg42.
Version note: ET Only

====minformortar====
set the minimum number of players playing in order for bots to choose the mobile mortar.
Version note: ET Only

====moveskill====
Combat Difficulty, sets persistent combat movement difficulty
0 = off, 1 = easy, 2 = medium, 3 = hard, 4 = random

====mypos====
My Position, gets the players current position
Usage: /bot mypos

====mywpmode====
My Waypoint Mode, enables waypoint view and autosave
Usage: /bot mywpmode

====numthreads====
Number of Threads, prints the number of current threads
Usage: /bot numthreads

====plantnext====
Advance to the next PLANT goal position. It will automatically select the goal. Waypoint tool for adding cover spots.
Version note: ET only

====plantstart====
Start iterating through the PLANT goals in the map. Waypoint tool for adding cover spots.
Version note: ET only

====resetxp====
Enables bots resetting xp. Use 1 to enable or -1 to disable.

Shrubbot is required. Flag M must be enabled for level 0 in the file shrubbot.cfg.
Version note: ET only

====rollcall====
Roll Call, lists each bots name, team, class, and entity
Usage: /bot rollcall

====sag====
alias for showactive

====saveplayerpos====
Writes player positions to a file in user folder.

====saveusepoint====
Writes player position as Util.AddUsePoint command to a file in user folder. Optional parameter is goal name expression.

====sei====
alias for showentityinfo

====sendtrigger====
Test command and example of sending a trigger from script.

====sg====
Set Goal, enables the given goalname for the given team
Usage: /bot sg <goalname> <team>

====sgi====
Show Goal Info, lists information about the given goal
Usage: /bot sgi <goalname>
Note: lists goals health, DEAD status, entity number, and position

====sgn====
Show Goal Name, lists all goals found within the given radius
Usage: /bot sgn <radius> <optional true>
Note: passing the optional true parameter will give player offset

====sgo====
Show Goal Offset, lists players offset to the given goal
Usage: /bot sgo <goalname>

====showactive====
Show Active Goals, lists each currently active goal by team
Usage: /bot sag <optional team 0/1/2> <optional routes> <optional showuse>

====showentityinfo====
Show Entity Info, runs a traceline and returns Entity information
Usage: /bot showentityinfo <optional traceType>

====showevents====
Show Events, lists all events in the EVENT table
Usage: /bot showevents

====showgroup====
Lists all goals of a given group in console.

====showweapons====
Show Weapons, lists all weapons in the WEAPON table
Usage: /bot showweapons

====skip====
Skip, sets Util.Skip to true
Usage: /bot skip
Note: Util.Skip is used in some debugging functions

====skipreset====
Skip Reset, sets Util.Skip to false
Usage: /bot skipreset
Note: Util.Skip is used in some debugging functions

====spp====
alias for saveplayerpos

====stresstest====
Stress Test, this command should only be used by developers
Usage: /bot stresstest

====stucknext====
Used for stuckage checking. Advance to the next stuckage position.

====stuckstart====
Start iterating through the stuckage table for the map. Before you use this command, you must move file <mapname>_stuckages.gm from et/user folder to et/scripts folder.

====sup====
alias for saveusepoint

====sysusage====
Writes a timeline of system usage stats to systemtimeline.gm.

====table_members====
Prints a sorted list of table members to the console for the given table name.

====test_priorities====
Test Priorities, test SetGoalPriorities calls on all map goals
usage, /bot test_priorities <bool allgoals>
example: /bot test_priorities true will loop through all goals in the map table

====testbot====
Test Bot, adds a testbot to the given team with the given class
Usage: /bot testbot <team> <class>
Usage: /bot testbot 0 - kicks the test bot

====testmap====
Test Map, starts the auto testing of maps based on the testmap scripts
Usage: /bot testmap

====testme====
Test command, prints out all arguments
Usage: /bot testme

====testsuicide====
Set Suicide, sets botSuicide session variable to given param
Bots will /kill 2 seconds before next spawn
Version note: RTCW only

====testvoice====
Test Voice Macro, used for testing a bots usage of given voice macro
usage, /bot testvoice <partial bot name> <voice macro name>
example, /bot testvoice Walt NEED_MEDIC

====testwin====
Test Windows, tests the debug window script testdebugwindows.gm
Usage: /bot testwin

====time====
Echo's the current time to the screen.

====trace_pos====
Prints position from a trace.

====tracearty====
Runs a trace to find visible Artillery_s or Artillery_d goals from closest Callartillery goal.

====tracebox====
Trace Box, builds an AABB based on the players position
Usage: /bot tracebox

====tracetrajectory====
Draws trajectory from player position and facing.
Usage: /bot tracetrajectory speed <optional interval> <optional duration> <optional bounceloss>

====trigger_aimpos====
Trigger Aim Position, creates a region trigger based on the players aim position
Usage: /bot trigger_aimpos

====trigger_bounds====
Trigger Bounds, builds an AABB region trigger based on the players position
Usage: /bot trigger_bounds

====wab====
alias for warpanybot

====warpanybot====
Will teleport a bot matching given name to the player if cheats are enabled.

====warpbot====
Warp Test Bot, will teleport testbot to given waypoint name or player position if cheats are enabled.
Usage: /bot warpbot <optional wpname>

====warpto====
Warp To, will teleport player to given goal or waypoint name if cheats are enabled.
ET accepts also waypoint ID or paththrough name.
Usage: /bot warpto <goalname|wpname>

====warptogoaloffset====
Warp To Goal Offset, will teleport player to given goal real world offset if cheats are enabled
Usage: /bot warptogoaloffset <goalname>

====wb====
alias for warpbot

====wiki_commands====
Writes all script commands to a file in wiki markup.

====wpa====
Waypoint Array, adds an array of waypoints numx by numy, distx and disty apart
Usage: /bot wpa <numx> <distx> <numy> <disty>

====wt====
alias for warpto

====wtgo====
alias for warptogoaloffset

Scripting waypoints flags

2025-05-16T12:29:18Z

Palota:

{{process header
| title = Scripting Waypoints flags
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

During the process of running a map things can change such as doors no longer been axis only.

The following flags can be added/removed via script

* axis
* allies
* closed

There are a few other flags that can be added removed but these are the only ones that you are likely to need to change in the game.

The waypoint must be named in the map "''/bot waypoint_setname name''" so the script knows which waypoint to add/remove the flag

The command to use in the script is "''Wp.SetWaypointFlag''".

<syntaxhighlight lang="java">
Wp.SetWaypointFlag( "waypoint_name", "flag", true/false );</syntaxhighlight>

This command initially must be added to the "''global OnMapLoad''" section so the status of the flag is known at the start of the map. The flag must then be added to any ''function triggers'' that causes the need to add/remove the flag.

Below is an example of the script to remove a axis only flag to allow both teams to use.

<syntaxhighlight lang="java">
global Map =
{
Main_Entrance_Destroyed = function()
{
Wp.SetWaypointFlag( "door1", "axis", false );

Util.MapDebugPrint( "Main_Entrance_Destroyed" );
},
};

global OnMapLoad = function()
{
OnTrigger( "Allies have destroyed the main entrance", Map.Main_Entrance_Destroyed );

Wp.SetWaypointFlag( "door1", "axis", true );
};
</syntaxhighlight>

Note: Using this to remove a closed flag is not needed on blockable section of a map unless the blockwall flag does not work like in the Caen map.

Changing spawns

2025-05-16T12:24:59Z

Palota:

Spawn points should always be changed in the '''OnBotJoin''' function, otherwise they would not work on dedicated servers, because players can join or leave during game.

You need to change spawn points in triggers too. It is recommended to define one function which will be called from both triggers and OnBotJoin.

This example sets spawn point for 50% of allied bots after they have taken the gold. You can adjust number 5 after RandInt if you want more or less bots to use new spawn.

<syntaxhighlight lang="java">
global Map =
{
TruckLoaded = false,

SetSpawn1 = function(bot)
{
if (bot.GetTeam() == TEAM.ALLIES) {
if (Map.TruckLoaded && RandInt(0,9) < 5) {
bot.ChangeSpawnPoint(3);
} else {
bot.ChangeSpawnPoint(0);
}
}
},

SetSpawn = function()
{
foreach(bot in BotTable)
{
Map.SetSpawn1(bot);
}
},

allies_taking_gold = function()
{
Map.TruckLoaded = true;
Map.SetSpawn();
},
};

global OnMapLoad = function()
{
OnTrigger( "Allied team is escaping with the Gold Crates!", Map.allies_taking_gold );
};

global OnBotJoin = function( bot )
{
Map.SetSpawn1(bot);
};
</syntaxhighlight>

Roles

2025-05-16T12:23:51Z

Palota: /* Region triggers */

{{process header
| title = Roles
| section =
| previous = [[Omni-Bot_Map_Scripting| Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

== Intro ==

Bot roles were added in version 0.8 as a method to focus specific bots on specific goals. Any goal that has a role defined will be ignored by bots that do not have the same role defined. This is particularly useful when there are multiple defense points in a map that are simultaneously active or in large dual objective maps.

The Enemy Territory map Radar is one such example as the last stage of the map has two separate objectives for the Allied team to steal; the East and West Radar Parts. The defense has been setup so that one group of defenders will focus on the West Parts and another will focus on the East Parts. Since the defend goals have an equal priority, setting roles ensures that the bots won't be wandering between locations; which results in a much weaker defense.

Another very specific usage of roles is for Covert Ops bots in Enemy Territory that have the ability to steal an enemies uniform. Once in uniform, the bot is automatically assigned an Infiltrator role; which makes certain goals available that normally would not be reachable.

A more common use of roles would be for the Capture the Flag type maps seen in Doom 3 and Quake 4 as there is a need for dedicated base defenders.

Roles however are not limited to the scenarios given. Any time there is a need for specific goals to be limited in usage to one or more bots, setting roles is a simple way to solve the problem.

== Setup ==

Setup requires that both bots and goals are given the desired roles with one of the predefined roles. Valid roles are as follows:

<syntaxhighlight lang="java">
ROLE.ATTACKER
ROLE.ATTACKER1
ROLE.ATTACKER2
ROLE.ATTACKER3
ROLE.OFFENSECAPTAIN
ROLE.DEFENDER
ROLE.DEFENDER1
ROLE.DEFENDER2
ROLE.DEFENDER3
ROLE.DEFENSECAPTAIN
ROLE.TEAMCAPTAIN
ROLE.FIRETEAMCAPTAIN
ROLE.AMBUSHER
ROLE.INFILTRATOR
ROLE.ROAMER
ROLE.SNIPER
ROLE.ESCORT
</syntaxhighlight>

=== Goals ===

Roles can be added to goals either in the editor or in a map script. To add a role in the editor, simply use the following commands:
/bot goal_edit
/bot goal_setproperty roles DEFENDER
/bot goal_finish

You can set multiple roles on a goal by using the | operator:
/bot goal_setproperty roles DEFENDER|DEFENDER1

Once completed, /bot goal_save will commit the changes to the goals file.

Setting roles in the editor is preferred since it reduces script size, but users wishing to set them in the map script can use the following helper functions:

<syntaxhighlight lang="java">
SetGoalRole( <goal expression or table>, <roles>, <persistent> );
Util.SetRoleForGroup( <goal group>, <roles> );
ClearGoalRole( <goal expression or table>, <roles> );
Util.ClearRoleForGroup( <goal group>, <roles> );
</syntaxhighlight>

For example:

<syntaxhighlight lang="java">
SetGoalRole("DEFEND_East.*", ROLE.DEFENDER); //set the defender role on goals that have a name starting with DEFEND_East
SetGoalRole("DEFUSE_wall.*", ROLE.DEFENDER2, true); //set role for dynamically created goal
SetGoalRole("MOUNTMG42_bank", { ROLE.DEFENDER2, ROLE.DEFENDER3 }); //set multiple roles to one goal
SetGoalRole({ "DEFEND_docs.*", "MOUNTMG42_docs" }, ROLE.DEFENDER1); //set role on multiple goals
</syntaxhighlight>

=== Priority ===

Almost every map goal has property RolePriorityBonus which is added to priority if the goal has any role. That's why bots prefer goals which have role. Camp goals (attack/defend/camp/snipe) have RolePriorityBonus only 0.01. Other goals have RolePriorityBonus 0.1.

Sometimes the default RolePriorityBonus is not enough and it's necessary to use function SetGoalPriority to change priorities. For example, if some CHECKPOINT goal without role is active, all DEFEND goals are ignored and all bots go to capture checkpoint. Even if the DEFEND goals have DEFENDER role and some bots have DEFENDER role, nobody will use DEFEND goals if they have default priority.

=== Bots ===

The simplest way to assign bot roles is to set up the map script to use the Role Manager. The Role Manager will automatically assign the bots' roles based on a Map.Roles table in the map script.

A commented example of the Role Manager setup:

<syntaxhighlight lang="java">
global Map =
{
Roles =
{
AXIS = // Team
{
AllBots = true, // each bot is considered for a role
DEFENDER = // the DEFENDER role
{
voice = "defend", // signals voice chat to randomly announce
spawnpt = 2, // users of this role will choose spawnpt 2
numbots = 4, // maximum of 4 bots
crucialClass = CLASS.ENGINEER, // class for the first bot
MinBotsForRole = 4, // only assign this role if there are already 4 bots in game
},
ATTACKER =
{
voice = "attack",
numbots = 4,
crucialClass = {CLASS.ENGINEER, CLASS.COVERTOPS}, //the first is engineer, the second is covertops
},
},

ALLIES =
{
AllBots = false, // default: every other bot
DEFENDER =
{
numbots = 3,
},
ATTACKER =
{
numbots = 4,
},
},
},
};
</syntaxhighlight>

In this example, each team will have bots assigned to two different roles. For each role there can be a maximum number of bots set, a spawn point defined, a crucial class given, and even a voice chat for the bot to randomly use when assigned the role. All of the role flags are optional except for numbots:

numbots - the number of bots the role manager will attempt to keep assigned the role at all times
crucialClass - the first bot assigned the role will switch to this class, can be a table of classes for more bots
spawnpt - bots with this role will choose this spawn point
voice - "attack" and "defend" are the two valid values
MinBotsForRole - set the number of bots required to be in game before assigning the role.

=== Region triggers ===

If some goals are behind a door or gate which can be opened or destroyed by one team, and closed or rebuilt by the other team, then it is recommended to use region triggers. It will prevent path failed errors. It is usually possible to create one large region which covers entire area behind door (see maps mml_minastirith_fp3, nod_temple). Bots inside the region will have a role, but bots outside the region will not have the role. Goals behind door or gate will have the role only if the door is closed or gate is built.

<syntaxhighlight lang="java">
Rocket_room =
{
Name = "Rocket_room",
TriggerOnClass = CLASS.ANYPLAYER,
OnEnter = function(ent)
{
bot = Util.IsBot(ent);
if(bot){ bot.SetRoles(ROLE.ATTACKER); }
},
OnExit = function(ent)
{
bot = Util.IsBot(ent);
if(bot){ bot.ClearRoles(ROLE.ATTACKER); }
},
},

Door_Open = function()
{
ClearGoalRole({ "PLANT_rocket", "ATTACK_rocket.*" }, ROLE.ATTACKER);
},

Door_Close = function()
{
SetGoalRole({ "PLANT_rocket", "ATTACK_rocket.*" }, ROLE.ATTACKER);
},
</syntaxhighlight>

Sometimes it's not possible to create one large region (see map sfx_endor). Then it is necessary to create the first region just behind the gate (OnEnter function sets bot's role) and other regions in front of the gate and at every spawn (OnEnter function clears bot's role).

Talking bots

2025-05-16T12:18:28Z

Palota: /* Scripting */

{{process header
| title = Talking Bots
| section =
| previous = [[Omni-Bot_Map_Scripting | Omni-Bot_Map_Scripting]]
| next =
| shortcut =
| notes =
}}

== Before you make the bots talk ==

Be aware that bots talking too much can annoy players so please be sensible when using this command.

== Forward ==

In previous versions of omni-bot the normal way to make the bots talk was to set up a random number & depending on the number the bots would talk.

In 0.81, a Three new commands were added to get rid of the old commands need to use a random number to define the number of bots that would talk.

Util.BotSay
ETUtil.WinningChat
ETUtil.LosingChat

== Usage ==

=== Util.BotChat ===

<syntaxhighlight lang="java">
Util.BotChat (Team, msgType, Msg, NumBots)</syntaxhighlight>

Team:

<syntaxhighlight lang="java">"TEAM.ALLIES" / "TEAM.AXIS" / "0" </syntaxhighlight>

MsgTypes:

<syntaxhighlight lang="java">"say", "sayteam", "vsay"</syntaxhighlight>

Msg:

For say/sayteam this is just plain text. For vsay this must be one of the voicechat commands defined on the [[VOICE | Voice page]]

NumBots :

The number of bots that will speak. Please do not set to a high number.

=== ETUtil.WinningChat ===

Team:

<syntaxhighlight lang="java">"TEAM.ALLIES" / "TEAM.AXIS" / "0" </syntaxhighlight>

Example :

<syntaxhighlight lang="java">ETUtil.WinningChat( TEAM.ALLIES );</syntaxhighlight>

=== ETUtil.LosingChat ===

Team:

<syntaxhighlight lang="java">"TEAM.ALLIES" / "TEAM.AXIS" / "0" </syntaxhighlight>

Example :

<syntaxhighlight lang="java">ETUtil.LosingChat( TEAM.AXIS );</syntaxhighlight>

== Notes ==

There is no longer the need to add "Talk = true," remove this line if you are using the new command on an old script.

Wether or not the bots talk is defined in ~omni-bot\et\scripts\et_autoexec.gm
Default is this
global MAP_TALK = true;
If this line is set to false the bots will not talk

== Scripting ==

'''One Axis bot saying a plain text message to all players'''

<syntaxhighlight lang="java">
global Map =
{
Radar_Destroyed = function()
{
Util.BotChat(TEAM.AXIS, "say", "Pesky Allies", 1);

Util.MapDebugPrint( "Radar_Destroyed" );
},
};
</syntaxhighlight>

'''One Allied bot saying a plain text message to team.'''

<syntaxhighlight lang="java">
global Map =
{
Radar_Destroyed = function()
{
Util.BotChat(TEAM.ALLIES, "sayteam", "ok lets get the doc's now", 1);

Util.MapDebugPrint( "Radar_Destroyed" );
},
};
</syntaxhighlight>

'''Two bots for both teams saying a voicechat command.'''

<syntaxhighlight lang="java">
global Map =
{
Axis_Break_Something = function()
{
Util.BotChat(TEAM.AXIS, "vsay", VOICE.G_CHEER, 2);
Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_NEGATIVE, 2);

Util.MapDebugPrint( "Axis_Break_Something" );
},
};
</syntaxhighlight>

''' Example for end of a map where the bots Cheer/Say no'''

<syntaxhighlight lang="java">
global Map =
{
Allies_win = function()
{
ETUtil.WinningChat( TEAM.ALLIES );
ETUtil.LosingChat( TEAM.AXIS );

Util.MapDebugPrint( "Allies_win" );
},
};
</syntaxhighlight>

Template:Baserouting

2025-05-16T12:15:13Z

Palota: /* Step 3: Scripting the routes */

[[Category:ET|Routing]]
[[Category:Doom 3|Routing]]
[[Category:Quake 4|Routing]]
[[Category:RTCW|Routing]]
[[Category:Waypointing]]
==Routing Overview==

Until version 0.65, omni-bot path selection relied on the shortest path to a goal. While this typically provided for very focused attacks, game play became very predictable. The solution is Routing. Routing provides alternate goals for the bots to go to before heading to their main goal. When positioned correctly, these alternate goals provide the effect of bots choosing realistic and varied paths to their main goals.

Routing requires some setup in script and in the waypoints, but the results are worth the effort. The objective of this article is to provide an overview of how the routing system works and to clearly define how to set it up by walking through a working example on Goldrush.

[[Image:Gr_routes2.jpg|Goldrush Multiple Routes Example]]

In this picture, Squares are route nodes and the Dots are potential paths. The color of the Dots correspond to the color of the Route nodes. Once they reach a route node, they will travel along the path(s) of the same color IF the route node is set up for their current main goal.

Walking through the picture, let’s say the tank construction goal is set up for an allied engineer within the AllySpawn route nodes, and that the engineer has the tank construct as its goal. The engineer will randomly choose whether to go to the green route node (as_right) or the yellow route node (depotgate). For the purpose of this example, let’s say the bot chose to go to the green route node. From there, he will randomly choose to go to the white or red route node. The bot will continue to make these decisions until there are no route nodes left to go to. From that point, the bot will take the shortest path to the tank construct goal.
As you can see, this opens up several different points of attack for the bots; which creates a sense of realism in terms of predictability. Defenses will now need to be set up to be able to react to all of the entry points rather than focusing on easily predicted choke points if the shortest path is always used.

==Setting It Up==

Setting up Routes involves waypointing and scripting. This section will take you step by step through the process of setting up the routes in the Goldrush example.

===Step 1: Setting up the script===

The first requirement for routing is that the routes are defined in the map script. The method to do this consists of building a table for the routes and calling a utility function that will register the routes.

If a map script does not exist yet, open up your favorite text editor and add the following to a new file:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
}; </syntaxhighlight>

Save the file as <mapname>.gm in your Omni-Bot\et\nav folder. You are now ready to start building the routes. Inside the InitializeRoutes function is where the route definitions are placed and they all start with a basic layout:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You now have a MapRoutes table defined and are registering everything within that table with the Util.Routes function.

===Step 2: Adding route goal ===

Route goals are fairly straight forward. They have two important properties; route name and radius. You can use any name you want for the route nodes, but they should be somewhat intuitive. To see the full guide on adding route goals see the [[Route_Goal]] page.

Route goals are placed in positions where a bot might receive the goal you want them to use alternate paths for. The bot MUST be inside the route node radius when receiving a goal for it to work. Spawn points are good spots for route nodes because bots always receive a goal when they spawn.

In the spawns area you need to place the goal over the spawn positions and give it a large radius to cover the spawn points. Issue the following commands in console:

/bot show_spawns
/bot goal_create route AllySpawn
/bot goal_setproperty radius 500
/bot goal_finish

The radius of the route nodes at spawn positions are very critical because the bots must be inside its radius for it to work. Be sure that the radius covers the entire spawn area. Bots do not always receive goals immediately at spawn. Sometimes they receive goals 2 seconds after spawn. That's why it's always better to set bigger radius. But be careful, route nodes must not overlap.

For routing to be effective, you will need at least two defined because once they reach the route node, they will take the shortest path to their goal UNLESS there is another route node set up for them to go to. Continuing with our example, create a route node where the green square is in the picture and name it as_right:

/bot goal_create route as_right
/bot goal_finish

You now have two route nodes; meeting the requirement for working routes. In our example, we want the bots to use two paths from the spawn, so add the route node depicted by the yellow square at the depot gate:

/bot goal_create route depotgate
/bot goal_finish

Be sure to save the goals at this point. The next step is to set up the goals and route node selection in the script.

/bot goal_save

===Step 3: Scripting the routes===

The Maproutes table is set up with the following format:
<syntaxhighlight lang="java">
MapRoutes =
{
GOALNAME =
{
ROUTNAME = {},
},
GOALNAME2 =
{
ROUTENAME = {},
},
};</syntaxhighlight>

If you are new to map scripting, this may appear a bit intimidating. The key is to follow the steps and syntax exactly, then let the understanding of the syntax come naturally. If you are comfortable with gm scripting, the routing set up consists of nested tables.

The goal name must match the output from show_goals and the route name is the waypoint name prepended with ROUTE_. For the Goldrush example, set up the tank construct routing as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You have just added a map goal to the Maproutes table. The syntax of the goal name is VERY important. Be sure to double check the goal name with /bot show_goals. Once you are sure the goal name is correct, you can add the route nodes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn = {},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

The AllySpawn route node is now a valid route node for the tank construct goal. If a bot spawns within its radius and receives the tank construct as a goal, it will use that route node. In and of itself, this route node will not do anything because at spawn the bot is already at it. So let’s add the two path options we want to give the bots from the Allied Spawn:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

It’s important to understand what we just did with this:
<syntaxhighlight lang="java">
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},</syntaxhighlight>

The bot reaches the AllySpawn route node by default when it spawns; and because we have added the two routes inside the brackets, the bots will randomly choose between them. At this point, you have randomized routes for Allied engineers with the tank construct goal. Half the time they will choose to go to route as_right and half the time they will choose to go to route depotgate.

Let’s make them even less predictable. Looking at the example picture, you can see that we want them to have a couple different options once they reach the route nodes we just set up. Repeating step 2, add the rest of the route nodes depicted by the colored squares.

The scripting for the path options in the picture is as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right =
{
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
ROUTE_depotflank = {},
},
},
ROUTE_depotgate =
{
ROUTE_cproute = {},
ROUTE_depotgatesplit = {},
ROUTE_as_rightsplit1 = {},
},
},
},
};

Util.Routes(Maproutes);
}; </syntaxhighlight>

===Step 4: Testing the routes===

Testing the routes is by far the most important step. It is recommended that you test routes individually as you start to learn the routing system. Once you are comfortable with the setup, you may want to add routes for an entire phase and then test them to make the process a bit faster.

If the routing is not working as expected, there are some basic troubleshooting options. It’s important to remember the criteria for the routes; the bot must be within the radius of the route node when receiving the goal, and the route node must be set up to support the goal. The basic troubleshooting steps are:

# Check in console when the map loads for any error messages. It should list any goal names not found when initializing the routes.
# Check the radius of the route where the bot receives the goal
# Make sure the bot can reach the goal
# Make sure the bot is getting the expected goal

For numbers 2 and 3, consider using the command /bot debugbot all goals with only one bot connected. In console, it should give success / failure messages for short term and long term goals. An example of a known problem is if there are priority type goals (like radar parts stealing) that are active when they aren’t reachable. The solution is to set them to be not active in OnMapLoad if they are unreachable.

===Step 5: Adding priorities to routes===

In some cases, you may want bots to use a certain route more often than others. This can be done by adding a “weight” to the route table:
<syntaxhighlight lang="java">
ROUTE_as_right =
{
Weight = 2,
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
Weight = 2,
ROUTE_depotflank = {},
},
},</syntaxhighlight>

In this example, the bots will randomly choose to go to route as_right twice as much as route depotgate. And then they will choose to go to route as_rightsplit2 twice as much as route as_rightsplit1.

===Step 6: Copying routes===

If you have more than one goal that you want to share the same routing with, you can copy the routing. In the Goldrush example, say we have some attack goals in the yard that we want to route to. Rather than writing out the tables for each attack goal, we can copy them like this:
<syntaxhighlight lang="java">
MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;
</syntaxhighlight>

The key point to remember when doing this is that the route table that exists must be on the right side of the equation. In this case, we have created routes for multiple attack goals and a mount goal that are the same as our example routing to build the tank.

These should be placed in OnMapLoad as well, below the Maproutes table and above the Utility function that registers the routes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_Tank =
{

},
};

MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;

Util.Routes(MapRoutes);
};</syntaxhighlight>

===Step 7: Toggling routes===

Routes are treated very similar to map goals. They will show up in your list if you do a /bot show_goals. They can be turned on and off via scripting with the SetAvailableMapGoals function. As an example, say we have route that we want opened up when barrier is destroyed, then closed when that barrier is constructed. This can be done inside the OnTriggers for those events:
<syntaxhighlight lang="java">
Barrier_construct = function ()
{
Util.DisableGoal( "ROUTE_routname" );
};

Barrier_destroyed = function ()
{
Util.EnableGoal( "ROUTE_routname" );
};
</syntaxhighlight>

===Step 8: Route maker===
* Windows users can use the route maker tool to easily create routes.
* Download it from http://svn.assembla.com/svn/omnibot/Enemy-Territory/0.8/tools/route_tool/
* Extract both RouteMaker.zip and RouteMaker2.zip into the same folder.
* Run RouteMaker2.exe
* You must set rcon password on your Enemy Territory or RTCW server.
* Then use menu command File / Load From RCON
* Drag & drop goals from left panel into middle panel.
* Drag & drop routes from right panel into middle panel.
* Double-click to delete routes.
* Finally use menu command Write / Script
* Output script will be copied to the clipboard. Paste it into the InitializeRoutes function in your map gm script.

===Step 9: Ask for help===

If you are having trouble with the syntax, set up, or understanding the routing system, ask for help. This guide is by no means comprehensive and complex maps will offer different challenges. Please post in the forums if you have questions / problems / bug reports.

Template:Baserouting

2025-05-16T12:10:47Z

Palota: /* Step 7: Toggling routes */

[[Category:ET|Routing]]
[[Category:Doom 3|Routing]]
[[Category:Quake 4|Routing]]
[[Category:RTCW|Routing]]
[[Category:Waypointing]]
==Routing Overview==

Until version 0.65, omni-bot path selection relied on the shortest path to a goal. While this typically provided for very focused attacks, game play became very predictable. The solution is Routing. Routing provides alternate goals for the bots to go to before heading to their main goal. When positioned correctly, these alternate goals provide the effect of bots choosing realistic and varied paths to their main goals.

Routing requires some setup in script and in the waypoints, but the results are worth the effort. The objective of this article is to provide an overview of how the routing system works and to clearly define how to set it up by walking through a working example on Goldrush.

[[Image:Gr_routes2.jpg|Goldrush Multiple Routes Example]]

In this picture, Squares are route nodes and the Dots are potential paths. The color of the Dots correspond to the color of the Route nodes. Once they reach a route node, they will travel along the path(s) of the same color IF the route node is set up for their current main goal.

Walking through the picture, let’s say the tank construction goal is set up for an allied engineer within the AllySpawn route nodes, and that the engineer has the tank construct as its goal. The engineer will randomly choose whether to go to the green route node (as_right) or the yellow route node (depotgate). For the purpose of this example, let’s say the bot chose to go to the green route node. From there, he will randomly choose to go to the white or red route node. The bot will continue to make these decisions until there are no route nodes left to go to. From that point, the bot will take the shortest path to the tank construct goal.
As you can see, this opens up several different points of attack for the bots; which creates a sense of realism in terms of predictability. Defenses will now need to be set up to be able to react to all of the entry points rather than focusing on easily predicted choke points if the shortest path is always used.

==Setting It Up==

Setting up Routes involves waypointing and scripting. This section will take you step by step through the process of setting up the routes in the Goldrush example.

===Step 1: Setting up the script===

The first requirement for routing is that the routes are defined in the map script. The method to do this consists of building a table for the routes and calling a utility function that will register the routes.

If a map script does not exist yet, open up your favorite text editor and add the following to a new file:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
}; </syntaxhighlight>

Save the file as <mapname>.gm in your Omni-Bot\et\nav folder. You are now ready to start building the routes. Inside the InitializeRoutes function is where the route definitions are placed and they all start with a basic layout:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You now have a MapRoutes table defined and are registering everything within that table with the Util.Routes function.

===Step 2: Adding route goal ===

Route goals are fairly straight forward. They have two important properties; route name and radius. You can use any name you want for the route nodes, but they should be somewhat intuitive. To see the full guide on adding route goals see the [[Route_Goal]] page.

Route goals are placed in positions where a bot might receive the goal you want them to use alternate paths for. The bot MUST be inside the route node radius when receiving a goal for it to work. Spawn points are good spots for route nodes because bots always receive a goal when they spawn.

In the spawns area you need to place the goal over the spawn positions and give it a large radius to cover the spawn points. Issue the following commands in console:

/bot show_spawns
/bot goal_create route AllySpawn
/bot goal_setproperty radius 500
/bot goal_finish

The radius of the route nodes at spawn positions are very critical because the bots must be inside its radius for it to work. Be sure that the radius covers the entire spawn area. Bots do not always receive goals immediately at spawn. Sometimes they receive goals 2 seconds after spawn. That's why it's always better to set bigger radius. But be careful, route nodes must not overlap.

For routing to be effective, you will need at least two defined because once they reach the route node, they will take the shortest path to their goal UNLESS there is another route node set up for them to go to. Continuing with our example, create a route node where the green square is in the picture and name it as_right:

/bot goal_create route as_right
/bot goal_finish

You now have two route nodes; meeting the requirement for working routes. In our example, we want the bots to use two paths from the spawn, so add the route node depicted by the yellow square at the depot gate:

/bot goal_create route depotgate
/bot goal_finish

Be sure to save the goals at this point. The next step is to set up the goals and route node selection in the script.

/bot goal_save

===Step 3: Scripting the routes===

The Maproutes table is set up with the following format:
<syntaxhighlight lang="java">
MapRoutes =
{
GOALNAME =
{
ROUTNAME = {},
},
GOALNAME2 =
{
ROUTENAME = {},
},
};</syntaxhighlight>

If you are new to map scripting, this may appear a bit intimidating. The key is to follow the steps and syntax exactly, then let the understanding of the syntax come naturally. If you are comfortable with gm scripting, the routing set up consists of nested tables.

The goal name must match the output from show_goals and the route name is the waypoint name prepended with ROUTE_. For the Goldrush example, set up the tank construct routing as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

You have just added a map goal to the Maproutes table. The syntax of the goal name is VERY important. Be sure to double check the goal name with /bot show_goals. Once you are sure the goal name is correct, you can add the route nodes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn = {},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

The AllySpawn route node is now a valid route node for the tank construct goal. If a bot spawns within its radius and receives the tank construct as a goal, it will use that route node. In and of itself, this route node will not do anything because at spawn the bot is already at it. So let’s add the two path options we want to give the bots from the Allied Spawn:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},
},
};

Util.Routes(MapRoutes);
}; </syntaxhighlight>

It’s important to understand what we just did with this:
<syntaxhighlight lang="java">
ROUTE_AllySpawn =
{
ROUTE_as_right = {},
ROUTE_depotgate = {},
},</syntaxhighlight>

The bot reaches the AllySpawn route node by default when it spawns; and because we have added the two routes inside the brackets, the bots will randomly choose between them. At this point, you have randomized routes for Allied engineers with the tank construct goal. Half the time they will choose to go to route as_right and half the time they will choose to go to route depotgate.

Let’s make them even less predictable. Looking at the example picture, you can see that we want them to have a couple different options once they reach the route nodes we just set up. Repeating step 2, add the rest of the route nodes depicted by the colored squares.

The scripting for the path options in the picture is as follows:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_tank_construct =
{
ROUTE_AllySpawn =
{
ROUTE_as_right =
{
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
ROUTE_depotflank = {},
},
},
ROUTE_depotgate =
{
ROUTE_cproute = {},
ROUTE_depotgatesplit = {},
ROUTE_as_rightsplit1 = {},
},
},
},
};

Util.Routes(Maproutes);
}; </syntaxhighlight>

===Step 4: Testing the routes===

Testing the routes is by far the most important step. It is recommended that you test routes individually as you start to learn the routing system. Once you are comfortable with the setup, you may want to add routes for an entire phase and then test them to make the process a bit faster.

If the routing is not working as expected, there are some basic troubleshooting options. It’s important to remember the criteria for the routes; the bot must be within the radius of the route node when receiving the goal, and the route node must be set up to support the goal. The basic troubleshooting steps are:

# Check in console when the map loads for any error messages. It should list any goal names not found when initializing the routes.
# Check the radius of the route where the bot receives the goal
# Make sure the bot can reach the goal
# Make sure the bot is getting the expected goal

For numbers 2 and 3, consider using the command /bot debugbot all goals with only one bot connected. In console, it should give success / failure messages for short term and long term goals. An example of a known problem is if there are priority type goals (like radar parts stealing) that are active when they aren’t reachable. The solution is to set them to be not active in OnMapLoad if they are unreachable.

===Step 5: Adding priorities to routes===

In some cases, you may want bots to use a certain route more often than others. This can be done by adding a “weight” to the route table:
<syntaxhighlight lang="java">
ROUTE_as_right =
{
Weight = 2,
ROUTE_as_rightsplit1 = {},
ROUTE_as_rightsplit2 =
{
Weight = 2,
ROUTE_depotflank = {},
},
},</syntaxhighlight>

In this example, the bots will randomly choose to go to route as_right twice as much as route depotgate. And then they will choose to go to route as_rightsplit2 twice as much as route as_rightsplit1.

===Step 6: Copying routes===

If you have more than one goal that you want to share the same routing with, you can copy the routing. In the Goldrush example, say we have some attack goals in the yard that we want to route to. Rather than writing out the tables for each attack goal, we can copy them like this:
<syntaxhighlight lang="java">
MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;
</syntaxhighlight>

The key point to remember when doing this is that the route table that exists must be on the right side of the equation. In this case, we have created routes for multiple attack goals and a mount goal that are the same as our example routing to build the tank.

These should be placed in OnMapLoad as well, below the Maproutes table and above the Utility function that registers the routes:
<syntaxhighlight lang="java">
global InitializeRoutes = function()
{
MapRoutes =
{
BUILD_Tank =
{

},
};

MapRoutes["ATTACK_Depot_.*"] = MapRoutes.BUILD_tank;
MapRoutes.MOUNT_tank = MapRoutes.BUILD_Tank;

Util.Routes(MapRoutes);
};</syntaxhighlight>

===Step 7: Toggling routes===

Routes are treated very similar to map goals. They will show up in your list if you do a /bot show_goals. They can be turned on and off via scripting with the SetAvailableMapGoals function. As an example, say we have route that we want opened up when barrier is destroyed, then closed when that barrier is constructed. This can be done inside the OnTriggers for those events:
<syntaxhighlight lang="java">
Barrier_construct = function ()
{
Util.DisableGoal( "ROUTE_routname" );
};

Barrier_destroyed = function ()
{
Util.EnableGoal( "ROUTE_routname" );
};
</syntaxhighlight>

===Step 8: Route maker===
* Windows users can use the route maker tool to easily create routes.
* Download it from http://svn.assembla.com/svn/omnibot/Enemy-Territory/0.8/tools/route_tool/
* Extract both RouteMaker.zip and RouteMaker2.zip into the same folder.
* Run RouteMaker2.exe
* You must set rcon password on your Enemy Territory or RTCW server.
* Then use menu command File / Load From RCON
* Drag & drop goals from left panel into middle panel.
* Drag & drop routes from right panel into middle panel.
* Double-click to delete routes.
* Finally use menu command Write / Script
* Output script will be copied to the clipboard. Paste it into the InitializeRoutes function in your map gm script.

===Step 9: Ask for help===

If you are having trouble with the syntax, set up, or understanding the routing system, ask for help. This guide is by no means comprehensive and complex maps will offer different challenges. Please post in the forums if you have questions / problems / bug reports.

Bot

2025-05-13T08:58:40Z

Palota: /* HasTarget */

{{process header
| title = Bot Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Bot Properties==

----

Unless otherwise noted, all properties can be get and set.

=== AimDamping ===
Effects the acceleration and turn rate.
=== AimPersistance ===
The time(in seconds) the bot will continue to aim at the last position of a target before aborting.
=== AimStiffness ===
Effects the acceleration of turning.
=== AimTolerance ===
The tolerance(in degrees) the bot tries to aim at stuff with.
=== Armor ===
Current Armor
=== FieldOfView ===
The angle(in degrees) the bot is capable of 'seeing'.
=== Health ===
Current health.
=== MaxArmor ===
Max Armor
=== MaxHealth ===
Max Health
=== MaxTurnSpeed ===
The maximum speed(in degrees/second) the bot can rotate his aim at.
=== MaxViewDistance ===
The max distance(in game units) the bot is capable of seeing.
=== MemorySpan ===
The time(in seconds) taken for the memory about an entity to become stale.
=== Name ===
Name of the bot.

=== ReactionTime ===
The time(in seconds) it takes the bot to begin responding to a newly sensed threat.

----

=== Enemy Territory Addendum ===

----

==== DoNotKill ====
Set it to true to prevent medics to kill the bot for revive. It is used by BUILD, PLANT and PLANTMINE goals.
==== TargetBreakableDist ====
The maximum distance (in game units) the bot will attempt to target breakable entities. It can be set by [[Pre-Scripted_Regions#BreakableDistance|pre-scripted trigger region]] or inside [[Creating_a_script|OnBotJoin]] function.

----

==Bot Functions==
----
===AddScriptGoal===
Adds a goal to the bots behavior tree by name. Useful when a script goal has AutoAdd set to false, so you can more explicitly control when a bot gets the goal.

'''Parameters:''' (name of script goal to add to bot behavior tree)

'''Returns:''' true on success, false on failure

'''Example:''' <syntaxhighlight lang="java">
b.AddScriptGoal("TestBot");</syntaxhighlight>
----
===RemoveState===
Removes a state from a bots behavior tree by name.

'''Parameters:''' (name of script goal to remove from bot behavior tree)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.RemoveState("TestBot");</syntaxhighlight>
----
===SetStateEnabled===
Enables/Disables a state by name.

'''Parameters:''' (name of state, bool enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetStateEnabled("Attack", false); // disable attack state</syntaxhighlight>
----

===CanGrabItem===
Returns true if bot can take item (flag, gold, radar parts, ...).

'''Parameters:''' (GameEntity)

'''Parameters:''' (FLAG or FLAG_dropped goal name)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if (b.CanGrabItem("FLAG_gold")) {
}</syntaxhighlight>

----

===ChangeClass===
Changes the bot to a specified class.

'''Parameters:''' (classId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeClass(CLASS.SOLDIER);</syntaxhighlight>

----

===ChangeTeam===
Changes the bot to a specified team.

'''Parameters:''' (teamId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeTeam(TEAM.AXIS);</syntaxhighlight>

----

===ClearRoles===
Takes away a role from the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ClearRoles(ROLE.ATTACKER);</syntaxhighlight>

'''See Also:'''
[[Bot#SetRoles| SetRoles]], [[Bot#HasRole| HasRole]]

----

===DisableBotPush===
Used by [[Pre-Scripted_Regions#DisableBotPush|pre-scripted trigger region]].

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DisableBotPush(true);</syntaxhighlight>

----

===DistanceTo===
Overloaded utility function for simplified distance checks.

'''Parameters:''' (Vector3, notUseEyePosition<default false>)

'''Parameters:''' (MapGoal, notUseEyePosition<default false>)

'''Parameters:''' (GameEntity/GameId, notUseEyePosition<default false>)

'''Returns:''' float - distance from bot to Vector3, MapGoal, GameEntity or GameId

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,20,30);
target = b.GetTarget();
// distance from bot to target entity
d1 = b.DistanceTo(target, true);
// distance from bot to world position
d2 = b.DistanceTo(v, true);
// distance from bot eye to world position
d3 = b.DistanceTo(v);</syntaxhighlight>
----

===DumpBotTable===
Dumps a file with the bot's table to a file in the user folder.

'''Parameters:''' (filename)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DumpBotTable("foo.txt");</syntaxhighlight>

----

===Enable===
Disables all thinking for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Enable(false);</syntaxhighlight>

----

===ExecCommand===
Executes a string command on the bot as if the bot executed a console command.

'''Parameters:''' (command)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ExecCommand("kill");</syntaxhighlight>

----

===Weapons/Ammo===
====CanSnipe====
It's deprecated and has been replaced by Util.CanBotSnipe(bot) in Enemy Territory.

Checks if the bot can snipe based on the internally implemented snipe checks. Vary by game. Typically involves checking if the bot has a snipe enabled weapon and has ammo.

'''Parameters:''' none

'''Returns:''' true if the bot can snipe, else false

'''Example:''' <syntaxhighlight lang="java">
if(b.CanSnipe()) {}</syntaxhighlight>

----

====EnableShooting====
Disables all shooting for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.EnableShooting(false);</syntaxhighlight>

----
====GetWeapon====
Gets a reference to a specific weapon from the bot.

'''Parameters:''' (weaponId)

'''Returns:''' [[Weapon]] reference, or NULL if the bot doesn't have the weapon.

'''Example:''' <syntaxhighlight lang="java">
wpn = b.GetWeapon(WEAPON.SHOTGUN);
wpn.PrimaryFire.AimOffset = Vector3(0,0,10);</syntaxhighlight>

----
====GetBestWeapon====
Gets a weapon id for the best weapon versus current target or a specific entity.

'''Parameters:''' none - uses current target

'''Parameters:''' (entity) evaluate weapon versus specific target entity

'''Returns:''' weapon id of weapon that is chosen.

'''Example:''' <syntaxhighlight lang="java">
best = b.GetBestWeapon();
// OR
best = b.GetBestWeapon(someEnt);</syntaxhighlight>

----
====GetRandomWeapon====
Gets a random weapon id from the list of weapons the bot currently has.

'''Parameters:''' none

'''Returns:''' random weapon id

'''Example:''' <syntaxhighlight lang="java">
randwpn = b.GetRandomWeapon();</syntaxhighlight>

----

====GetCurrentWeapon====
Gets the current weapon id for the bot.

'''Parameters:''' none

'''Returns:''' weapon Id for bot

'''Example:''' <syntaxhighlight lang="java">
mywpn = b.GetCurrentWeapon();
if(mywpn == WEAPON.SHOTGUN)
{
}</syntaxhighlight>

----
====GetCurrentAmmo====
Gets the ammo information for a weapon.

'''Parameters:''' (table)

'''Parameters:''' (table, firemode)

'''Parameters:''' (table, firemode, weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
ammoTable = {};
// Get primary ammo for current weapon
b.GetCurrentAmmo(ammoTable);
// Get secondary ammo for current weapon
b.GetCurrentAmmo(ammoTable, 1);
// Get primary ammo for another weapon.
b.GetCurrentAmmo(ammoTable, 0, WEAPON.SHOTGUN);

print("Current Ammo:", ammoTable.CurrentAmmo);
print("Max Ammo:", ammoTable.MaxAmmo);
print("Current Clips:", ammoTable.CurrentClip);
print("Max Clips:", ammoTable.MaxClip);</syntaxhighlight>

----

====GetMostDesiredAmmo====
Gets information about the currently most needed ammo.

'''Parameters:''' (table)

'''Returns:''' none

* AmmoType - weapon ID
* Desire - [[Weapon#LowAmmoPriority|LowAmmoPriority]]; It will be zero if bot has more ammo than [[Weapon#LowAmmoThreshold|LowAmmoThreshold]]
* GetAmmo - [[Weapon#LowAmmoGetAmmoAmount|LowAmmoGetAmmoAmount]]

'''Example:''' <syntaxhighlight lang="java">
mostNeededAmmo = {};
b.GetMostDesiredAmmo(mostNeededAmmo);
if( mostNeededAmmo.Desire > 0) {
print("Need ammo for weapon", Util.WeaponName(mostNeededAmmo.AmmoType));
}</syntaxhighlight>
----

====FireWeapon====
Fires the current weapon.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.FireWeapon();</syntaxhighlight>

----
====HasAmmo====
Checks if the bot has a certain ammo type.

'''Parameters:''' () - If no parameters passed, checks current weapon ammo.

'''Parameters:''' (WeaponId)

'''Parameters:''' (WeaponId, needed amount)

'''Returns:''' true/false if the bot has ammo.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasAmmo())
{
}
if(b.HasAmmo(WEAPON.MP40))
{
}</syntaxhighlight>

----

====HasAnyWeapon====
Checks if the bot has any of specified weapons. Table keys are weaponIDs, table values should be set to true.

'''Parameters:''' (weapons, options<optional>, weaponList<optional>)

The second parameter is table which has items CheckAmmo and CheckCharged. Both options are true by default.

The third parameter is empty table to store all results.

'''Returns:''' weaponId if the bot has that weapon, 0 if the bot does not have any weapon from the list.

'''Example:''' <syntaxhighlight lang="java">
weapons = table();
weapons[WEAPON.MP40] = true;
weapons[WEAPON.THOMPSON] = true;
weapon = b.HasAnyWeapon(weapons, { CheckAmmo=true, CheckCharged=false } );
if (weapon) {
}</syntaxhighlight>

----

====HasWeapon====
Checks if the bot has a specific weapon.

'''Parameters:''' (weaponId)

'''Returns:''' true if the bot has it, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasWeapon(WEAPON.SHOTGUN))
{
}</syntaxhighlight>

----
====IsWeaponCharged====
Checks if a weapon is ''charged''. A charged weapon is one that is capable of being used that might occasionally be unavailable for use due to lack of character 'charge', whether that be a gameplay charge bar, stamina, skill, etc.

'''Parameters:''' (weaponId, firemode<optional>)

'''Returns:''' true if weapon is charged, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsWeaponCharged(WEAPON.MORTAR, 0))
{
}</syntaxhighlight>
----

===GetAllAlly===
Fills a table with all known allied entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllAlly(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllEnemy===
Fills a table with all known enemy entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllEnemy(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllType===
Fills a table with all known entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllType(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----

===GetClass===
Gets the current class id for the bot.

'''Parameters:''' none

'''Returns:''' class Id for bot

'''Example:''' <syntaxhighlight lang="java">
myclass = b.GetClass();
if(myClass == CLASS.SOLDIER)
{
}</syntaxhighlight>

----

===GetEyePosition===
Gets the world position of the bots 'eye'

'''Parameters:''' none

'''Returns:''' Vector3 eye position

'''Example:''' <syntaxhighlight lang="java">
eyepos = b.GetEyePosition();</syntaxhighlight>

----

===GetFacing===
Gets the facing vector for the bots aim. This method is fast, but can return incorrect value if the aim request is restricted by the game or mod (for example after revive). You can use function GetEntFacing to get correct facing.

'''Parameters:''' none

'''Returns:''' Vector3 facing vector

'''Example:''' <syntaxhighlight lang="java">
facing = b.GetFacing();
pointinfront = b.GetEyePosition() + facing * 100;</syntaxhighlight>

----

===GetGameEntity===
Gets the game entity for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
ent = b.GetGameEntity();</syntaxhighlight>

----

===GetGameId===
Gets the game id for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
gameid = b.GetGameId();</syntaxhighlight>

----

===GetHealthPercent===
Gets the bot's current health percentage.

'''Parameters:''' none

'''Returns:''' 0.0 - 1.0 health scalar

'''Example:''' <syntaxhighlight lang="java">
if(bot.GetHealthPercent() < 0.5)
{
// < 50% health
}</syntaxhighlight>
----
===GetHighLevelGoalName===
Gets the bot's current high level goal name.

Examples: UseCabinet, WatchForProjectile, CovertOps, BUILD, PLANT, CAMP, SWITCH, ROAMING, ...

Some goal names changed after they were moved to scripts.

Goals in 0.81: DefuseDynamite, ReviveTeammate, TakeCheckPoint, RepairMg42

Goals in 0.82: DEFUSE, REVIVE, CHECKPOINT, REPAIRMG42

Goals in 0.83: CaptureTheFlag, ReturnTheFlag, MobileMortar, PlantMine, CallArtillery

Goals in 0.84: FLAG, FLAGRETURN, MOBILEMORTAR, PLANTMINE, CALLARTILLERY

'''Parameters:''' none

'''Returns:''' goal name, or NULL if the bot doesn't have a high level goal.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetHighLevelGoalName();</syntaxhighlight>
----

===GetMapGoalName===
Gets the bot's current map goal name (for example: BUILD_Tank, DEFEND_depot1, ...).

Returns NULL if the current high level goal is ROAMING, WatchForProjectile or CovertOps.

Note: This function has been added in 0.82.

'''Parameters:''' none

'''Returns:''' goal name or NULL.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetMapGoalName();</syntaxhighlight>
----

===GetLastTarget===
Gets the target the bot had before the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
last = b.GetLastTarget();</syntaxhighlight>

----

===GetNearest===
Gets the nearest target matching the desired criteria, friend or foe.

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearest(CAT.PLAYER);
// get nearest soldier or medic player
s = b.GetNearest(CAT.PLAYER, {CLASS.SOLDIER, CLASS.MEDIC});</syntaxhighlight>

----

===GetNearestAlly===
Gets the nearest target matching the desired criteria, only allies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestAlly(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestAlly(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

===GetNearestEnemy===
Gets the nearest target matching the desired criteria, only enemies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestEnemy(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestEnemy(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

=== GetNearestDestination ===
Finds paths from the current bot position to multiple destination positions. Returns index of the destination which has the shortest path. It can depend on navigation flags (e.g. teleports, axis/allied waypoints).

'''Parameters:''' (table of vectors)

'''Returns:''' index OR null

'''Example:''' <syntaxhighlight lang="java">
positions = { Vec3(105,4564,0), Vec3(-48,1234,0) };
id = bot.GetNearestDestination(positions);
if(typeId(id)==0)
{
print("path not found");
}else{
print("path found to destination", positions[id]);
}
</syntaxhighlight>
----

===GetPosition===
Gets the world position of the bot.

'''Parameters:''' none

'''Returns:''' Vector3 world position

'''Example:''' <syntaxhighlight lang="java">
mypos = b.GetPosition();</syntaxhighlight>

----

===GetTarget===
Gets the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
target = b.GetTarget();</syntaxhighlight>

----

===GetTargetInfo===
Returns the [[TargetInfo]] for an entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' [[TargetInfo]] for entity.

'''Example:''' <syntaxhighlight lang="java">
ti = b.GetTargetInfo(b.GetTarget());</syntaxhighlight>

----

===GetTeam===
Gets the current team the bot is on.

'''Parameters:''' none

'''Returns:''' team #

'''Example:''' <syntaxhighlight lang="java">
myteam = b.GetTeam();</syntaxhighlight>

'''See also:''' [[TEAM]]

----

===GetVelocity===
Gets the world velocity of the bot. The bot must be alive. It returns wrong vector if the bot is injured.

'''Parameters:''' none

'''Returns:''' Vector3 world velocity

'''Example:''' <syntaxhighlight lang="java">
myvel = b.GetVelocity();</syntaxhighlight>

----

===HasTarget===
Checks if the bot has a current target (enemy)

'''Parameters:''' none

'''Returns:''' true if bot has a target

'''Example:''' <syntaxhighlight lang="java">
if(b.HasTarget())
{
}</syntaxhighlight>

----

===HasAnyEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has at least one of the flags, or false if it doesn't have any of them.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has any flag, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasAnyEntityFlag(ENTFLAG.ZOOMING))
{
}
// checking multiple flags.
if(b.HasAnyEntityFlag(ENTFLAG.MOUNTED, ENTFLAG.ON_LADDER))
{
}</syntaxhighlight>

----

===HasEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has all flags, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasEntityFlag(ENTFLAG.RELOADING))
{
}
// checking multiple flags.
if(b.HasEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER))
{
}</syntaxhighlight>

----

===HasLineOfSightTo===
This functions checks whether the bot has line of sight to a 3d position. This function does not account for field of view, simply does a raycast for obstructions between the bots eye position and the provided position. To account for field of view, use [[Bot#InFieldOfView|InFieldOfView]]. If an entity or gameId is provided as the 2nd parameter, the function will return true if the raycast hits nothing on its way to the position OR if it hits the entity that is passed.

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, entity)

'''Returns:''' true if the bot has line of sight to the position or entity passed. false if the bot's view is obstructed.

'''Note:''' This function calls [[Bot_Library#TraceLine|TraceLine]] with parameter TRACE.SHOT | TRACE.SMOKEBOMB

'''Example:''' <syntaxhighlight lang="java">
if(b.HasLineOfSightTo( Vec3(30,50,10) ))
{
}</syntaxhighlight>

----

===HasPowerUp===
Checks if the bot has a given powerup. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (powerup, ...)

'''Returns:''' true if bot has all powerups, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasPowerUp(POWERUP.INVINCIBLE))
{
}
// checking multiple flags.
if(b.HasPowerUp(POWERUP.INVINCIBLE, POWERUP.QUADDAMAGE))
{
}</syntaxhighlight>

----

===HasRole===
Checks if the bot has a specific role or any role.

'''Parameters:''' roleId <optional>

'''Returns:''' true if the bot has role, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasRole(ROLE.INFILTRATOR)){
}
</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#SetRoles| SetRoles]]

----

===HoldButton===
Makes the bot 'press' a button, and hold it for an amount of time. This function can take any number of buttons as parameters, and will apply the effect to all of them. The time value is '''ALWAYS''' the last parameter.

'''Parameters:''' (buttonId, ..., time in seconds)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// hold crouch for 5 seconds
b.HoldButton(BTN.CROUCH, 5);
// hold multiple buttons for 5 seconds
b.HoldButton(BTN.CROUCH, BTN.SPRINT, 5);</syntaxhighlight>

'''See Also:''' [[Bot#PressButton| PressButton]], [[Bot#ReleaseButton| ReleaseButton]]

----

===IgnoreTarget===
This function causes the bot to ignore specific entities for targeting for some duration of time.

'''Parameters:''' (entity/gameId or goal name or table, seconds to ignore <optional>)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// ignore the entity, so the bot won't shoot at it.
bot.IgnoreTarget("MOVER_bird1");
bot.IgnoreTarget(Map.Movers);
bot.IgnoreTarget(GetLocalEntity(), 100);</syntaxhighlight>

'''See also:''' [[Bots shooting map objects]]

----

===InFieldOfView===
Checks whether a position is within the bots current [[Bot#FieldOfView | FieldOfView]]. This function can take an optional field of view(in degrees) to check. If not provided, it will use the bots current [[Bot#FieldOfView | FieldOfView]].

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, fov angles)

'''Returns:''' Vector3 - center point of the AABB.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,10,10);
// check if in default field of view
if(b.InFieldOfView(v))
{
}
// check if in custom field of view
if(b.InFieldOfView(v, 180))
{
}</syntaxhighlight>
----

===IsAllied===
Checks if the bot is allied with a given entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' true if allied, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsAllied(someentity))
{
}</syntaxhighlight>
----

===IsCarryingFlag===
Checks if the bot is carrying objective (flag, gold, documents, radar parts, ...).

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(b.IsCarryingFlag())
{
}
</syntaxhighlight>
----
===IsStuck===
Checks if the bot considers himself to be stuck. Stuckness is typically defined as an insignificant amount of movement over a short period of time. The time can be optionally passed to the function for flexibility.

'''Parameters:''' () - If no params passed, the time used is 0.5 seconds.

'''Parameters:''' (time in seconds)

'''Returns:''' true if bot is ''stuck'', false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsStuck())
{
}
// or check stuckness for 1.5 seconds.
if(b.IsStuck(1.5))
{
}</syntaxhighlight>
----

===MoveTowards===
Can be used in paththrough navigation or script goals. Cannot be called from map triggers.
Causes the bot to blindly move towards a target. This function does no path finding. It's primary use is short range movement when you are reasonably sure the bot can run right at the target.

'''Parameters:''' (Vector3 position) - if distance tolerance not specified, default of 32 units is used.

'''Parameters:''' (Vector3 position, distance tolerance)

'''Returns:''' true if the bot is within the distance tolerance, false if not.

'''Example:''' <syntaxhighlight lang="java">
// get within 64 units of this position
v = Vector3(10,10,10);
while(b.MoveTowards(v, 64) == false)
{
yield();
} </syntaxhighlight>
----

===PressButton===
Makes the bot 'press' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them. Buttons that are ''pressed'' using this function are released automatically for the next bot update.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// press crouch
b.PressButton(BTN.CROUCH);
// press multiple buttons
b.PressButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#ReleaseButton| ReleaseButton]]
----

===ReleaseButton===
Makes the bot 'release' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// release crouch
b.ReleaseButton(BTN.CROUCH);
// release multiple buttons
b.ReleaseButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#PressButton| PressButton]]
----

===ReloadProfile===
Reloads the bots profile. The profile is any script associated with the bots name.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ReloadProfile();</syntaxhighlight>
----

===ResetStuckTime===
Reset the stuck timer.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ResetStuckTime();</syntaxhighlight>

----

===Say===
Chat function used for bots to ''say'' messages through the normal chat channels of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Say("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#SayTeam| SayTeam]], [[Bot#SayVoice| SayVoice]]
----

===SayTeam===
Chat function used for bots to ''say'' messages through the team chat channel of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayTeam("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayVoice| SayVoice]]
----

===SayVoice===
Broadcasts a voice macro to the game. Used with global [[VOICE]] table values.

'''Parameters:''' (macroId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayVoice(VOICE.NEED_MEDIC);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayTeam| SayTeam]]
----

===ScriptEvent===
Sends [[EVENT#SCRIPTMSG|SCRIPTMSG]] event.

'''Parameters:''' (name, param1, param2, param3)

'''Returns:''' none
----

===SetDebugFlag===
Enables a debug flag for the bot. See the global [[DEBUG]] table for available options. Enabling debug flags typically cause various debug visualizations to render in order to help identify whats going on with various systems of the bot.

'''Parameters:''' (flag, true/false to enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetDebugFlag(DEBUG.AIM, true);</syntaxhighlight>
----

===SetRoles===
Assign a role to the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#HasRole| HasRole]]

----

===ToLocalSpace===
Converts a vector into local bot space. This results in a position relative to the bots current position and rotation. This function is useful for simplifying some types of logic.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 local space position.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(4356,342,276); // some world position.
v2 = b.ToLocalSpace(v);
if(v2.y < 0)
{
// the position is behind the bot.
}
if(v2.x < 0)
{
// the position is to the right of the bot
}</syntaxhighlight>

----

===ToWorldSpace===
Converts a vector from local bot space to world space.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 world space position.

'''Example:''' <syntaxhighlight lang="java">
// slightly forward and to the right.
v = Vector3(10,10,0);
v2 = b.ToWorldSpace(v);</syntaxhighlight>

----

===Enemy Territory Addendum===

====ChangePrimaryWeapon====
Selects a new primary weapon for the bot. Should take effect next spawn. You must not use this function inside map scripts. You should use [[Utility_Functions#WeaponTable.SetWeaponAvailability|SetWeaponAvailability]] if you want to disable some weapons.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangePrimaryWeapon(WEAPON.PANZERFAUST);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangeSecondaryWeapon| ChangeSecondaryWeapon]]
----

====ChangeSecondaryWeapon====
Selects a new secondary weapon for the bot. Should take effect next spawn.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSecondaryWeapon(WEAPON.LUGER);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangePrimaryWeapon| ChangePrimaryWeapon]]
----

====ChangeSpawnPoint====
Changes the desired spawn point for the bot to respawn at.

'''Parameters:''' (spawnpoint #)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSpawnPoint(2); </syntaxhighlight>

----

====GetConstructableState====
Check state of a BUILD goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can build the entity, 0 if the entity is already built, -1 if the entity is not constructable or has been built by enemy.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetConstructableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetCursorHint====
When a player is near enough something to get a hint icon, such as for dynamiting, this function can access what hint is showing. Some of these hints may or may not ever show up, they were taken as-is from the ET SDK.

* NONE - 0
* PLAYER - 1
* ACTIVATE - 2
* DOOR - 3
* DOOR_ROTATING - 4
* DOOR_LOCKED - 5
* DOOR_ROTATING_LOCKED - 6
* MG42 - 7
* BREAKABLE - 8
* BREAKABLE_DYNAMITE - 9
* CHAIR - 10
* ALARM - 11
* HEALTH - 12
* TREASURE - 13
* KNIFE - 14
* LADDER - 15
* BUTTON - 16
* WATER - 17
* CAUTION - 18
* DANGER - 19
* SECRET - 20
* QUESTION - 21
* EXCLAMATION - 22
* CLIPBOARD - 23
* WEAPON - 24
* AMMO - 25
* ARMOR - 26
* POWERUP - 27
* HOLDABLE - 28
* INVENTORY - 29
* SCENARIC - 30
* EXIT - 31
* NOEXIT - 32
* PLYR_FRIEND - 33
* PLYR_NEUTRAL - 34
* PLYR_ENEMY - 35
* PLYR_UNKNOWN - 36
* BUILD - 37
* DISARM - 38
* REVIVE - 39
* DYNAMITE - 40
* CONSTRUCTIBLE - 41
* UNIFORM - 42
* LANDMINE - 43
* TANK - 44
* SATCHELCHARGE - 45
* LOCKPICK - 46

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
hint = table();
b.GetCursorHint(hint);

print(hint.type); // one of the values above
print(hint.value); // usually a health associated with certain types </syntaxhighlight>
----

====GetDestroyableState====
Check state of a PLANT goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can destroy the entity, -1 if the entity is not destroyable or is friendly objective.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetDestroyableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetExplosiveState====
Check state of a dynamite, landmine or tripmine.

'''Note:''' It does not work for a poison mine and bouncing betty in Jaymod.

'''Parameters:''' (entity)

'''Returns:''' 1 if the dynamite/mine can be armed, 0 if the dynamite is ticking or the mine is activated.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetExplosiveState(TargetEntity) == 1 ) {
}</syntaxhighlight>

----

====GetMG42Info====
Gets information about currently mounted MG42 - vector CenterFacing and angles MinHorizontal, MaxHorizontal, MinVertical, MaxVertical.

'''Parameters:''' (table)

'''Returns:''' true if info has been stored into table

----

====GetMountedPlayerOnMG42====
Gets player who is mounting MG42.

'''Parameters:''' (mg42Entity)

'''Returns:''' player's entity or null

----

====GetReinforceTime====
Gets the current time left(in seconds) before reinforcements spawn for the bots team.

'''Parameters:''' none

'''Returns:''' seconds left till reinforcements spawn

'''Example:''' <syntaxhighlight lang="java">
if(b.GetReinforceTime() < 2)
{
// 2 seconds to reinforcements
}</syntaxhighlight>

----

====GetSkills====
Gets the current skill values and puts them into the table parameter.

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
skills = table();
b.GetSkills(skills);
print("Battle Sense:", skills[SKILL.BATTLE_SENSE]);
print("Engineering:", skills[SKILL.ENGINEERING]);
print("First Aid:", skills[SKILL.FIRST_AID]);
print("Signals:", skills[SKILL.SIGNALS]);
print("Light Weapons:", skills[SKILL.LIGHT_WEAPONS]);
print("Heavy Weapons:", skills[SKILL.HEAVY_WEAPONS]);
print("Coverops:", skills[SKILL.COVERTOPS]); </syntaxhighlight>

'''See Also:''' [[SKILL]]
----
====GetStat====
Gets a current stat from the bot by name. Valid stat names for ET are kills, deaths and xp.

'''Parameters:''' (string) the stat name

'''Returns:''' the value of the stat

'''Example:''' <syntaxhighlight lang="java">
xp = b.GetStat("xp");
print("Bot xp value is",xp);</syntaxhighlight>

----

====IsMG42Repairable====

'''Parameters:''' (mg42Entity)

'''Returns:''' true if mg42 is damaged and can be repaired

----
====TeamLandminesAvailable====

'''Parameters:''' none

'''Returns:''' remaining count of team landmines

----

Bot

2025-05-13T08:44:36Z

Palota: /* MoveTowards */

{{process header
| title = Bot Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Bot Properties==

----

Unless otherwise noted, all properties can be get and set.

=== AimDamping ===
Effects the acceleration and turn rate.
=== AimPersistance ===
The time(in seconds) the bot will continue to aim at the last position of a target before aborting.
=== AimStiffness ===
Effects the acceleration of turning.
=== AimTolerance ===
The tolerance(in degrees) the bot tries to aim at stuff with.
=== Armor ===
Current Armor
=== FieldOfView ===
The angle(in degrees) the bot is capable of 'seeing'.
=== Health ===
Current health.
=== MaxArmor ===
Max Armor
=== MaxHealth ===
Max Health
=== MaxTurnSpeed ===
The maximum speed(in degrees/second) the bot can rotate his aim at.
=== MaxViewDistance ===
The max distance(in game units) the bot is capable of seeing.
=== MemorySpan ===
The time(in seconds) taken for the memory about an entity to become stale.
=== Name ===
Name of the bot.

=== ReactionTime ===
The time(in seconds) it takes the bot to begin responding to a newly sensed threat.

----

=== Enemy Territory Addendum ===

----

==== DoNotKill ====
Set it to true to prevent medics to kill the bot for revive. It is used by BUILD, PLANT and PLANTMINE goals.
==== TargetBreakableDist ====
The maximum distance (in game units) the bot will attempt to target breakable entities. It can be set by [[Pre-Scripted_Regions#BreakableDistance|pre-scripted trigger region]] or inside [[Creating_a_script|OnBotJoin]] function.

----

==Bot Functions==
----
===AddScriptGoal===
Adds a goal to the bots behavior tree by name. Useful when a script goal has AutoAdd set to false, so you can more explicitly control when a bot gets the goal.

'''Parameters:''' (name of script goal to add to bot behavior tree)

'''Returns:''' true on success, false on failure

'''Example:''' <syntaxhighlight lang="java">
b.AddScriptGoal("TestBot");</syntaxhighlight>
----
===RemoveState===
Removes a state from a bots behavior tree by name.

'''Parameters:''' (name of script goal to remove from bot behavior tree)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.RemoveState("TestBot");</syntaxhighlight>
----
===SetStateEnabled===
Enables/Disables a state by name.

'''Parameters:''' (name of state, bool enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetStateEnabled("Attack", false); // disable attack state</syntaxhighlight>
----

===CanGrabItem===
Returns true if bot can take item (flag, gold, radar parts, ...).

'''Parameters:''' (GameEntity)

'''Parameters:''' (FLAG or FLAG_dropped goal name)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if (b.CanGrabItem("FLAG_gold")) {
}</syntaxhighlight>

----

===ChangeClass===
Changes the bot to a specified class.

'''Parameters:''' (classId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeClass(CLASS.SOLDIER);</syntaxhighlight>

----

===ChangeTeam===
Changes the bot to a specified team.

'''Parameters:''' (teamId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeTeam(TEAM.AXIS);</syntaxhighlight>

----

===ClearRoles===
Takes away a role from the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ClearRoles(ROLE.ATTACKER);</syntaxhighlight>

'''See Also:'''
[[Bot#SetRoles| SetRoles]], [[Bot#HasRole| HasRole]]

----

===DisableBotPush===
Used by [[Pre-Scripted_Regions#DisableBotPush|pre-scripted trigger region]].

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DisableBotPush(true);</syntaxhighlight>

----

===DistanceTo===
Overloaded utility function for simplified distance checks.

'''Parameters:''' (Vector3, notUseEyePosition<default false>)

'''Parameters:''' (MapGoal, notUseEyePosition<default false>)

'''Parameters:''' (GameEntity/GameId, notUseEyePosition<default false>)

'''Returns:''' float - distance from bot to Vector3, MapGoal, GameEntity or GameId

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,20,30);
target = b.GetTarget();
// distance from bot to target entity
d1 = b.DistanceTo(target, true);
// distance from bot to world position
d2 = b.DistanceTo(v, true);
// distance from bot eye to world position
d3 = b.DistanceTo(v);</syntaxhighlight>
----

===DumpBotTable===
Dumps a file with the bot's table to a file in the user folder.

'''Parameters:''' (filename)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DumpBotTable("foo.txt");</syntaxhighlight>

----

===Enable===
Disables all thinking for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Enable(false);</syntaxhighlight>

----

===ExecCommand===
Executes a string command on the bot as if the bot executed a console command.

'''Parameters:''' (command)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ExecCommand("kill");</syntaxhighlight>

----

===Weapons/Ammo===
====CanSnipe====
It's deprecated and has been replaced by Util.CanBotSnipe(bot) in Enemy Territory.

Checks if the bot can snipe based on the internally implemented snipe checks. Vary by game. Typically involves checking if the bot has a snipe enabled weapon and has ammo.

'''Parameters:''' none

'''Returns:''' true if the bot can snipe, else false

'''Example:''' <syntaxhighlight lang="java">
if(b.CanSnipe()) {}</syntaxhighlight>

----

====EnableShooting====
Disables all shooting for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.EnableShooting(false);</syntaxhighlight>

----
====GetWeapon====
Gets a reference to a specific weapon from the bot.

'''Parameters:''' (weaponId)

'''Returns:''' [[Weapon]] reference, or NULL if the bot doesn't have the weapon.

'''Example:''' <syntaxhighlight lang="java">
wpn = b.GetWeapon(WEAPON.SHOTGUN);
wpn.PrimaryFire.AimOffset = Vector3(0,0,10);</syntaxhighlight>

----
====GetBestWeapon====
Gets a weapon id for the best weapon versus current target or a specific entity.

'''Parameters:''' none - uses current target

'''Parameters:''' (entity) evaluate weapon versus specific target entity

'''Returns:''' weapon id of weapon that is chosen.

'''Example:''' <syntaxhighlight lang="java">
best = b.GetBestWeapon();
// OR
best = b.GetBestWeapon(someEnt);</syntaxhighlight>

----
====GetRandomWeapon====
Gets a random weapon id from the list of weapons the bot currently has.

'''Parameters:''' none

'''Returns:''' random weapon id

'''Example:''' <syntaxhighlight lang="java">
randwpn = b.GetRandomWeapon();</syntaxhighlight>

----

====GetCurrentWeapon====
Gets the current weapon id for the bot.

'''Parameters:''' none

'''Returns:''' weapon Id for bot

'''Example:''' <syntaxhighlight lang="java">
mywpn = b.GetCurrentWeapon();
if(mywpn == WEAPON.SHOTGUN)
{
}</syntaxhighlight>

----
====GetCurrentAmmo====
Gets the ammo information for a weapon.

'''Parameters:''' (table)

'''Parameters:''' (table, firemode)

'''Parameters:''' (table, firemode, weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
ammoTable = {};
// Get primary ammo for current weapon
b.GetCurrentAmmo(ammoTable);
// Get secondary ammo for current weapon
b.GetCurrentAmmo(ammoTable, 1);
// Get primary ammo for another weapon.
b.GetCurrentAmmo(ammoTable, 0, WEAPON.SHOTGUN);

print("Current Ammo:", ammoTable.CurrentAmmo);
print("Max Ammo:", ammoTable.MaxAmmo);
print("Current Clips:", ammoTable.CurrentClip);
print("Max Clips:", ammoTable.MaxClip);</syntaxhighlight>

----

====GetMostDesiredAmmo====
Gets information about the currently most needed ammo.

'''Parameters:''' (table)

'''Returns:''' none

* AmmoType - weapon ID
* Desire - [[Weapon#LowAmmoPriority|LowAmmoPriority]]; It will be zero if bot has more ammo than [[Weapon#LowAmmoThreshold|LowAmmoThreshold]]
* GetAmmo - [[Weapon#LowAmmoGetAmmoAmount|LowAmmoGetAmmoAmount]]

'''Example:''' <syntaxhighlight lang="java">
mostNeededAmmo = {};
b.GetMostDesiredAmmo(mostNeededAmmo);
if( mostNeededAmmo.Desire > 0) {
print("Need ammo for weapon", Util.WeaponName(mostNeededAmmo.AmmoType));
}</syntaxhighlight>
----

====FireWeapon====
Fires the current weapon.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.FireWeapon();</syntaxhighlight>

----
====HasAmmo====
Checks if the bot has a certain ammo type.

'''Parameters:''' () - If no parameters passed, checks current weapon ammo.

'''Parameters:''' (WeaponId)

'''Parameters:''' (WeaponId, needed amount)

'''Returns:''' true/false if the bot has ammo.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasAmmo())
{
}
if(b.HasAmmo(WEAPON.MP40))
{
}</syntaxhighlight>

----

====HasAnyWeapon====
Checks if the bot has any of specified weapons. Table keys are weaponIDs, table values should be set to true.

'''Parameters:''' (weapons, options<optional>, weaponList<optional>)

The second parameter is table which has items CheckAmmo and CheckCharged. Both options are true by default.

The third parameter is empty table to store all results.

'''Returns:''' weaponId if the bot has that weapon, 0 if the bot does not have any weapon from the list.

'''Example:''' <syntaxhighlight lang="java">
weapons = table();
weapons[WEAPON.MP40] = true;
weapons[WEAPON.THOMPSON] = true;
weapon = b.HasAnyWeapon(weapons, { CheckAmmo=true, CheckCharged=false } );
if (weapon) {
}</syntaxhighlight>

----

====HasWeapon====
Checks if the bot has a specific weapon.

'''Parameters:''' (weaponId)

'''Returns:''' true if the bot has it, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasWeapon(WEAPON.SHOTGUN))
{
}</syntaxhighlight>

----
====IsWeaponCharged====
Checks if a weapon is ''charged''. A charged weapon is one that is capable of being used that might occasionally be unavailable for use due to lack of character 'charge', whether that be a gameplay charge bar, stamina, skill, etc.

'''Parameters:''' (weaponId, firemode<optional>)

'''Returns:''' true if weapon is charged, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsWeaponCharged(WEAPON.MORTAR, 0))
{
}</syntaxhighlight>
----

===GetAllAlly===
Fills a table with all known allied entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllAlly(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllEnemy===
Fills a table with all known enemy entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllEnemy(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllType===
Fills a table with all known entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllType(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----

===GetClass===
Gets the current class id for the bot.

'''Parameters:''' none

'''Returns:''' class Id for bot

'''Example:''' <syntaxhighlight lang="java">
myclass = b.GetClass();
if(myClass == CLASS.SOLDIER)
{
}</syntaxhighlight>

----

===GetEyePosition===
Gets the world position of the bots 'eye'

'''Parameters:''' none

'''Returns:''' Vector3 eye position

'''Example:''' <syntaxhighlight lang="java">
eyepos = b.GetEyePosition();</syntaxhighlight>

----

===GetFacing===
Gets the facing vector for the bots aim. This method is fast, but can return incorrect value if the aim request is restricted by the game or mod (for example after revive). You can use function GetEntFacing to get correct facing.

'''Parameters:''' none

'''Returns:''' Vector3 facing vector

'''Example:''' <syntaxhighlight lang="java">
facing = b.GetFacing();
pointinfront = b.GetEyePosition() + facing * 100;</syntaxhighlight>

----

===GetGameEntity===
Gets the game entity for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
ent = b.GetGameEntity();</syntaxhighlight>

----

===GetGameId===
Gets the game id for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
gameid = b.GetGameId();</syntaxhighlight>

----

===GetHealthPercent===
Gets the bot's current health percentage.

'''Parameters:''' none

'''Returns:''' 0.0 - 1.0 health scalar

'''Example:''' <syntaxhighlight lang="java">
if(bot.GetHealthPercent() < 0.5)
{
// < 50% health
}</syntaxhighlight>
----
===GetHighLevelGoalName===
Gets the bot's current high level goal name.

Examples: UseCabinet, WatchForProjectile, CovertOps, BUILD, PLANT, CAMP, SWITCH, ROAMING, ...

Some goal names changed after they were moved to scripts.

Goals in 0.81: DefuseDynamite, ReviveTeammate, TakeCheckPoint, RepairMg42

Goals in 0.82: DEFUSE, REVIVE, CHECKPOINT, REPAIRMG42

Goals in 0.83: CaptureTheFlag, ReturnTheFlag, MobileMortar, PlantMine, CallArtillery

Goals in 0.84: FLAG, FLAGRETURN, MOBILEMORTAR, PLANTMINE, CALLARTILLERY

'''Parameters:''' none

'''Returns:''' goal name, or NULL if the bot doesn't have a high level goal.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetHighLevelGoalName();</syntaxhighlight>
----

===GetMapGoalName===
Gets the bot's current map goal name (for example: BUILD_Tank, DEFEND_depot1, ...).

Returns NULL if the current high level goal is ROAMING, WatchForProjectile or CovertOps.

Note: This function has been added in 0.82.

'''Parameters:''' none

'''Returns:''' goal name or NULL.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetMapGoalName();</syntaxhighlight>
----

===GetLastTarget===
Gets the target the bot had before the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
last = b.GetLastTarget();</syntaxhighlight>

----

===GetNearest===
Gets the nearest target matching the desired criteria, friend or foe.

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearest(CAT.PLAYER);
// get nearest soldier or medic player
s = b.GetNearest(CAT.PLAYER, {CLASS.SOLDIER, CLASS.MEDIC});</syntaxhighlight>

----

===GetNearestAlly===
Gets the nearest target matching the desired criteria, only allies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestAlly(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestAlly(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

===GetNearestEnemy===
Gets the nearest target matching the desired criteria, only enemies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestEnemy(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestEnemy(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

=== GetNearestDestination ===
Finds paths from the current bot position to multiple destination positions. Returns index of the destination which has the shortest path. It can depend on navigation flags (e.g. teleports, axis/allied waypoints).

'''Parameters:''' (table of vectors)

'''Returns:''' index OR null

'''Example:''' <syntaxhighlight lang="java">
positions = { Vec3(105,4564,0), Vec3(-48,1234,0) };
id = bot.GetNearestDestination(positions);
if(typeId(id)==0)
{
print("path not found");
}else{
print("path found to destination", positions[id]);
}
</syntaxhighlight>
----

===GetPosition===
Gets the world position of the bot.

'''Parameters:''' none

'''Returns:''' Vector3 world position

'''Example:''' <syntaxhighlight lang="java">
mypos = b.GetPosition();</syntaxhighlight>

----

===GetTarget===
Gets the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
target = b.GetTarget();</syntaxhighlight>

----

===GetTargetInfo===
Returns the [[TargetInfo]] for an entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' [[TargetInfo]] for entity.

'''Example:''' <syntaxhighlight lang="java">
ti = b.GetTargetInfo(b.GetTarget());</syntaxhighlight>

----

===GetTeam===
Gets the current team the bot is on.

'''Parameters:''' none

'''Returns:''' team #

'''Example:''' <syntaxhighlight lang="java">
myteam = b.GetTeam();</syntaxhighlight>

'''See also:''' [[TEAM]]

----

===GetVelocity===
Gets the world velocity of the bot. The bot must be alive. It returns wrong vector if the bot is injured.

'''Parameters:''' none

'''Returns:''' Vector3 world velocity

'''Example:''' <syntaxhighlight lang="java">
myvel = b.GetVelocity();</syntaxhighlight>

----

===HasTarget===
Checks if the bot has a current target

'''Parameters:''' none

'''Returns:''' true if bot has a target

'''Example:''' <syntaxhighlight lang="java">
if(b.HasTarget())
{
}</syntaxhighlight>

----

===HasAnyEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has at least one of the flags, or false if it doesn't have any of them.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has any flag, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasAnyEntityFlag(ENTFLAG.ZOOMING))
{
}
// checking multiple flags.
if(b.HasAnyEntityFlag(ENTFLAG.MOUNTED, ENTFLAG.ON_LADDER))
{
}</syntaxhighlight>

----

===HasEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has all flags, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasEntityFlag(ENTFLAG.RELOADING))
{
}
// checking multiple flags.
if(b.HasEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER))
{
}</syntaxhighlight>

----

===HasLineOfSightTo===
This functions checks whether the bot has line of sight to a 3d position. This function does not account for field of view, simply does a raycast for obstructions between the bots eye position and the provided position. To account for field of view, use [[Bot#InFieldOfView|InFieldOfView]]. If an entity or gameId is provided as the 2nd parameter, the function will return true if the raycast hits nothing on its way to the position OR if it hits the entity that is passed.

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, entity)

'''Returns:''' true if the bot has line of sight to the position or entity passed. false if the bot's view is obstructed.

'''Note:''' This function calls [[Bot_Library#TraceLine|TraceLine]] with parameter TRACE.SHOT | TRACE.SMOKEBOMB

'''Example:''' <syntaxhighlight lang="java">
if(b.HasLineOfSightTo( Vec3(30,50,10) ))
{
}</syntaxhighlight>

----

===HasPowerUp===
Checks if the bot has a given powerup. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (powerup, ...)

'''Returns:''' true if bot has all powerups, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasPowerUp(POWERUP.INVINCIBLE))
{
}
// checking multiple flags.
if(b.HasPowerUp(POWERUP.INVINCIBLE, POWERUP.QUADDAMAGE))
{
}</syntaxhighlight>

----

===HasRole===
Checks if the bot has a specific role or any role.

'''Parameters:''' roleId <optional>

'''Returns:''' true if the bot has role, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasRole(ROLE.INFILTRATOR)){
}
</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#SetRoles| SetRoles]]

----

===HoldButton===
Makes the bot 'press' a button, and hold it for an amount of time. This function can take any number of buttons as parameters, and will apply the effect to all of them. The time value is '''ALWAYS''' the last parameter.

'''Parameters:''' (buttonId, ..., time in seconds)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// hold crouch for 5 seconds
b.HoldButton(BTN.CROUCH, 5);
// hold multiple buttons for 5 seconds
b.HoldButton(BTN.CROUCH, BTN.SPRINT, 5);</syntaxhighlight>

'''See Also:''' [[Bot#PressButton| PressButton]], [[Bot#ReleaseButton| ReleaseButton]]

----

===IgnoreTarget===
This function causes the bot to ignore specific entities for targeting for some duration of time.

'''Parameters:''' (entity/gameId or goal name or table, seconds to ignore <optional>)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// ignore the entity, so the bot won't shoot at it.
bot.IgnoreTarget("MOVER_bird1");
bot.IgnoreTarget(Map.Movers);
bot.IgnoreTarget(GetLocalEntity(), 100);</syntaxhighlight>

'''See also:''' [[Bots shooting map objects]]

----

===InFieldOfView===
Checks whether a position is within the bots current [[Bot#FieldOfView | FieldOfView]]. This function can take an optional field of view(in degrees) to check. If not provided, it will use the bots current [[Bot#FieldOfView | FieldOfView]].

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, fov angles)

'''Returns:''' Vector3 - center point of the AABB.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,10,10);
// check if in default field of view
if(b.InFieldOfView(v))
{
}
// check if in custom field of view
if(b.InFieldOfView(v, 180))
{
}</syntaxhighlight>
----

===IsAllied===
Checks if the bot is allied with a given entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' true if allied, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsAllied(someentity))
{
}</syntaxhighlight>
----

===IsCarryingFlag===
Checks if the bot is carrying objective (flag, gold, documents, radar parts, ...).

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(b.IsCarryingFlag())
{
}
</syntaxhighlight>
----
===IsStuck===
Checks if the bot considers himself to be stuck. Stuckness is typically defined as an insignificant amount of movement over a short period of time. The time can be optionally passed to the function for flexibility.

'''Parameters:''' () - If no params passed, the time used is 0.5 seconds.

'''Parameters:''' (time in seconds)

'''Returns:''' true if bot is ''stuck'', false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsStuck())
{
}
// or check stuckness for 1.5 seconds.
if(b.IsStuck(1.5))
{
}</syntaxhighlight>
----

===MoveTowards===
Can be used in paththrough navigation or script goals. Cannot be called from map triggers.
Causes the bot to blindly move towards a target. This function does no path finding. It's primary use is short range movement when you are reasonably sure the bot can run right at the target.

'''Parameters:''' (Vector3 position) - if distance tolerance not specified, default of 32 units is used.

'''Parameters:''' (Vector3 position, distance tolerance)

'''Returns:''' true if the bot is within the distance tolerance, false if not.

'''Example:''' <syntaxhighlight lang="java">
// get within 64 units of this position
v = Vector3(10,10,10);
while(b.MoveTowards(v, 64) == false)
{
yield();
} </syntaxhighlight>
----

===PressButton===
Makes the bot 'press' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them. Buttons that are ''pressed'' using this function are released automatically for the next bot update.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// press crouch
b.PressButton(BTN.CROUCH);
// press multiple buttons
b.PressButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#ReleaseButton| ReleaseButton]]
----

===ReleaseButton===
Makes the bot 'release' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// release crouch
b.ReleaseButton(BTN.CROUCH);
// release multiple buttons
b.ReleaseButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#PressButton| PressButton]]
----

===ReloadProfile===
Reloads the bots profile. The profile is any script associated with the bots name.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ReloadProfile();</syntaxhighlight>
----

===ResetStuckTime===
Reset the stuck timer.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ResetStuckTime();</syntaxhighlight>

----

===Say===
Chat function used for bots to ''say'' messages through the normal chat channels of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Say("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#SayTeam| SayTeam]], [[Bot#SayVoice| SayVoice]]
----

===SayTeam===
Chat function used for bots to ''say'' messages through the team chat channel of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayTeam("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayVoice| SayVoice]]
----

===SayVoice===
Broadcasts a voice macro to the game. Used with global [[VOICE]] table values.

'''Parameters:''' (macroId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayVoice(VOICE.NEED_MEDIC);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayTeam| SayTeam]]
----

===ScriptEvent===
Sends [[EVENT#SCRIPTMSG|SCRIPTMSG]] event.

'''Parameters:''' (name, param1, param2, param3)

'''Returns:''' none
----

===SetDebugFlag===
Enables a debug flag for the bot. See the global [[DEBUG]] table for available options. Enabling debug flags typically cause various debug visualizations to render in order to help identify whats going on with various systems of the bot.

'''Parameters:''' (flag, true/false to enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetDebugFlag(DEBUG.AIM, true);</syntaxhighlight>
----

===SetRoles===
Assign a role to the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#HasRole| HasRole]]

----

===ToLocalSpace===
Converts a vector into local bot space. This results in a position relative to the bots current position and rotation. This function is useful for simplifying some types of logic.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 local space position.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(4356,342,276); // some world position.
v2 = b.ToLocalSpace(v);
if(v2.y < 0)
{
// the position is behind the bot.
}
if(v2.x < 0)
{
// the position is to the right of the bot
}</syntaxhighlight>

----

===ToWorldSpace===
Converts a vector from local bot space to world space.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 world space position.

'''Example:''' <syntaxhighlight lang="java">
// slightly forward and to the right.
v = Vector3(10,10,0);
v2 = b.ToWorldSpace(v);</syntaxhighlight>

----

===Enemy Territory Addendum===

====ChangePrimaryWeapon====
Selects a new primary weapon for the bot. Should take effect next spawn. You must not use this function inside map scripts. You should use [[Utility_Functions#WeaponTable.SetWeaponAvailability|SetWeaponAvailability]] if you want to disable some weapons.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangePrimaryWeapon(WEAPON.PANZERFAUST);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangeSecondaryWeapon| ChangeSecondaryWeapon]]
----

====ChangeSecondaryWeapon====
Selects a new secondary weapon for the bot. Should take effect next spawn.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSecondaryWeapon(WEAPON.LUGER);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangePrimaryWeapon| ChangePrimaryWeapon]]
----

====ChangeSpawnPoint====
Changes the desired spawn point for the bot to respawn at.

'''Parameters:''' (spawnpoint #)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSpawnPoint(2); </syntaxhighlight>

----

====GetConstructableState====
Check state of a BUILD goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can build the entity, 0 if the entity is already built, -1 if the entity is not constructable or has been built by enemy.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetConstructableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetCursorHint====
When a player is near enough something to get a hint icon, such as for dynamiting, this function can access what hint is showing. Some of these hints may or may not ever show up, they were taken as-is from the ET SDK.

* NONE - 0
* PLAYER - 1
* ACTIVATE - 2
* DOOR - 3
* DOOR_ROTATING - 4
* DOOR_LOCKED - 5
* DOOR_ROTATING_LOCKED - 6
* MG42 - 7
* BREAKABLE - 8
* BREAKABLE_DYNAMITE - 9
* CHAIR - 10
* ALARM - 11
* HEALTH - 12
* TREASURE - 13
* KNIFE - 14
* LADDER - 15
* BUTTON - 16
* WATER - 17
* CAUTION - 18
* DANGER - 19
* SECRET - 20
* QUESTION - 21
* EXCLAMATION - 22
* CLIPBOARD - 23
* WEAPON - 24
* AMMO - 25
* ARMOR - 26
* POWERUP - 27
* HOLDABLE - 28
* INVENTORY - 29
* SCENARIC - 30
* EXIT - 31
* NOEXIT - 32
* PLYR_FRIEND - 33
* PLYR_NEUTRAL - 34
* PLYR_ENEMY - 35
* PLYR_UNKNOWN - 36
* BUILD - 37
* DISARM - 38
* REVIVE - 39
* DYNAMITE - 40
* CONSTRUCTIBLE - 41
* UNIFORM - 42
* LANDMINE - 43
* TANK - 44
* SATCHELCHARGE - 45
* LOCKPICK - 46

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
hint = table();
b.GetCursorHint(hint);

print(hint.type); // one of the values above
print(hint.value); // usually a health associated with certain types </syntaxhighlight>
----

====GetDestroyableState====
Check state of a PLANT goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can destroy the entity, -1 if the entity is not destroyable or is friendly objective.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetDestroyableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetExplosiveState====
Check state of a dynamite, landmine or tripmine.

'''Note:''' It does not work for a poison mine and bouncing betty in Jaymod.

'''Parameters:''' (entity)

'''Returns:''' 1 if the dynamite/mine can be armed, 0 if the dynamite is ticking or the mine is activated.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetExplosiveState(TargetEntity) == 1 ) {
}</syntaxhighlight>

----

====GetMG42Info====
Gets information about currently mounted MG42 - vector CenterFacing and angles MinHorizontal, MaxHorizontal, MinVertical, MaxVertical.

'''Parameters:''' (table)

'''Returns:''' true if info has been stored into table

----

====GetMountedPlayerOnMG42====
Gets player who is mounting MG42.

'''Parameters:''' (mg42Entity)

'''Returns:''' player's entity or null

----

====GetReinforceTime====
Gets the current time left(in seconds) before reinforcements spawn for the bots team.

'''Parameters:''' none

'''Returns:''' seconds left till reinforcements spawn

'''Example:''' <syntaxhighlight lang="java">
if(b.GetReinforceTime() < 2)
{
// 2 seconds to reinforcements
}</syntaxhighlight>

----

====GetSkills====
Gets the current skill values and puts them into the table parameter.

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
skills = table();
b.GetSkills(skills);
print("Battle Sense:", skills[SKILL.BATTLE_SENSE]);
print("Engineering:", skills[SKILL.ENGINEERING]);
print("First Aid:", skills[SKILL.FIRST_AID]);
print("Signals:", skills[SKILL.SIGNALS]);
print("Light Weapons:", skills[SKILL.LIGHT_WEAPONS]);
print("Heavy Weapons:", skills[SKILL.HEAVY_WEAPONS]);
print("Coverops:", skills[SKILL.COVERTOPS]); </syntaxhighlight>

'''See Also:''' [[SKILL]]
----
====GetStat====
Gets a current stat from the bot by name. Valid stat names for ET are kills, deaths and xp.

'''Parameters:''' (string) the stat name

'''Returns:''' the value of the stat

'''Example:''' <syntaxhighlight lang="java">
xp = b.GetStat("xp");
print("Bot xp value is",xp);</syntaxhighlight>

----

====IsMG42Repairable====

'''Parameters:''' (mg42Entity)

'''Returns:''' true if mg42 is damaged and can be repaired

----
====TeamLandminesAvailable====

'''Parameters:''' none

'''Returns:''' remaining count of team landmines

----

Bot

2025-05-13T08:33:29Z

Palota: /* GetFacing */

{{process header
| title = Bot Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Bot Properties==

----

Unless otherwise noted, all properties can be get and set.

=== AimDamping ===
Effects the acceleration and turn rate.
=== AimPersistance ===
The time(in seconds) the bot will continue to aim at the last position of a target before aborting.
=== AimStiffness ===
Effects the acceleration of turning.
=== AimTolerance ===
The tolerance(in degrees) the bot tries to aim at stuff with.
=== Armor ===
Current Armor
=== FieldOfView ===
The angle(in degrees) the bot is capable of 'seeing'.
=== Health ===
Current health.
=== MaxArmor ===
Max Armor
=== MaxHealth ===
Max Health
=== MaxTurnSpeed ===
The maximum speed(in degrees/second) the bot can rotate his aim at.
=== MaxViewDistance ===
The max distance(in game units) the bot is capable of seeing.
=== MemorySpan ===
The time(in seconds) taken for the memory about an entity to become stale.
=== Name ===
Name of the bot.

=== ReactionTime ===
The time(in seconds) it takes the bot to begin responding to a newly sensed threat.

----

=== Enemy Territory Addendum ===

----

==== DoNotKill ====
Set it to true to prevent medics to kill the bot for revive. It is used by BUILD, PLANT and PLANTMINE goals.
==== TargetBreakableDist ====
The maximum distance (in game units) the bot will attempt to target breakable entities. It can be set by [[Pre-Scripted_Regions#BreakableDistance|pre-scripted trigger region]] or inside [[Creating_a_script|OnBotJoin]] function.

----

==Bot Functions==
----
===AddScriptGoal===
Adds a goal to the bots behavior tree by name. Useful when a script goal has AutoAdd set to false, so you can more explicitly control when a bot gets the goal.

'''Parameters:''' (name of script goal to add to bot behavior tree)

'''Returns:''' true on success, false on failure

'''Example:''' <syntaxhighlight lang="java">
b.AddScriptGoal("TestBot");</syntaxhighlight>
----
===RemoveState===
Removes a state from a bots behavior tree by name.

'''Parameters:''' (name of script goal to remove from bot behavior tree)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.RemoveState("TestBot");</syntaxhighlight>
----
===SetStateEnabled===
Enables/Disables a state by name.

'''Parameters:''' (name of state, bool enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetStateEnabled("Attack", false); // disable attack state</syntaxhighlight>
----

===CanGrabItem===
Returns true if bot can take item (flag, gold, radar parts, ...).

'''Parameters:''' (GameEntity)

'''Parameters:''' (FLAG or FLAG_dropped goal name)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if (b.CanGrabItem("FLAG_gold")) {
}</syntaxhighlight>

----

===ChangeClass===
Changes the bot to a specified class.

'''Parameters:''' (classId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeClass(CLASS.SOLDIER);</syntaxhighlight>

----

===ChangeTeam===
Changes the bot to a specified team.

'''Parameters:''' (teamId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeTeam(TEAM.AXIS);</syntaxhighlight>

----

===ClearRoles===
Takes away a role from the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ClearRoles(ROLE.ATTACKER);</syntaxhighlight>

'''See Also:'''
[[Bot#SetRoles| SetRoles]], [[Bot#HasRole| HasRole]]

----

===DisableBotPush===
Used by [[Pre-Scripted_Regions#DisableBotPush|pre-scripted trigger region]].

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DisableBotPush(true);</syntaxhighlight>

----

===DistanceTo===
Overloaded utility function for simplified distance checks.

'''Parameters:''' (Vector3, notUseEyePosition<default false>)

'''Parameters:''' (MapGoal, notUseEyePosition<default false>)

'''Parameters:''' (GameEntity/GameId, notUseEyePosition<default false>)

'''Returns:''' float - distance from bot to Vector3, MapGoal, GameEntity or GameId

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,20,30);
target = b.GetTarget();
// distance from bot to target entity
d1 = b.DistanceTo(target, true);
// distance from bot to world position
d2 = b.DistanceTo(v, true);
// distance from bot eye to world position
d3 = b.DistanceTo(v);</syntaxhighlight>
----

===DumpBotTable===
Dumps a file with the bot's table to a file in the user folder.

'''Parameters:''' (filename)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DumpBotTable("foo.txt");</syntaxhighlight>

----

===Enable===
Disables all thinking for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Enable(false);</syntaxhighlight>

----

===ExecCommand===
Executes a string command on the bot as if the bot executed a console command.

'''Parameters:''' (command)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ExecCommand("kill");</syntaxhighlight>

----

===Weapons/Ammo===
====CanSnipe====
It's deprecated and has been replaced by Util.CanBotSnipe(bot) in Enemy Territory.

Checks if the bot can snipe based on the internally implemented snipe checks. Vary by game. Typically involves checking if the bot has a snipe enabled weapon and has ammo.

'''Parameters:''' none

'''Returns:''' true if the bot can snipe, else false

'''Example:''' <syntaxhighlight lang="java">
if(b.CanSnipe()) {}</syntaxhighlight>

----

====EnableShooting====
Disables all shooting for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.EnableShooting(false);</syntaxhighlight>

----
====GetWeapon====
Gets a reference to a specific weapon from the bot.

'''Parameters:''' (weaponId)

'''Returns:''' [[Weapon]] reference, or NULL if the bot doesn't have the weapon.

'''Example:''' <syntaxhighlight lang="java">
wpn = b.GetWeapon(WEAPON.SHOTGUN);
wpn.PrimaryFire.AimOffset = Vector3(0,0,10);</syntaxhighlight>

----
====GetBestWeapon====
Gets a weapon id for the best weapon versus current target or a specific entity.

'''Parameters:''' none - uses current target

'''Parameters:''' (entity) evaluate weapon versus specific target entity

'''Returns:''' weapon id of weapon that is chosen.

'''Example:''' <syntaxhighlight lang="java">
best = b.GetBestWeapon();
// OR
best = b.GetBestWeapon(someEnt);</syntaxhighlight>

----
====GetRandomWeapon====
Gets a random weapon id from the list of weapons the bot currently has.

'''Parameters:''' none

'''Returns:''' random weapon id

'''Example:''' <syntaxhighlight lang="java">
randwpn = b.GetRandomWeapon();</syntaxhighlight>

----

====GetCurrentWeapon====
Gets the current weapon id for the bot.

'''Parameters:''' none

'''Returns:''' weapon Id for bot

'''Example:''' <syntaxhighlight lang="java">
mywpn = b.GetCurrentWeapon();
if(mywpn == WEAPON.SHOTGUN)
{
}</syntaxhighlight>

----
====GetCurrentAmmo====
Gets the ammo information for a weapon.

'''Parameters:''' (table)

'''Parameters:''' (table, firemode)

'''Parameters:''' (table, firemode, weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
ammoTable = {};
// Get primary ammo for current weapon
b.GetCurrentAmmo(ammoTable);
// Get secondary ammo for current weapon
b.GetCurrentAmmo(ammoTable, 1);
// Get primary ammo for another weapon.
b.GetCurrentAmmo(ammoTable, 0, WEAPON.SHOTGUN);

print("Current Ammo:", ammoTable.CurrentAmmo);
print("Max Ammo:", ammoTable.MaxAmmo);
print("Current Clips:", ammoTable.CurrentClip);
print("Max Clips:", ammoTable.MaxClip);</syntaxhighlight>

----

====GetMostDesiredAmmo====
Gets information about the currently most needed ammo.

'''Parameters:''' (table)

'''Returns:''' none

* AmmoType - weapon ID
* Desire - [[Weapon#LowAmmoPriority|LowAmmoPriority]]; It will be zero if bot has more ammo than [[Weapon#LowAmmoThreshold|LowAmmoThreshold]]
* GetAmmo - [[Weapon#LowAmmoGetAmmoAmount|LowAmmoGetAmmoAmount]]

'''Example:''' <syntaxhighlight lang="java">
mostNeededAmmo = {};
b.GetMostDesiredAmmo(mostNeededAmmo);
if( mostNeededAmmo.Desire > 0) {
print("Need ammo for weapon", Util.WeaponName(mostNeededAmmo.AmmoType));
}</syntaxhighlight>
----

====FireWeapon====
Fires the current weapon.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.FireWeapon();</syntaxhighlight>

----
====HasAmmo====
Checks if the bot has a certain ammo type.

'''Parameters:''' () - If no parameters passed, checks current weapon ammo.

'''Parameters:''' (WeaponId)

'''Parameters:''' (WeaponId, needed amount)

'''Returns:''' true/false if the bot has ammo.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasAmmo())
{
}
if(b.HasAmmo(WEAPON.MP40))
{
}</syntaxhighlight>

----

====HasAnyWeapon====
Checks if the bot has any of specified weapons. Table keys are weaponIDs, table values should be set to true.

'''Parameters:''' (weapons, options<optional>, weaponList<optional>)

The second parameter is table which has items CheckAmmo and CheckCharged. Both options are true by default.

The third parameter is empty table to store all results.

'''Returns:''' weaponId if the bot has that weapon, 0 if the bot does not have any weapon from the list.

'''Example:''' <syntaxhighlight lang="java">
weapons = table();
weapons[WEAPON.MP40] = true;
weapons[WEAPON.THOMPSON] = true;
weapon = b.HasAnyWeapon(weapons, { CheckAmmo=true, CheckCharged=false } );
if (weapon) {
}</syntaxhighlight>

----

====HasWeapon====
Checks if the bot has a specific weapon.

'''Parameters:''' (weaponId)

'''Returns:''' true if the bot has it, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasWeapon(WEAPON.SHOTGUN))
{
}</syntaxhighlight>

----
====IsWeaponCharged====
Checks if a weapon is ''charged''. A charged weapon is one that is capable of being used that might occasionally be unavailable for use due to lack of character 'charge', whether that be a gameplay charge bar, stamina, skill, etc.

'''Parameters:''' (weaponId, firemode<optional>)

'''Returns:''' true if weapon is charged, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsWeaponCharged(WEAPON.MORTAR, 0))
{
}</syntaxhighlight>
----

===GetAllAlly===
Fills a table with all known allied entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllAlly(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllEnemy===
Fills a table with all known enemy entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllEnemy(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllType===
Fills a table with all known entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllType(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----

===GetClass===
Gets the current class id for the bot.

'''Parameters:''' none

'''Returns:''' class Id for bot

'''Example:''' <syntaxhighlight lang="java">
myclass = b.GetClass();
if(myClass == CLASS.SOLDIER)
{
}</syntaxhighlight>

----

===GetEyePosition===
Gets the world position of the bots 'eye'

'''Parameters:''' none

'''Returns:''' Vector3 eye position

'''Example:''' <syntaxhighlight lang="java">
eyepos = b.GetEyePosition();</syntaxhighlight>

----

===GetFacing===
Gets the facing vector for the bots aim. This method is fast, but can return incorrect value if the aim request is restricted by the game or mod (for example after revive). You can use function GetEntFacing to get correct facing.

'''Parameters:''' none

'''Returns:''' Vector3 facing vector

'''Example:''' <syntaxhighlight lang="java">
facing = b.GetFacing();
pointinfront = b.GetEyePosition() + facing * 100;</syntaxhighlight>

----

===GetGameEntity===
Gets the game entity for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
ent = b.GetGameEntity();</syntaxhighlight>

----

===GetGameId===
Gets the game id for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
gameid = b.GetGameId();</syntaxhighlight>

----

===GetHealthPercent===
Gets the bot's current health percentage.

'''Parameters:''' none

'''Returns:''' 0.0 - 1.0 health scalar

'''Example:''' <syntaxhighlight lang="java">
if(bot.GetHealthPercent() < 0.5)
{
// < 50% health
}</syntaxhighlight>
----
===GetHighLevelGoalName===
Gets the bot's current high level goal name.

Examples: UseCabinet, WatchForProjectile, CovertOps, BUILD, PLANT, CAMP, SWITCH, ROAMING, ...

Some goal names changed after they were moved to scripts.

Goals in 0.81: DefuseDynamite, ReviveTeammate, TakeCheckPoint, RepairMg42

Goals in 0.82: DEFUSE, REVIVE, CHECKPOINT, REPAIRMG42

Goals in 0.83: CaptureTheFlag, ReturnTheFlag, MobileMortar, PlantMine, CallArtillery

Goals in 0.84: FLAG, FLAGRETURN, MOBILEMORTAR, PLANTMINE, CALLARTILLERY

'''Parameters:''' none

'''Returns:''' goal name, or NULL if the bot doesn't have a high level goal.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetHighLevelGoalName();</syntaxhighlight>
----

===GetMapGoalName===
Gets the bot's current map goal name (for example: BUILD_Tank, DEFEND_depot1, ...).

Returns NULL if the current high level goal is ROAMING, WatchForProjectile or CovertOps.

Note: This function has been added in 0.82.

'''Parameters:''' none

'''Returns:''' goal name or NULL.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetMapGoalName();</syntaxhighlight>
----

===GetLastTarget===
Gets the target the bot had before the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
last = b.GetLastTarget();</syntaxhighlight>

----

===GetNearest===
Gets the nearest target matching the desired criteria, friend or foe.

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearest(CAT.PLAYER);
// get nearest soldier or medic player
s = b.GetNearest(CAT.PLAYER, {CLASS.SOLDIER, CLASS.MEDIC});</syntaxhighlight>

----

===GetNearestAlly===
Gets the nearest target matching the desired criteria, only allies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestAlly(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestAlly(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

===GetNearestEnemy===
Gets the nearest target matching the desired criteria, only enemies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestEnemy(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestEnemy(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

=== GetNearestDestination ===
Finds paths from the current bot position to multiple destination positions. Returns index of the destination which has the shortest path. It can depend on navigation flags (e.g. teleports, axis/allied waypoints).

'''Parameters:''' (table of vectors)

'''Returns:''' index OR null

'''Example:''' <syntaxhighlight lang="java">
positions = { Vec3(105,4564,0), Vec3(-48,1234,0) };
id = bot.GetNearestDestination(positions);
if(typeId(id)==0)
{
print("path not found");
}else{
print("path found to destination", positions[id]);
}
</syntaxhighlight>
----

===GetPosition===
Gets the world position of the bot.

'''Parameters:''' none

'''Returns:''' Vector3 world position

'''Example:''' <syntaxhighlight lang="java">
mypos = b.GetPosition();</syntaxhighlight>

----

===GetTarget===
Gets the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
target = b.GetTarget();</syntaxhighlight>

----

===GetTargetInfo===
Returns the [[TargetInfo]] for an entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' [[TargetInfo]] for entity.

'''Example:''' <syntaxhighlight lang="java">
ti = b.GetTargetInfo(b.GetTarget());</syntaxhighlight>

----

===GetTeam===
Gets the current team the bot is on.

'''Parameters:''' none

'''Returns:''' team #

'''Example:''' <syntaxhighlight lang="java">
myteam = b.GetTeam();</syntaxhighlight>

'''See also:''' [[TEAM]]

----

===GetVelocity===
Gets the world velocity of the bot. The bot must be alive. It returns wrong vector if the bot is injured.

'''Parameters:''' none

'''Returns:''' Vector3 world velocity

'''Example:''' <syntaxhighlight lang="java">
myvel = b.GetVelocity();</syntaxhighlight>

----

===HasTarget===
Checks if the bot has a current target

'''Parameters:''' none

'''Returns:''' true if bot has a target

'''Example:''' <syntaxhighlight lang="java">
if(b.HasTarget())
{
}</syntaxhighlight>

----

===HasAnyEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has at least one of the flags, or false if it doesn't have any of them.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has any flag, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasAnyEntityFlag(ENTFLAG.ZOOMING))
{
}
// checking multiple flags.
if(b.HasAnyEntityFlag(ENTFLAG.MOUNTED, ENTFLAG.ON_LADDER))
{
}</syntaxhighlight>

----

===HasEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has all flags, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasEntityFlag(ENTFLAG.RELOADING))
{
}
// checking multiple flags.
if(b.HasEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER))
{
}</syntaxhighlight>

----

===HasLineOfSightTo===
This functions checks whether the bot has line of sight to a 3d position. This function does not account for field of view, simply does a raycast for obstructions between the bots eye position and the provided position. To account for field of view, use [[Bot#InFieldOfView|InFieldOfView]]. If an entity or gameId is provided as the 2nd parameter, the function will return true if the raycast hits nothing on its way to the position OR if it hits the entity that is passed.

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, entity)

'''Returns:''' true if the bot has line of sight to the position or entity passed. false if the bot's view is obstructed.

'''Note:''' This function calls [[Bot_Library#TraceLine|TraceLine]] with parameter TRACE.SHOT | TRACE.SMOKEBOMB

'''Example:''' <syntaxhighlight lang="java">
if(b.HasLineOfSightTo( Vec3(30,50,10) ))
{
}</syntaxhighlight>

----

===HasPowerUp===
Checks if the bot has a given powerup. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (powerup, ...)

'''Returns:''' true if bot has all powerups, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasPowerUp(POWERUP.INVINCIBLE))
{
}
// checking multiple flags.
if(b.HasPowerUp(POWERUP.INVINCIBLE, POWERUP.QUADDAMAGE))
{
}</syntaxhighlight>

----

===HasRole===
Checks if the bot has a specific role or any role.

'''Parameters:''' roleId <optional>

'''Returns:''' true if the bot has role, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasRole(ROLE.INFILTRATOR)){
}
</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#SetRoles| SetRoles]]

----

===HoldButton===
Makes the bot 'press' a button, and hold it for an amount of time. This function can take any number of buttons as parameters, and will apply the effect to all of them. The time value is '''ALWAYS''' the last parameter.

'''Parameters:''' (buttonId, ..., time in seconds)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// hold crouch for 5 seconds
b.HoldButton(BTN.CROUCH, 5);
// hold multiple buttons for 5 seconds
b.HoldButton(BTN.CROUCH, BTN.SPRINT, 5);</syntaxhighlight>

'''See Also:''' [[Bot#PressButton| PressButton]], [[Bot#ReleaseButton| ReleaseButton]]

----

===IgnoreTarget===
This function causes the bot to ignore specific entities for targeting for some duration of time.

'''Parameters:''' (entity/gameId or goal name or table, seconds to ignore <optional>)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// ignore the entity, so the bot won't shoot at it.
bot.IgnoreTarget("MOVER_bird1");
bot.IgnoreTarget(Map.Movers);
bot.IgnoreTarget(GetLocalEntity(), 100);</syntaxhighlight>

'''See also:''' [[Bots shooting map objects]]

----

===InFieldOfView===
Checks whether a position is within the bots current [[Bot#FieldOfView | FieldOfView]]. This function can take an optional field of view(in degrees) to check. If not provided, it will use the bots current [[Bot#FieldOfView | FieldOfView]].

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, fov angles)

'''Returns:''' Vector3 - center point of the AABB.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,10,10);
// check if in default field of view
if(b.InFieldOfView(v))
{
}
// check if in custom field of view
if(b.InFieldOfView(v, 180))
{
}</syntaxhighlight>
----

===IsAllied===
Checks if the bot is allied with a given entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' true if allied, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsAllied(someentity))
{
}</syntaxhighlight>
----

===IsCarryingFlag===
Checks if the bot is carrying objective (flag, gold, documents, radar parts, ...).

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(b.IsCarryingFlag())
{
}
</syntaxhighlight>
----
===IsStuck===
Checks if the bot considers himself to be stuck. Stuckness is typically defined as an insignificant amount of movement over a short period of time. The time can be optionally passed to the function for flexibility.

'''Parameters:''' () - If no params passed, the time used is 0.5 seconds.

'''Parameters:''' (time in seconds)

'''Returns:''' true if bot is ''stuck'', false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsStuck())
{
}
// or check stuckness for 1.5 seconds.
if(b.IsStuck(1.5))
{
}</syntaxhighlight>
----

===MoveTowards===
Causes the bot to blindly move towards a target. This function does no path finding. It's primary use is short range movement when you are reasonably sure the bot can run right at the target.

'''Parameters:''' (Vector3 position) - if distance tolerance not specified, default of 32 units is used.

'''Parameters:''' (Vector3 position, distance tolerance)

'''Returns:''' true if the bot is within the distance tolerance, false if not.

'''Example:''' <syntaxhighlight lang="java">
// get within 64 units of this position
v = Vector3(10,10,10);
while(b.MoveTowards(v, 64) == false)
{
yield();
} </syntaxhighlight>
----

===PressButton===
Makes the bot 'press' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them. Buttons that are ''pressed'' using this function are released automatically for the next bot update.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// press crouch
b.PressButton(BTN.CROUCH);
// press multiple buttons
b.PressButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#ReleaseButton| ReleaseButton]]
----

===ReleaseButton===
Makes the bot 'release' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// release crouch
b.ReleaseButton(BTN.CROUCH);
// release multiple buttons
b.ReleaseButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#PressButton| PressButton]]
----

===ReloadProfile===
Reloads the bots profile. The profile is any script associated with the bots name.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ReloadProfile();</syntaxhighlight>
----

===ResetStuckTime===
Reset the stuck timer.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ResetStuckTime();</syntaxhighlight>

----

===Say===
Chat function used for bots to ''say'' messages through the normal chat channels of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Say("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#SayTeam| SayTeam]], [[Bot#SayVoice| SayVoice]]
----

===SayTeam===
Chat function used for bots to ''say'' messages through the team chat channel of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayTeam("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayVoice| SayVoice]]
----

===SayVoice===
Broadcasts a voice macro to the game. Used with global [[VOICE]] table values.

'''Parameters:''' (macroId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayVoice(VOICE.NEED_MEDIC);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayTeam| SayTeam]]
----

===ScriptEvent===
Sends [[EVENT#SCRIPTMSG|SCRIPTMSG]] event.

'''Parameters:''' (name, param1, param2, param3)

'''Returns:''' none
----

===SetDebugFlag===
Enables a debug flag for the bot. See the global [[DEBUG]] table for available options. Enabling debug flags typically cause various debug visualizations to render in order to help identify whats going on with various systems of the bot.

'''Parameters:''' (flag, true/false to enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetDebugFlag(DEBUG.AIM, true);</syntaxhighlight>
----

===SetRoles===
Assign a role to the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#HasRole| HasRole]]

----

===ToLocalSpace===
Converts a vector into local bot space. This results in a position relative to the bots current position and rotation. This function is useful for simplifying some types of logic.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 local space position.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(4356,342,276); // some world position.
v2 = b.ToLocalSpace(v);
if(v2.y < 0)
{
// the position is behind the bot.
}
if(v2.x < 0)
{
// the position is to the right of the bot
}</syntaxhighlight>

----

===ToWorldSpace===
Converts a vector from local bot space to world space.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 world space position.

'''Example:''' <syntaxhighlight lang="java">
// slightly forward and to the right.
v = Vector3(10,10,0);
v2 = b.ToWorldSpace(v);</syntaxhighlight>

----

===Enemy Territory Addendum===

====ChangePrimaryWeapon====
Selects a new primary weapon for the bot. Should take effect next spawn. You must not use this function inside map scripts. You should use [[Utility_Functions#WeaponTable.SetWeaponAvailability|SetWeaponAvailability]] if you want to disable some weapons.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangePrimaryWeapon(WEAPON.PANZERFAUST);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangeSecondaryWeapon| ChangeSecondaryWeapon]]
----

====ChangeSecondaryWeapon====
Selects a new secondary weapon for the bot. Should take effect next spawn.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSecondaryWeapon(WEAPON.LUGER);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangePrimaryWeapon| ChangePrimaryWeapon]]
----

====ChangeSpawnPoint====
Changes the desired spawn point for the bot to respawn at.

'''Parameters:''' (spawnpoint #)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSpawnPoint(2); </syntaxhighlight>

----

====GetConstructableState====
Check state of a BUILD goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can build the entity, 0 if the entity is already built, -1 if the entity is not constructable or has been built by enemy.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetConstructableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetCursorHint====
When a player is near enough something to get a hint icon, such as for dynamiting, this function can access what hint is showing. Some of these hints may or may not ever show up, they were taken as-is from the ET SDK.

* NONE - 0
* PLAYER - 1
* ACTIVATE - 2
* DOOR - 3
* DOOR_ROTATING - 4
* DOOR_LOCKED - 5
* DOOR_ROTATING_LOCKED - 6
* MG42 - 7
* BREAKABLE - 8
* BREAKABLE_DYNAMITE - 9
* CHAIR - 10
* ALARM - 11
* HEALTH - 12
* TREASURE - 13
* KNIFE - 14
* LADDER - 15
* BUTTON - 16
* WATER - 17
* CAUTION - 18
* DANGER - 19
* SECRET - 20
* QUESTION - 21
* EXCLAMATION - 22
* CLIPBOARD - 23
* WEAPON - 24
* AMMO - 25
* ARMOR - 26
* POWERUP - 27
* HOLDABLE - 28
* INVENTORY - 29
* SCENARIC - 30
* EXIT - 31
* NOEXIT - 32
* PLYR_FRIEND - 33
* PLYR_NEUTRAL - 34
* PLYR_ENEMY - 35
* PLYR_UNKNOWN - 36
* BUILD - 37
* DISARM - 38
* REVIVE - 39
* DYNAMITE - 40
* CONSTRUCTIBLE - 41
* UNIFORM - 42
* LANDMINE - 43
* TANK - 44
* SATCHELCHARGE - 45
* LOCKPICK - 46

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
hint = table();
b.GetCursorHint(hint);

print(hint.type); // one of the values above
print(hint.value); // usually a health associated with certain types </syntaxhighlight>
----

====GetDestroyableState====
Check state of a PLANT goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can destroy the entity, -1 if the entity is not destroyable or is friendly objective.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetDestroyableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetExplosiveState====
Check state of a dynamite, landmine or tripmine.

'''Note:''' It does not work for a poison mine and bouncing betty in Jaymod.

'''Parameters:''' (entity)

'''Returns:''' 1 if the dynamite/mine can be armed, 0 if the dynamite is ticking or the mine is activated.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetExplosiveState(TargetEntity) == 1 ) {
}</syntaxhighlight>

----

====GetMG42Info====
Gets information about currently mounted MG42 - vector CenterFacing and angles MinHorizontal, MaxHorizontal, MinVertical, MaxVertical.

'''Parameters:''' (table)

'''Returns:''' true if info has been stored into table

----

====GetMountedPlayerOnMG42====
Gets player who is mounting MG42.

'''Parameters:''' (mg42Entity)

'''Returns:''' player's entity or null

----

====GetReinforceTime====
Gets the current time left(in seconds) before reinforcements spawn for the bots team.

'''Parameters:''' none

'''Returns:''' seconds left till reinforcements spawn

'''Example:''' <syntaxhighlight lang="java">
if(b.GetReinforceTime() < 2)
{
// 2 seconds to reinforcements
}</syntaxhighlight>

----

====GetSkills====
Gets the current skill values and puts them into the table parameter.

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
skills = table();
b.GetSkills(skills);
print("Battle Sense:", skills[SKILL.BATTLE_SENSE]);
print("Engineering:", skills[SKILL.ENGINEERING]);
print("First Aid:", skills[SKILL.FIRST_AID]);
print("Signals:", skills[SKILL.SIGNALS]);
print("Light Weapons:", skills[SKILL.LIGHT_WEAPONS]);
print("Heavy Weapons:", skills[SKILL.HEAVY_WEAPONS]);
print("Coverops:", skills[SKILL.COVERTOPS]); </syntaxhighlight>

'''See Also:''' [[SKILL]]
----
====GetStat====
Gets a current stat from the bot by name. Valid stat names for ET are kills, deaths and xp.

'''Parameters:''' (string) the stat name

'''Returns:''' the value of the stat

'''Example:''' <syntaxhighlight lang="java">
xp = b.GetStat("xp");
print("Bot xp value is",xp);</syntaxhighlight>

----

====IsMG42Repairable====

'''Parameters:''' (mg42Entity)

'''Returns:''' true if mg42 is damaged and can be repaired

----
====TeamLandminesAvailable====

'''Parameters:''' none

'''Returns:''' remaining count of team landmines

----

Bot

2025-02-10T19:09:02Z

Palota: /* DistanceTo */

{{process header
| title = Bot Functions
| section =
| previous = [[Omni-bot_Script_Reference | Script Reference]]
| next =
| shortcut =
| notes =
}}
{{TOCright}}
==Bot Properties==

----

Unless otherwise noted, all properties can be get and set.

=== AimDamping ===
Effects the acceleration and turn rate.
=== AimPersistance ===
The time(in seconds) the bot will continue to aim at the last position of a target before aborting.
=== AimStiffness ===
Effects the acceleration of turning.
=== AimTolerance ===
The tolerance(in degrees) the bot tries to aim at stuff with.
=== Armor ===
Current Armor
=== FieldOfView ===
The angle(in degrees) the bot is capable of 'seeing'.
=== Health ===
Current health.
=== MaxArmor ===
Max Armor
=== MaxHealth ===
Max Health
=== MaxTurnSpeed ===
The maximum speed(in degrees/second) the bot can rotate his aim at.
=== MaxViewDistance ===
The max distance(in game units) the bot is capable of seeing.
=== MemorySpan ===
The time(in seconds) taken for the memory about an entity to become stale.
=== Name ===
Name of the bot.

=== ReactionTime ===
The time(in seconds) it takes the bot to begin responding to a newly sensed threat.

----

=== Enemy Territory Addendum ===

----

==== DoNotKill ====
Set it to true to prevent medics to kill the bot for revive. It is used by BUILD, PLANT and PLANTMINE goals.
==== TargetBreakableDist ====
The maximum distance (in game units) the bot will attempt to target breakable entities. It can be set by [[Pre-Scripted_Regions#BreakableDistance|pre-scripted trigger region]] or inside [[Creating_a_script|OnBotJoin]] function.

----

==Bot Functions==
----
===AddScriptGoal===
Adds a goal to the bots behavior tree by name. Useful when a script goal has AutoAdd set to false, so you can more explicitly control when a bot gets the goal.

'''Parameters:''' (name of script goal to add to bot behavior tree)

'''Returns:''' true on success, false on failure

'''Example:''' <syntaxhighlight lang="java">
b.AddScriptGoal("TestBot");</syntaxhighlight>
----
===RemoveState===
Removes a state from a bots behavior tree by name.

'''Parameters:''' (name of script goal to remove from bot behavior tree)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.RemoveState("TestBot");</syntaxhighlight>
----
===SetStateEnabled===
Enables/Disables a state by name.

'''Parameters:''' (name of state, bool enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetStateEnabled("Attack", false); // disable attack state</syntaxhighlight>
----

===CanGrabItem===
Returns true if bot can take item (flag, gold, radar parts, ...).

'''Parameters:''' (GameEntity)

'''Parameters:''' (FLAG or FLAG_dropped goal name)

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if (b.CanGrabItem("FLAG_gold")) {
}</syntaxhighlight>

----

===ChangeClass===
Changes the bot to a specified class.

'''Parameters:''' (classId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeClass(CLASS.SOLDIER);</syntaxhighlight>

----

===ChangeTeam===
Changes the bot to a specified team.

'''Parameters:''' (teamId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeTeam(TEAM.AXIS);</syntaxhighlight>

----

===ClearRoles===
Takes away a role from the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ClearRoles(ROLE.ATTACKER);</syntaxhighlight>

'''See Also:'''
[[Bot#SetRoles| SetRoles]], [[Bot#HasRole| HasRole]]

----

===DisableBotPush===
Used by [[Pre-Scripted_Regions#DisableBotPush|pre-scripted trigger region]].

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DisableBotPush(true);</syntaxhighlight>

----

===DistanceTo===
Overloaded utility function for simplified distance checks.

'''Parameters:''' (Vector3, notUseEyePosition<default false>)

'''Parameters:''' (MapGoal, notUseEyePosition<default false>)

'''Parameters:''' (GameEntity/GameId, notUseEyePosition<default false>)

'''Returns:''' float - distance from bot to Vector3, MapGoal, GameEntity or GameId

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,20,30);
target = b.GetTarget();
// distance from bot to target entity
d1 = b.DistanceTo(target, true);
// distance from bot to world position
d2 = b.DistanceTo(v, true);
// distance from bot eye to world position
d3 = b.DistanceTo(v);</syntaxhighlight>
----

===DumpBotTable===
Dumps a file with the bot's table to a file in the user folder.

'''Parameters:''' (filename)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.DumpBotTable("foo.txt");</syntaxhighlight>

----

===Enable===
Disables all thinking for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Enable(false);</syntaxhighlight>

----

===ExecCommand===
Executes a string command on the bot as if the bot executed a console command.

'''Parameters:''' (command)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ExecCommand("kill");</syntaxhighlight>

----

===Weapons/Ammo===
====CanSnipe====
It's deprecated and has been replaced by Util.CanBotSnipe(bot) in Enemy Territory.

Checks if the bot can snipe based on the internally implemented snipe checks. Vary by game. Typically involves checking if the bot has a snipe enabled weapon and has ammo.

'''Parameters:''' none

'''Returns:''' true if the bot can snipe, else false

'''Example:''' <syntaxhighlight lang="java">
if(b.CanSnipe()) {}</syntaxhighlight>

----

====EnableShooting====
Disables all shooting for the bot.

'''Parameters:''' (true/false)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.EnableShooting(false);</syntaxhighlight>

----
====GetWeapon====
Gets a reference to a specific weapon from the bot.

'''Parameters:''' (weaponId)

'''Returns:''' [[Weapon]] reference, or NULL if the bot doesn't have the weapon.

'''Example:''' <syntaxhighlight lang="java">
wpn = b.GetWeapon(WEAPON.SHOTGUN);
wpn.PrimaryFire.AimOffset = Vector3(0,0,10);</syntaxhighlight>

----
====GetBestWeapon====
Gets a weapon id for the best weapon versus current target or a specific entity.

'''Parameters:''' none - uses current target

'''Parameters:''' (entity) evaluate weapon versus specific target entity

'''Returns:''' weapon id of weapon that is chosen.

'''Example:''' <syntaxhighlight lang="java">
best = b.GetBestWeapon();
// OR
best = b.GetBestWeapon(someEnt);</syntaxhighlight>

----
====GetRandomWeapon====
Gets a random weapon id from the list of weapons the bot currently has.

'''Parameters:''' none

'''Returns:''' random weapon id

'''Example:''' <syntaxhighlight lang="java">
randwpn = b.GetRandomWeapon();</syntaxhighlight>

----

====GetCurrentWeapon====
Gets the current weapon id for the bot.

'''Parameters:''' none

'''Returns:''' weapon Id for bot

'''Example:''' <syntaxhighlight lang="java">
mywpn = b.GetCurrentWeapon();
if(mywpn == WEAPON.SHOTGUN)
{
}</syntaxhighlight>

----
====GetCurrentAmmo====
Gets the ammo information for a weapon.

'''Parameters:''' (table)

'''Parameters:''' (table, firemode)

'''Parameters:''' (table, firemode, weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
ammoTable = {};
// Get primary ammo for current weapon
b.GetCurrentAmmo(ammoTable);
// Get secondary ammo for current weapon
b.GetCurrentAmmo(ammoTable, 1);
// Get primary ammo for another weapon.
b.GetCurrentAmmo(ammoTable, 0, WEAPON.SHOTGUN);

print("Current Ammo:", ammoTable.CurrentAmmo);
print("Max Ammo:", ammoTable.MaxAmmo);
print("Current Clips:", ammoTable.CurrentClip);
print("Max Clips:", ammoTable.MaxClip);</syntaxhighlight>

----

====GetMostDesiredAmmo====
Gets information about the currently most needed ammo.

'''Parameters:''' (table)

'''Returns:''' none

* AmmoType - weapon ID
* Desire - [[Weapon#LowAmmoPriority|LowAmmoPriority]]; It will be zero if bot has more ammo than [[Weapon#LowAmmoThreshold|LowAmmoThreshold]]
* GetAmmo - [[Weapon#LowAmmoGetAmmoAmount|LowAmmoGetAmmoAmount]]

'''Example:''' <syntaxhighlight lang="java">
mostNeededAmmo = {};
b.GetMostDesiredAmmo(mostNeededAmmo);
if( mostNeededAmmo.Desire > 0) {
print("Need ammo for weapon", Util.WeaponName(mostNeededAmmo.AmmoType));
}</syntaxhighlight>
----

====FireWeapon====
Fires the current weapon.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.FireWeapon();</syntaxhighlight>

----
====HasAmmo====
Checks if the bot has a certain ammo type.

'''Parameters:''' () - If no parameters passed, checks current weapon ammo.

'''Parameters:''' (WeaponId)

'''Parameters:''' (WeaponId, needed amount)

'''Returns:''' true/false if the bot has ammo.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasAmmo())
{
}
if(b.HasAmmo(WEAPON.MP40))
{
}</syntaxhighlight>

----

====HasAnyWeapon====
Checks if the bot has any of specified weapons. Table keys are weaponIDs, table values should be set to true.

'''Parameters:''' (weapons, options<optional>, weaponList<optional>)

The second parameter is table which has items CheckAmmo and CheckCharged. Both options are true by default.

The third parameter is empty table to store all results.

'''Returns:''' weaponId if the bot has that weapon, 0 if the bot does not have any weapon from the list.

'''Example:''' <syntaxhighlight lang="java">
weapons = table();
weapons[WEAPON.MP40] = true;
weapons[WEAPON.THOMPSON] = true;
weapon = b.HasAnyWeapon(weapons, { CheckAmmo=true, CheckCharged=false } );
if (weapon) {
}</syntaxhighlight>

----

====HasWeapon====
Checks if the bot has a specific weapon.

'''Parameters:''' (weaponId)

'''Returns:''' true if the bot has it, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasWeapon(WEAPON.SHOTGUN))
{
}</syntaxhighlight>

----
====IsWeaponCharged====
Checks if a weapon is ''charged''. A charged weapon is one that is capable of being used that might occasionally be unavailable for use due to lack of character 'charge', whether that be a gameplay charge bar, stamina, skill, etc.

'''Parameters:''' (weaponId, firemode<optional>)

'''Returns:''' true if weapon is charged, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsWeaponCharged(WEAPON.MORTAR, 0))
{
}</syntaxhighlight>
----

===GetAllAlly===
Fills a table with all known allied entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllAlly(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllEnemy===
Fills a table with all known enemy entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllEnemy(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----
===GetAllType===
Fills a table with all known entities (from bot's sensory memory) that match a desired criteria.

'''Parameters:''' (category, class, table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// Get all known soldier players.
players = table();
b.GetAllType(CAT.PLAYER, CLASS.SOLDIER, players);
foreach ( ent in players )
{
print(ent);
}</syntaxhighlight>

----

===GetClass===
Gets the current class id for the bot.

'''Parameters:''' none

'''Returns:''' class Id for bot

'''Example:''' <syntaxhighlight lang="java">
myclass = b.GetClass();
if(myClass == CLASS.SOLDIER)
{
}</syntaxhighlight>

----

===GetEyePosition===
Gets the world position of the bots 'eye'

'''Parameters:''' none

'''Returns:''' Vector3 eye position

'''Example:''' <syntaxhighlight lang="java">
eyepos = b.GetEyePosition();</syntaxhighlight>

----

===GetFacing===
Gets the facing vector for the bots aim.

'''Parameters:''' none

'''Returns:''' Vector3 facing vector

'''Example:''' <syntaxhighlight lang="java">
facing = b.GetFacing();
pointinfront = b.GetEyePosition() + facing * 100;</syntaxhighlight>

----

===GetGameEntity===
Gets the game entity for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
ent = b.GetGameEntity();</syntaxhighlight>

----

===GetGameId===
Gets the game id for the bot.

'''Parameters:''' none

'''Returns:''' entity

'''Example:''' <syntaxhighlight lang="java">
gameid = b.GetGameId();</syntaxhighlight>

----

===GetHealthPercent===
Gets the bot's current health percentage.

'''Parameters:''' none

'''Returns:''' 0.0 - 1.0 health scalar

'''Example:''' <syntaxhighlight lang="java">
if(bot.GetHealthPercent() < 0.5)
{
// < 50% health
}</syntaxhighlight>
----
===GetHighLevelGoalName===
Gets the bot's current high level goal name.

Examples: UseCabinet, WatchForProjectile, CovertOps, BUILD, PLANT, CAMP, SWITCH, ROAMING, ...

Some goal names changed after they were moved to scripts.

Goals in 0.81: DefuseDynamite, ReviveTeammate, TakeCheckPoint, RepairMg42

Goals in 0.82: DEFUSE, REVIVE, CHECKPOINT, REPAIRMG42

Goals in 0.83: CaptureTheFlag, ReturnTheFlag, MobileMortar, PlantMine, CallArtillery

Goals in 0.84: FLAG, FLAGRETURN, MOBILEMORTAR, PLANTMINE, CALLARTILLERY

'''Parameters:''' none

'''Returns:''' goal name, or NULL if the bot doesn't have a high level goal.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetHighLevelGoalName();</syntaxhighlight>
----

===GetMapGoalName===
Gets the bot's current map goal name (for example: BUILD_Tank, DEFEND_depot1, ...).

Returns NULL if the current high level goal is ROAMING, WatchForProjectile or CovertOps.

Note: This function has been added in 0.82.

'''Parameters:''' none

'''Returns:''' goal name or NULL.

'''Example:''' <syntaxhighlight lang="java">
g = bot.GetMapGoalName();</syntaxhighlight>
----

===GetLastTarget===
Gets the target the bot had before the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
last = b.GetLastTarget();</syntaxhighlight>

----

===GetNearest===
Gets the nearest target matching the desired criteria, friend or foe.

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearest(CAT.PLAYER);
// get nearest soldier or medic player
s = b.GetNearest(CAT.PLAYER, {CLASS.SOLDIER, CLASS.MEDIC});</syntaxhighlight>

----

===GetNearestAlly===
Gets the nearest target matching the desired criteria, only allies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestAlly(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestAlly(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

===GetNearestEnemy===
Gets the nearest target matching the desired criteria, only enemies

'''Parameters:''' (category)

'''Parameters:''' (category, classId)

'''Parameters:''' (category, table of classIds)

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
// get nearest player, defaults to any class within that category
p = b.GetNearestEnemy(CAT.PLAYER);
// get nearest soldier player
s = b.GetNearestEnemy(CAT.PLAYER, CLASS.SOLDIER);</syntaxhighlight>

----

=== GetNearestDestination ===
Finds paths from the current bot position to multiple destination positions. Returns index of the destination which has the shortest path. It can depend on navigation flags (e.g. teleports, axis/allied waypoints).

'''Parameters:''' (table of vectors)

'''Returns:''' index OR null

'''Example:''' <syntaxhighlight lang="java">
positions = { Vec3(105,4564,0), Vec3(-48,1234,0) };
id = bot.GetNearestDestination(positions);
if(typeId(id)==0)
{
print("path not found");
}else{
print("path found to destination", positions[id]);
}
</syntaxhighlight>
----

===GetPosition===
Gets the world position of the bot.

'''Parameters:''' none

'''Returns:''' Vector3 world position

'''Example:''' <syntaxhighlight lang="java">
mypos = b.GetPosition();</syntaxhighlight>

----

===GetTarget===
Gets the current target.

'''Parameters:''' none

'''Returns:''' entity OR null

'''Example:''' <syntaxhighlight lang="java">
target = b.GetTarget();</syntaxhighlight>

----

===GetTargetInfo===
Returns the [[TargetInfo]] for an entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' [[TargetInfo]] for entity.

'''Example:''' <syntaxhighlight lang="java">
ti = b.GetTargetInfo(b.GetTarget());</syntaxhighlight>

----

===GetTeam===
Gets the current team the bot is on.

'''Parameters:''' none

'''Returns:''' team #

'''Example:''' <syntaxhighlight lang="java">
myteam = b.GetTeam();</syntaxhighlight>

'''See also:''' [[TEAM]]

----

===GetVelocity===
Gets the world velocity of the bot. The bot must be alive. It returns wrong vector if the bot is injured.

'''Parameters:''' none

'''Returns:''' Vector3 world velocity

'''Example:''' <syntaxhighlight lang="java">
myvel = b.GetVelocity();</syntaxhighlight>

----

===HasTarget===
Checks if the bot has a current target

'''Parameters:''' none

'''Returns:''' true if bot has a target

'''Example:''' <syntaxhighlight lang="java">
if(b.HasTarget())
{
}</syntaxhighlight>

----

===HasAnyEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has at least one of the flags, or false if it doesn't have any of them.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has any flag, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasAnyEntityFlag(ENTFLAG.ZOOMING))
{
}
// checking multiple flags.
if(b.HasAnyEntityFlag(ENTFLAG.MOUNTED, ENTFLAG.ON_LADDER))
{
}</syntaxhighlight>

----

===HasEntityFlag===
Checks if the bot has a given entity flag. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (entityflag, ...)

'''Returns:''' true if bot has all flags, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasEntityFlag(ENTFLAG.RELOADING))
{
}
// checking multiple flags.
if(b.HasEntityFlag(ENTFLAG.INWATER, ENTFLAG.UNDERWATER))
{
}</syntaxhighlight>

----

===HasLineOfSightTo===
This functions checks whether the bot has line of sight to a 3d position. This function does not account for field of view, simply does a raycast for obstructions between the bots eye position and the provided position. To account for field of view, use [[Bot#InFieldOfView|InFieldOfView]]. If an entity or gameId is provided as the 2nd parameter, the function will return true if the raycast hits nothing on its way to the position OR if it hits the entity that is passed.

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, entity)

'''Returns:''' true if the bot has line of sight to the position or entity passed. false if the bot's view is obstructed.

'''Note:''' This function calls [[Bot_Library#TraceLine|TraceLine]] with parameter TRACE.SHOT | TRACE.SMOKEBOMB

'''Example:''' <syntaxhighlight lang="java">
if(b.HasLineOfSightTo( Vec3(30,50,10) ))
{
}</syntaxhighlight>

----

===HasPowerUp===
Checks if the bot has a given powerup. This function can take any number of flags to check, and will return true if the bot has all the flags, or false if it is missing any.

'''Parameters:''' (powerup, ...)

'''Returns:''' true if bot has all powerups, false if not

'''Example:''' <syntaxhighlight lang="java">
// checking 1 flag
if(b.HasPowerUp(POWERUP.INVINCIBLE))
{
}
// checking multiple flags.
if(b.HasPowerUp(POWERUP.INVINCIBLE, POWERUP.QUADDAMAGE))
{
}</syntaxhighlight>

----

===HasRole===
Checks if the bot has a specific role or any role.

'''Parameters:''' roleId <optional>

'''Returns:''' true if the bot has role, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.HasRole(ROLE.INFILTRATOR)){
}
</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#SetRoles| SetRoles]]

----

===HoldButton===
Makes the bot 'press' a button, and hold it for an amount of time. This function can take any number of buttons as parameters, and will apply the effect to all of them. The time value is '''ALWAYS''' the last parameter.

'''Parameters:''' (buttonId, ..., time in seconds)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// hold crouch for 5 seconds
b.HoldButton(BTN.CROUCH, 5);
// hold multiple buttons for 5 seconds
b.HoldButton(BTN.CROUCH, BTN.SPRINT, 5);</syntaxhighlight>

'''See Also:''' [[Bot#PressButton| PressButton]], [[Bot#ReleaseButton| ReleaseButton]]

----

===IgnoreTarget===
This function causes the bot to ignore specific entities for targeting for some duration of time.

'''Parameters:''' (entity/gameId or goal name or table, seconds to ignore <optional>)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// ignore the entity, so the bot won't shoot at it.
bot.IgnoreTarget("MOVER_bird1");
bot.IgnoreTarget(Map.Movers);
bot.IgnoreTarget(GetLocalEntity(), 100);</syntaxhighlight>

'''See also:''' [[Bots shooting map objects]]

----

===InFieldOfView===
Checks whether a position is within the bots current [[Bot#FieldOfView | FieldOfView]]. This function can take an optional field of view(in degrees) to check. If not provided, it will use the bots current [[Bot#FieldOfView | FieldOfView]].

'''Parameters:''' (Vector3 position)

'''Parameters:''' (Vector3 position, fov angles)

'''Returns:''' Vector3 - center point of the AABB.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(10,10,10);
// check if in default field of view
if(b.InFieldOfView(v))
{
}
// check if in custom field of view
if(b.InFieldOfView(v, 180))
{
}</syntaxhighlight>
----

===IsAllied===
Checks if the bot is allied with a given entity.

'''Parameters:''' (entity/gameId)

'''Returns:''' true if allied, false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsAllied(someentity))
{
}</syntaxhighlight>
----

===IsCarryingFlag===
Checks if the bot is carrying objective (flag, gold, documents, radar parts, ...).

'''Parameters:''' none

'''Returns:''' true/false

'''Example:''' <syntaxhighlight lang="java">
if(b.IsCarryingFlag())
{
}
</syntaxhighlight>
----
===IsStuck===
Checks if the bot considers himself to be stuck. Stuckness is typically defined as an insignificant amount of movement over a short period of time. The time can be optionally passed to the function for flexibility.

'''Parameters:''' () - If no params passed, the time used is 0.5 seconds.

'''Parameters:''' (time in seconds)

'''Returns:''' true if bot is ''stuck'', false if not.

'''Example:''' <syntaxhighlight lang="java">
if(b.IsStuck())
{
}
// or check stuckness for 1.5 seconds.
if(b.IsStuck(1.5))
{
}</syntaxhighlight>
----

===MoveTowards===
Causes the bot to blindly move towards a target. This function does no path finding. It's primary use is short range movement when you are reasonably sure the bot can run right at the target.

'''Parameters:''' (Vector3 position) - if distance tolerance not specified, default of 32 units is used.

'''Parameters:''' (Vector3 position, distance tolerance)

'''Returns:''' true if the bot is within the distance tolerance, false if not.

'''Example:''' <syntaxhighlight lang="java">
// get within 64 units of this position
v = Vector3(10,10,10);
while(b.MoveTowards(v, 64) == false)
{
yield();
} </syntaxhighlight>
----

===PressButton===
Makes the bot 'press' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them. Buttons that are ''pressed'' using this function are released automatically for the next bot update.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// press crouch
b.PressButton(BTN.CROUCH);
// press multiple buttons
b.PressButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#ReleaseButton| ReleaseButton]]
----

===ReleaseButton===
Makes the bot 'release' a button. This function can take any number of buttons as parameters, and will apply the effect to all of them.

'''Parameters:''' (buttonId, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
// release crouch
b.ReleaseButton(BTN.CROUCH);
// release multiple buttons
b.ReleaseButton(BTN.CROUCH, BTN.SPRINT);</syntaxhighlight>

'''See Also:''' [[Bot#HoldButton | HoldButton]], [[Bot#PressButton| PressButton]]
----

===ReloadProfile===
Reloads the bots profile. The profile is any script associated with the bots name.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ReloadProfile();</syntaxhighlight>
----

===ResetStuckTime===
Reset the stuck timer.

'''Parameters:''' none

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ResetStuckTime();</syntaxhighlight>

----

===Say===
Chat function used for bots to ''say'' messages through the normal chat channels of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.Say("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#SayTeam| SayTeam]], [[Bot#SayVoice| SayVoice]]
----

===SayTeam===
Chat function used for bots to ''say'' messages through the team chat channel of the game. For flexibility, this function can take any number and type of parameters, which it will convert to a single long string and use as the chat message.

'''Parameters:''' (string, ...)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayTeam("My name is ", b.Name);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayVoice| SayVoice]]
----

===SayVoice===
Broadcasts a voice macro to the game. Used with global [[VOICE]] table values.

'''Parameters:''' (macroId)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SayVoice(VOICE.NEED_MEDIC);</syntaxhighlight>

'''See Also:'''
[[Bot#Say| Say]], [[Bot#SayTeam| SayTeam]]
----

===ScriptEvent===
Sends [[EVENT#SCRIPTMSG|SCRIPTMSG]] event.

'''Parameters:''' (name, param1, param2, param3)

'''Returns:''' none
----

===SetDebugFlag===
Enables a debug flag for the bot. See the global [[DEBUG]] table for available options. Enabling debug flags typically cause various debug visualizations to render in order to help identify whats going on with various systems of the bot.

'''Parameters:''' (flag, true/false to enable)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetDebugFlag(DEBUG.AIM, true);</syntaxhighlight>
----

===SetRoles===
Assign a role to the bot.

'''Parameters:''' roleId

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.SetRoles(ROLE.DEFENDER);</syntaxhighlight>

'''See Also:'''
[[Bot#ClearRoles| ClearRoles]], [[Bot#HasRole| HasRole]]

----

===ToLocalSpace===
Converts a vector into local bot space. This results in a position relative to the bots current position and rotation. This function is useful for simplifying some types of logic.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 local space position.

'''Example:''' <syntaxhighlight lang="java">
v = Vector3(4356,342,276); // some world position.
v2 = b.ToLocalSpace(v);
if(v2.y < 0)
{
// the position is behind the bot.
}
if(v2.x < 0)
{
// the position is to the right of the bot
}</syntaxhighlight>

----

===ToWorldSpace===
Converts a vector from local bot space to world space.

* x axis is side to side.
* y axis is forward and back.
* z axis is up and down.

'''Parameters:''' (Vector3)

'''Returns:''' Vector3 world space position.

'''Example:''' <syntaxhighlight lang="java">
// slightly forward and to the right.
v = Vector3(10,10,0);
v2 = b.ToWorldSpace(v);</syntaxhighlight>

----

===Enemy Territory Addendum===

====ChangePrimaryWeapon====
Selects a new primary weapon for the bot. Should take effect next spawn. You must not use this function inside map scripts. You should use [[Utility_Functions#WeaponTable.SetWeaponAvailability|SetWeaponAvailability]] if you want to disable some weapons.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangePrimaryWeapon(WEAPON.PANZERFAUST);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangeSecondaryWeapon| ChangeSecondaryWeapon]]
----

====ChangeSecondaryWeapon====
Selects a new secondary weapon for the bot. Should take effect next spawn.

'''Parameters:''' (weaponId)

'''Returns:''' true if successful, false if not

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSecondaryWeapon(WEAPON.LUGER);</syntaxhighlight>

'''See Also:'''
[[Bot#ChangePrimaryWeapon| ChangePrimaryWeapon]]
----

====ChangeSpawnPoint====
Changes the desired spawn point for the bot to respawn at.

'''Parameters:''' (spawnpoint #)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
b.ChangeSpawnPoint(2); </syntaxhighlight>

----

====GetConstructableState====
Check state of a BUILD goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can build the entity, 0 if the entity is already built, -1 if the entity is not constructable or has been built by enemy.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetConstructableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetCursorHint====
When a player is near enough something to get a hint icon, such as for dynamiting, this function can access what hint is showing. Some of these hints may or may not ever show up, they were taken as-is from the ET SDK.

* NONE - 0
* PLAYER - 1
* ACTIVATE - 2
* DOOR - 3
* DOOR_ROTATING - 4
* DOOR_LOCKED - 5
* DOOR_ROTATING_LOCKED - 6
* MG42 - 7
* BREAKABLE - 8
* BREAKABLE_DYNAMITE - 9
* CHAIR - 10
* ALARM - 11
* HEALTH - 12
* TREASURE - 13
* KNIFE - 14
* LADDER - 15
* BUTTON - 16
* WATER - 17
* CAUTION - 18
* DANGER - 19
* SECRET - 20
* QUESTION - 21
* EXCLAMATION - 22
* CLIPBOARD - 23
* WEAPON - 24
* AMMO - 25
* ARMOR - 26
* POWERUP - 27
* HOLDABLE - 28
* INVENTORY - 29
* SCENARIC - 30
* EXIT - 31
* NOEXIT - 32
* PLYR_FRIEND - 33
* PLYR_NEUTRAL - 34
* PLYR_ENEMY - 35
* PLYR_UNKNOWN - 36
* BUILD - 37
* DISARM - 38
* REVIVE - 39
* DYNAMITE - 40
* CONSTRUCTIBLE - 41
* UNIFORM - 42
* LANDMINE - 43
* TANK - 44
* SATCHELCHARGE - 45
* LOCKPICK - 46

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
hint = table();
b.GetCursorHint(hint);

print(hint.type); // one of the values above
print(hint.value); // usually a health associated with certain types </syntaxhighlight>
----

====GetDestroyableState====
Check state of a PLANT goal.

'''Parameters:''' (entity)

'''Returns:''' 1 if the bot can destroy the entity, -1 if the entity is not destroyable or is friendly objective.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetDestroyableState(TargetEntity) < 1 ) {
}</syntaxhighlight>

----

====GetExplosiveState====
Check state of a dynamite, landmine or tripmine.

'''Note:''' It does not work for a poison mine and bouncing betty in Jaymod.

'''Parameters:''' (entity)

'''Returns:''' 1 if the dynamite/mine can be armed, 0 if the dynamite is ticking or the mine is activated.

'''Example:''' <syntaxhighlight lang="java">
if(b.GetExplosiveState(TargetEntity) == 1 ) {
}</syntaxhighlight>

----

====GetMG42Info====
Gets information about currently mounted MG42 - vector CenterFacing and angles MinHorizontal, MaxHorizontal, MinVertical, MaxVertical.

'''Parameters:''' (table)

'''Returns:''' true if info has been stored into table

----

====GetMountedPlayerOnMG42====
Gets player who is mounting MG42.

'''Parameters:''' (mg42Entity)

'''Returns:''' player's entity or null

----

====GetReinforceTime====
Gets the current time left(in seconds) before reinforcements spawn for the bots team.

'''Parameters:''' none

'''Returns:''' seconds left till reinforcements spawn

'''Example:''' <syntaxhighlight lang="java">
if(b.GetReinforceTime() < 2)
{
// 2 seconds to reinforcements
}</syntaxhighlight>

----

====GetSkills====
Gets the current skill values and puts them into the table parameter.

'''Parameters:''' (table)

'''Returns:''' none

'''Example:''' <syntaxhighlight lang="java">
skills = table();
b.GetSkills(skills);
print("Battle Sense:", skills[SKILL.BATTLE_SENSE]);
print("Engineering:", skills[SKILL.ENGINEERING]);
print("First Aid:", skills[SKILL.FIRST_AID]);
print("Signals:", skills[SKILL.SIGNALS]);
print("Light Weapons:", skills[SKILL.LIGHT_WEAPONS]);
print("Heavy Weapons:", skills[SKILL.HEAVY_WEAPONS]);
print("Coverops:", skills[SKILL.COVERTOPS]); </syntaxhighlight>

'''See Also:''' [[SKILL]]
----
====GetStat====
Gets a current stat from the bot by name. Valid stat names for ET are kills, deaths and xp.

'''Parameters:''' (string) the stat name

'''Returns:''' the value of the stat

'''Example:''' <syntaxhighlight lang="java">
xp = b.GetStat("xp");
print("Bot xp value is",xp);</syntaxhighlight>

----

====IsMG42Repairable====

'''Parameters:''' (mg42Entity)

'''Returns:''' true if mg42 is damaged and can be repaired

----
====TeamLandminesAvailable====

'''Parameters:''' none

'''Returns:''' remaining count of team landmines

----