Utility Functions

Omni-Bot_Map_Scripting

Utility Functions

Util

Util.AddUsePoint

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

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

  syntax: Util.AddUseWp(goalname, <waypointname or table>);
  example: Util.AddUseWp( "somegoalname", "somewaypointname" );

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

  syntax: Util.AliveCount( team, class );
  example: Util.AliveCount( TEAM.AXIS, CLASS.MEDIC );

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

Util.BotChat

  syntax: Util.BotChat(Team, msgType, Msg, NumBots);
  example: Util.BotChat(TEAM.ALLIES, "vsay", VOICE.G_CHEER, 2);

See Talking_bots page

Util.BotHasAnyRole

  syntax: Util.BotHasAnyRole(bot);
  example: if ( Util.BotHasAnyRole(bot) ) {

returns true if bot has any role.

see also: Roles Page

Util.CanBotSnipe

  syntax: Util.CanBotSnipe(bot);
  example: if ( Util.CanBotSnipe(bot) ) {

returns true if bot has a sniper weapon.

Util.CappointForFlag

  syntax: Util.CappointForFlag( flag_goalname, cappoint_goalname );
  example: Util.CappointForFlag( "FLAG_axis_gold", "CAPPOINT_Truck" );

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

  syntax: Util.ChangeCrucialClassForRole ( team, role, class );
  example: Util.ChangeCrucialClassForRole(TEAM.AXIS, ROLE.DEFENDER1, CLASS.COVERTOPS);

Sets new crucialClass in the Map.Roles table.

Util.ChangeSpawn

This function is deprecated. See Changing spawns.

Util.ChangeSpawnForRole

  syntax: Util.ChangeSpawnForRole( <team>, <role>, <spawnpoint> );
  example: Util.ChangeSpawnForRole(TEAM.ALLIES, ROLE.ATTACKER, 1);

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

see also: Roles Page

Util.ChangeToSniperWeapons

  syntax: Util.ChangeToSniperWeapons( bot, <optional viewDistance> );
  example: Util.ChangeToSniperWeapons(bot);

called from OnBotJoin on sniper maps.

see also: Sniper_and_Panzer_maps

Util.ClearRoleForGoals

This function is deprecated. Use ClearGoalRole

Util.ClearRoleForGroup

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

used to remove roles from a given group of goals

see also: Roles Page

Util.ClearRoleForTable

  syntax: Util.ClearRoleForTable( tbl, <role or table> );
  example: Util.ClearRoleForTable( someTable, ROLE.DEFENDER );

used to remove roles from a given table of goals

see also: Roles Page

Util.DisableGoal

  syntax: Util.DisableGoal(goalname, <optional true>);
  example: Util.DisableGoal("FLAG_someflag");

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

Util.DisableGroup

  syntax: Util.DisableGroup(groupname, team);
  example: Util.DisableGroup( "somegroupname", TEAM.ALLIES );

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

Util.EnableGoal

  syntax: Util.EnableGoal(goalname);
  example: Util.EnableGoal("FLAG_someflag");

enables the goal for both teams.

Util.EnableGroup

  syntax: Util.EnableGroup(groupname, team);
  example: Util.EnableGroup( "somegroupname", TEAM.SOMETEAM );

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

Util.ExcludeClass

  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 );

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

Util.ForceRouting

  syntax: Util.ForceRouting(goalName, true/false);
  example: Util.ForceRouting( "BUILD_Tank", true );

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

  syntax: Util.GetEntHealth(entity);
  example: health = Util.GetEntHealth(this.TargetEntity);

returns entity health.

Util.GetGroup

  syntax: Util.GetGroup(groupname);
  example: Util.GetGroup("somegroupname");

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

Util.GetRandomFromTable

  syntax: Util.GetRandomFromTable( tbl );
  example: index = Util.GetRandomFromTable( someTable );

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

  syntax: Util.GetRandomTableValue( tbl );
  example: value = Util.GetRandomTableValue( someTable );

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

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

returns table of map goals that match a regular expression.

Util.IgnoreTargetGoal

  syntax:Util.IgnoreTargetGoal( bot, goalname, time );
  example: Util.IgnoreTargetGoal( bot, "MOVER_bird1" );
  example: Util.IgnoreTargetGoal( bot, "MOVER_bird1", 9999 );

used to stop bots shooting at game entities such as movers, Normally added in OnBotJoin

Util.IgnoreTargetGoalTable

  syntax: Util.IgnoreTargetGoalTable(bot, <table name>);
  example: Util.IgnoreTargetGoalTable(bot, Map.Movers);

used to stop bots shooting at game entities listed in a map table, Normally added in OnBotJoin

Util.IsBot

  syntax: Util.IsBot(entity);
  example: bot = Util.IsBot(ent);

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

  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

used to limit specific goals to a specific class or classes

Util.LimitToTeam

  syntax: Util.LimitToTeam(team, goal);
  example: Util.LimitToTeam(TEAM.AXIS, "SWITCH_gate_depot");

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

Util.MapDebugPrint

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

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

see also: Debugging_tips

Util.OnTriggerPosition

  syntax: Util.OnTriggerPosition( goalname, wpname or position, tolerance, wpfunction );
  example: Util.OnTriggerPosition( "MOVER_train1", "depotyard", 200.0, Map.tug_depotyard );

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

  syntax: Util.RemoveGoal( goalnames );
  example: Util.RemoveGoal( "MOVER_truck" );

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

  syntax: Util.Routes( <table> );
  example: Util.Routes(MapRoutes);

initializes routes

see also: Routing

Util.SetGoalOffset

  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" );

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

  syntax: Util.SetGoalPosition( x, y, z, GoalName );
  example: Util.SetGoalPosition( 4534, 2168, -199, "BUILD_construct" )

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

  syntax: Util.SetGoalRange( goalNames, distance );
  example: Util.SetGoalRange("GRENADE_tower.*", 800);

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

  syntax: Util.SetGroup(goalname, groupname);
  example: Util.SetGroup("somegoalname", "somegroupname");

this function will add a given goal to a given groupname

Util.SetGroupForTable

  syntax: Util.SetGroupForTable( tbl, group );
  example: Util.SetGroupForTable( someTable, "myGroup" );

add each goal in the given table of goals to the given group.

Util.SetMaxUsers

  syntax: Util.SetMaxUsers( botnum, goal );
  example: Util.SetMaxUsers( 1, "ATTACK_.*" );

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

Util.SetMaxUsersInProgress

  syntax: Util.SetMaxUsersInProgress( Users, GoalNames );
  example: Util.SetMaxUsersInProgress( 15, "CHECKPOINT.*" );

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

Util.SetMaxUsersInUse

  syntax: Util.SetMaxUsersInUse( Users, GoalNames );
  example: Util.SetMaxUsersInUse( 1, "MOUNT_.*" );

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

Util.SetPercentInProgress

  syntax: Util.SetPercentInProgress(%, goal);
  example: Util.SetPercentInProgress(70, "FLAG_docs");

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

  syntax: Util.SetPositionGoal( goalname1, goalname2 );
  example: Util.SetPositionGoal( "BUILD_Tank", "MOVER_tank" );

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 SetGoalRole

Util.SetRoleForGroup

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

sets the given roles for the given group of goals.

Util.SetRoleForTable

  syntax: Util.SetRoleForTable( <goal table>, <role or table> );
  example: Util.SetRoleForTable( someTable, ROLE.DEFENDER );

sets the given roles for the given table of goals.

see also: Roles Page

Util.ShowGroup

  syntax: Util.ShowGroup(groupname);
  example: Util.ShowGroup("somegroupname");

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

Util.UpdateSwitchData

  syntax: Util.UpdateSwitchData();

this function must be called from OnMapLoad if Map.Switches is defined.

see also: Paththrough UseSwitch

Util.WpNameInfo

  syntax: Util.WpNameInfo(waypointName);
  example: wpInfo = Util.WpNameInfo("rNadeHall");

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

  syntax: ETUtil.ChangeToPanzer( bot );

called from OnBotJoin on panzer maps.

see also: Sniper_and_Panzer_maps

ETUtil.CountClass

  syntax: ETUtil.CountClass( team, class );
  example: ETUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER );

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

ETUtil.GetTimeElapsed

  syntax: ETUtil.GetTimeElapsed();

returns time since map start.

ETUtil.IsTeamClassDead

  syntax: ETUtil.IsTeamClassDead( team, class );
  example: ETUtil.IsTeamClassDead( TEAM.AXIS, CLASS.MEDIC );

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

ETUtil.IsTeamDead

  syntax: ETUtil.IsTeamDead( team );
  example: ETUtil.IsTeamDead( TEAM.AXIS );

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

ETUtil.LosingChat

  syntax: ETUtil.LosingChat(team);
  example: ETUtil.LosingChat( TEAM.AXIS );

See Talking_bots page

ETUtil.SelectWeapon

  syntax: ETUtil.SelectWeapon(bot, weapon);
  example: ETUtil.SelectWeapon(bot, WEAPON.PANZERFAUST);

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

ETUtil.SetAimModeForMount

  syntax: ETUtil.SetAimModeForMount(goalName, aimType);
  example: ETUtil.SetAimModeForMount("MOUNT_ship", Vec3(-340, 1530, 90));

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

ETUtil.SetCabinets

  syntax: ETUtil.SetCabinets();

disables health & ammo cabinets for Medic & FieldOp Classes

ETUtil.SetExcludeIndexes

  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

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

ETUtil.SetStartIndex

  syntax: ETUtil.SetStartIndex(goal, offset);
  example: ETUtil.SetStartIndex("ESCORT_tank", 2); // Use Offset 2
  example: ETUtil.SetStartIndex("ESCORT_tank", -1); // Random

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

  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

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

  syntax: ETUtil.SwitchWeapon(weapon);
  example: ETUtil.SwitchWeapon(WEAPON.PANZERFAUST); //all soldiers will switch to panzer

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

ETUtil.WinningChat

  syntax: ETUtil.WinningChat(Team);
  example: ETUtil.WinningChat( TEAM.ALLIES );

See Talking_bots page

RTCWUtil

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

RTCWUtil.BotDisableCombatCrouch

  syntax: RTCWUtil.BotDisableCombatCrouch( bot, bool enable );
  example: RTCWUtil.BotDisableCombatCrouch( bot, true );

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

  syntax: RTCWUtil.ClearMainGoals();

This function will deactivate all main goals for both teams.

  goals deactivated: PLANT MOUNTMG42 MOVER CHECKPOINT FLAG

RTCWUtil.ClearSecondaryGoals

  syntax: RTCWUtil.ClearSecondaryGoals();

 This function will deactivate all secondary goals for both teams.
 
 goals deactivated: ARTILLERY REPAIR

RTCWUtil.CountClass

  syntax: RTCWUtil.CountClass( team, class );
  example: RTCWUtil.CountClass( TEAM.ALLIES, CLASS.ENGINEER );

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

RTCWUtil.CountTeam

  syntax: RTCWUtil.DisableGoal(goalname, <optional true>);
  example: RTCWUtil.DisableGoal("FLAG_someflag");

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

RTCWUtil.IsPlantGoalAvailable

  syntax: RTCWUtil.IsPlantGoalAvailable();
  example: RTCWUtil.IsPlantGoalAvailable();

returns true if there is a plant goal available

RTCWUtil.IsTeamClassDead

  syntax: RTCWUtil.IsTeamClassDead( team, class );
  example: RTCWUtil.IsTeamClassDead( TEAM.AXIS, CLASS.ENGINEER )

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

RTCWUtil.IsTeamDead

  syntax: RTCWUtil.IsTeamDead( team, minbots );
  example: RTCWUtil.IsTeamDead( TEAM.AXIS, 2 );

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

  syntax: RTCWUtil.KillEntities( table or int );
  example: RTCWUtil.KillEntities( 123 );
  example: RTCWUtil.KillEntities( {123, 124} );

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

RTCWUtil.NoSnipe

  syntax: syntax: RTCWUtil.NoSnipe(bot);

soldier bots will not choose a mauser when selecting a weapon

note: this is typically called in OnBotJoin

RTCWUtil.SelectSoldierWeapons

  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

RTCWUtil.SelectWeapon

  syntax: RTCWUtil.SelectWeapon(bot, weapon, isFog);
  example: RTCWUtil.SelectWeapon(bot, WEAPON.MAUSER);

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

  syntax: RTCWUtil.SetPrimaryGoals(priority);

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

  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

RTCWUtil.SetTeamSuicide

  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

RTCWUtil.StopSniping

  syntax: RTCWUtil.StopSniping();

all bots currently using a sniper weapon will switch to a different weapon

note: this is typically called inside trigger functions

RTCWUtil.SwitchSoldierWeapons

  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

RTCWUtil.SwitchWeapon

  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

RTCWUtil.TeamDisableCombatCrouch

  syntax: RTCWUtil.TeamDisableCombatCrouch( team );
  example: RTCWUtil.TeamDisableCombatCrouch( TEAM.AXIS );

disables combat crouching for the given team

RTCWUtil.ToggleFlag

  syntax: RTCWUtil.ToggleFlag( goal, time in seconds );
  example: thread(RTCWUtil.ToggleFlag, "CHECKPOINT.someFlag", 300);

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

  syntax: WeaponTable.ListWeaponAvailability();

prints current availability of all weapons

WeaponTable.SetWeaponAvailability

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

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

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

enables or disables weapon for team and class.

WeaponTable.Shotgun

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