ABL Orders List
ABL is a finite state machine (FSM). This means that the code in any script is organized into states. Each time the game goes through a script, it only goes through the current, active state. The following is a list of all functions and commands that can be added to an ABL script in MechWarrior 4: Vengeance. Take note that most of the ABL orders only work in single player games, and a set group of orders is passed from server to client. (Multiplayer orders are listed at the end of this document). 

FSM Functions
Variable Types
Prefixes
Notes on Syntax
Parameter Shortcuts
Built-in Functions
MW4 Constants
Gets
Sets
Orders
Conditionals (Expressions)
Group/Team Functions
Timer Functions
Objective Functions
Audio Functions
Miscellaneous Functions
Degugging Functions
In-game Cinema Related Functions
Multiplayer Support and Buckets

Variable types

Variables are symbols that represent a stored value. Below are valid type definitions for FSM variables:

integer: A basic integer, whole numbers
real: A basic floating-point number
Boolean: A Boolean that can be true or false
char: A single character
ObjectID: A reference to an object in the world
LocPoint: A location in the world (3D point)
TimerID: A reference to a timer in the mission 0-31 only
CameraID: A reference to a camera
PlayerID: A reference to a player

Prefixes

The following prefixes are automatically added to all items placed in the editor. EX: You drop a vehicle and name it “MainTank”. In all scripts it will actually be called “eve_maintank”. ALL objects dropped in the editor come with a prefix.

eve_: Vehicles/’Mechs
ebu_: Buildings
eso_: Sounds
epa_: Paths
ena_: Nav points
eob_: Objectives
epl_: Players
edr_: Drop zones
ede_: Default/other
eai_: A.I.s
etu_: Turrets

Notes on Syntax

ABL has two different ways of checking for a TRUE response, and two ways of checking for a false response. For example, the ABL Command isdead(getplayervehicle(epl_player0)) will return true if the player in a single-player mission has died. The different ways to check for true and false are as follows:

TRUE

If (isdead(getplayervehicle(epl_player0))) then
If (isdead(getplayervehicle(epl_player0)) == TRUE) then

FALSE

If (not isdead(getplayervehicle(epl_player0))) then
If (isdead(getplayervehicle(epl_player0)) == FALSE) then

This document uses all four methods in its example usage.
Parameter shortcuts
The following shortcuts are used in the parameter lists to represent a larger collection of valid parameter types.

any: Represents any type of parameter
num: Either an integer or a real
string: An array of char’s
id: An ObjectID

Note ABL is not case sensitive, so capitalization does not matter for function names.
Buil-in Functions
return (any): The parameter value is the return value for the function (only used in a function)
integer concat (string, any): Parameter value is added onto the end of the string (if a variable then it is the value of that variable)
num abs (num): Returns the absolute value of the parameter
integer random (integer): Returns a random number from 0-parameter
integer round (real): Rounds the real parameter to the nearest integer
real sqrt (num): Returns the square root of the parameter
integer trunc (num): Truncates the parameter and return the integer. 1.9 truncs to 1
setmaxloops (integer): Sets the maximum number of loops that will occur in a looping construct before abl will error out with an infinite loop run-time error
fatal (integer, string): Halts the script in the debugger with the string message if debugger is present; if no debugger is present, halts the whole game with the string message
assert (Boolean, integer, string): Same as the fatal call, but only if the Boolean is false
MechWarrior4 Constants

ME: Specifies the object ID of the unit currently executing. Only usable in unit brains

NO_UNIT: A special ObjectID that specifies no unit (or an invalid unit). This is usually provided as a return value from a function; you generally should not pass it in to a function as an ObjectID unless the function specifically states that you may do so.

All other constants are listed under the specific commands that use them.
Gets
The following functions are used for getting a variety of variables, properties, and parameters.

GetPlayerVehicle:

Determines what vehicle a specific player is driving in a mission

Format: GetPlayerVehicle(who)

Who = ObjectID of a player in the game. Valid player constants are from epl_player0 – epl_player15. epl_player0 is the player in any single player mission.

Returns: ObjectID of the unit being driven by the player specified in the command

Example usage: UnitDriven == GetPlayerVehicle(epl_player0);

GetTarget:

Determines the target of the specified object

Format: GetTarget(who)

Who = ObjectID for any object with an attached ai in the game. The “who” parameter must not be a team or group.

Returns: The ObjectID of the target for the object “who”

Example usage: if ((gettarget(joe)) = (gettarget(tom))) then

WhoShot:

Determines who shot the specified target

Format: Whoshot(who)

Who = ObjectID for any object in the game; “who” may be a team or a group

Returns: ObjectID of who last shot the object indicated by “who” (if it was shot within the last 5 seconds). If the specified object has not been shot in the last 5 seconds, then no_unit will be returned.

Example usage: if ((whoshot(me)) = eve_Atlas1) then

GetNearestEnemy:

Determines which enemy unit is closest to the specified unit

Format: GetNearestEnemy(who)

Who = ObjectID for any object in the game that has an alignment; “who” may be a team or group

Returns: ObjectID of the nearest enemy to the object indicated by the “who” parameter

Example usage: Mytarget == getnearestenemy(me);

FindObject:

Searches for objects

Format: FindObject(who,alignment,type,criteria,flags,distance)

Who = The object being searched from; this may be a team or group

Alignment = alignment to search for. Alignment checked is in relation to the who parameter, including these options:
	FA_FRIENDLY
	FA_ENEMY
	FA_NEUTRAL	
	FA_ANY

Type = what type of object to look for, including these options: 
	FT_MECH = all ‘Mechs
	FT_AIRPLANE = all armed airplanes
	FT_BOAT = all armed boats
	FT_TURRET = all turrets
	FT_VEHICLE = all armed vehicles not included in the above categories
	FT_DEFAULT = all of the above at once
FT_BUILDING = all buildings with PLAYER or ENEMY alignment (neutral buildings are always ignored)
FT_UNARMED = all unarmed units

Criteria = what search criteria to use, including these options: 
FC_BEST_TARGET = Find the best target (considers distance, tonnage, current damage, and what weapons the unit carries)
	FC_GREATEST_THREAT = find the greatest threat
	FC_LEAST_THREAT = find the least threat
	FC_MOST_DAMAGED = find the most damaged object	
	FC_NEAREST = find the nearest object

Flags = Flags that can be used as modifiers to the other criteria, including these options:
FF_WHO_SHOT = if specified and someone shot player, return that object, overriding anything else
FF_SEEPLAYER = if specified, we can also see the player if within fog radius and if we're facing toward him
FF_LOOK_EVERYWHERE = if specified, we look through every potential enemy in the whole mission (Note: THIS CAN BE VERY EXPENSIVE!!! Use only on small, limited maps!)

Distance = What distance to search for (integer)

Returns: The ObjectID of the selected object

Example usage: Mytarget = FindObject (me, FA_ENEMY, FT_DEFAULT, FC_BEST_TARGET, FF_WHO_SHOT, 800);

FindObjectExcept:

Identical to FindObject (see above), except that it takes an additional parameter (“except”). This is an ObjectID that indicates an object that should be excluded from the search (i.e., ignored).

Format: FindObjectExcept(who,alignment,type,criteria,flags,distance,except)

Returns: The ObjectID of the selected object

Example usage : Mytarget = FindObject (me, FA_ENEMY, FT_DEFAULT, FC_BEST_TARGET, FF_WHO_SHOT, 800, EVE_APC1);

FindEnemy:

Searches for a specific opponent type to shoot, then loads it as the current target (FindEnemy can only be placed inside a unit brain and cannot be used from inside a mission script)

Format: FindEnemy(searchrange, type)

Searchrange = The range for the search (from the unit executing the command)

Type = What type of object to look for, including these options:
	FT_MECH = All ‘Mechs
	FT_AIRPLANE = All armed airplanes
	FT_BOAT = All armed boats
	FT_TURRET = all turrets
	FT_VEHICLE = All armed vehicles that are not included in the above categories
	FT_DEFAULT = ALL of the above categories at once

Returns: True if a target has been set (a target has been set if an enemy unit is detected inside the searchrange, or if the unit has been shot by an opponent)

Example usage: if ((findenemy(500,FT_default)) == true) then

SetMyTarget:

A specific search function that looks for an opponent to shoot and then loads it as the current target. SetMyTarget can only be placed inside a unit brain and cannot be used from inside a mission script.

Format: SetMyTarget(searchrange)

Searchrange = The range for the search (from the unit executing the command).

Returns: True if a target has been set. A target has been set if an enemy unit is detected inside the searchrange or if the unit has been shot by an opponent.

Example usage: SetMyTarget(650);

LeaveAttackState:

Determines if the unit should stop attacking its current target

Format: LeaveAttackState(WithdrawRange)

WithdrawRange = The range from the unit whereupon the unit should break off combat

Returns: True if any of the following parameters apply:
	1: The unit’s target is outside the withdrawrange and has not shot the target within the last 5 seconds
	2: The unit’s target is dead
	3: The unit has no valid target

Example usage: if (leaveattackstate(800)) then

GetLocation:

Finds the current location of a specific object

Format: GetLocation(who,point)

Who = ObjectID of an object in the game.
Point = A three-integer array used to hold the location of the object who. The location of the object “who” is loaded into the point array.

Returns: Location of the object. Location is loaded into the “point” variable.

Example usage: GetLocation(me,mystart);

GetNearestPathPoint:

Finds the closest point on a path from a specific object

Format: GetNearestPathPoint (who, path, point)

Who = the object being searched from
Path = the path being searched to
Point = the point found by the function

Returns: Nearest path point to the specified object on the specified path

Example usage: GetNearestPathPoint(me, epa_path1,wheretogo);

GetAlignment:

Finds the alignment of the specified object

Format: GetAlignment(who);

Who = A specific object. Who may be a team or group.

Returns: The alignment of the specified object. Possibilities are…
	FA_FRIENDLY
	FA_ENEMY
	FA_NEUTRAL	

Example usage: if ((getalignment(mytarget)) = FA_FRIENDLY) then

GetGunnerySkill:

Finds the gunnery skill of the specified object

Format: GetGunnerySkill(who);

Who = A specific object. Who may not be a team or group.

Returns: The gunnery skill of the specified object

Example usage: enemygunnery = GetGunnerySkill (mytarget);

GetPilotSkill:

Finds the pilot skill of the specified object

Format: GetPilotSkill(who);

Who = A specific object. Who may not be a team or group.

Returns: The Pilot skill of the specified object

Example usage: enemyPilot = GetPilotSkill (mytarget);

GetAttackThrottle:

Finds the AttackThrottle of the specified object

Format: GetAttackThrottle(who);

Who = a specific object. Who may not be a team or group

Returns: The Attack Throttle setting of the specified object

Example usage: enemyAttackThrottle = GetAttackThrottle (mytarget);

GetEliteLevel:

Finds the EliteLevel of the specified object

Format: GetEliteLevel(who);

Who = a specific object. Who may not be a team or group.

Returns: The elite level setting of the specified object

Example Usage: enemyEliteLevel = GetEliteLevel (mytarget);

GetMemoryInteger:

Finds the value of one of the loaded memory integer cells of the specified object. Each object in the game ahs ten memory locations that can be loaded with a number and used to differentiate between multiple units that have the same script.

Format: GetMemoryInteger(who,index)

Who = The unit being checked

Index = which memory cell to check. The 10 memory cells are numbered 0 through 9.

Returns: The value of the memory cell

Example usage:

	switch (getmemoryinteger(me,9))

	case 1:
		//AlphaMechs
		attackrange = 650;
		path = epa_Alphapath;
	endcase;
						
	case 2:
		//BetaMechs
		attackrange = 700;
		mytactic = tactic_circle;
		path = epa_Betapath;
	endcase;
	
	endswitch;

GetDifficulty:

Checks the difficulty level for a specific mission

Format: GetDifficulty

Note: This command has no parameters

Returns: the difficulty level. Possibilities include the following:

	EASY_DIFFICULTY
	MEDIUM_DIFFICULTY
	HARD_DIFFICULTY
	IMPOSSIBLE_DIFFICULTY

Example usage: If (getdifficulty == EASY_DIFFICULTY) then

GetTeamNumber:

Finds what team a specified object in a multiplayer mission is on

Format: GetTeamNumber(who)

Who = The object being checked. Who cannot be a team or group.

Returns: What team the unit is on. Team numbers are 0 – 7. If the unit is not on a team, then a value of 8 will be returned.

Example usage: If ((Getteamnumber(EVE_unit_3)) == 6) then

WhoDestroyed:

Finds the unit that destroyed a specific object in game.

Format: WhoDestroyed(who)

Who = A specific object in game. Who can not be a team or group.

Returns: The ObjectID of the unit that destroyed the specified object. if “who” is still alive or if its destroyer cannot be identified then NO_UNIT is returned.

Example usage: if (getteamnumber((Whodestroyed(me))) == (getteamnumber(me))) then

GetLancemate:

Finds the ObjectID of a specific lancemate

Format: GetLancemate(index)

Index = The index of the lancemate in the group. The player himself is always the 0th element, and additional lancemates are at indices 1, 2, 3.

Returns: ObjectID of the specified lancemate. This function will return NO_UNIT if the unit does not exist.

Example usage: MyLancemate = GetLancemate(1);

GetMechType:

Checks what ‘Mech chassis type a specific unit has.

Format: GetMechType(who)

Who = ObjectID of the unit being checked. Who may not be a team or group.

Returns: Mech type. The different ‘Mech types are listed below. NoMechID is returned if the unit is not a ‘Mech or was not found.

	M_Argus
	M_Atlas
	M_Awesome
	M_Bushwacker
	M_Catapult
	M_Chimera
	M_Cougar
	M_Daishi
	M_Hellspawn
	M_Loki	
	M_Madcat
	M_Madcat_MKII
	M_Mauler
	M_Novacat
	M_Osiris
	M_Raven
	M_Shadowcat
	M_Thanatos
	M_Thor	
	M_Uziel
	M_Vulture
	NoMechID

Example usage:

	If ((getmechtype(epl_player1)) == M_Daishi) then
		Print(“Wimp!”);
	Endif;

GetViewMode:

Checks the user’s current camera viewing mode (Inside ‘Mech, directly behind, behind right or behind left) for a player controlled ‘Mech.

Format GetViewMode(who)

Who = The player being checked. The unit being checked MUST be a player.

Returns: The view mode for that player. Possible returns include the following:

	VIEW_OUTSIDE_CENTER
	VIEW_OUTSIDE_RIGHT
	VIEW_OUTSIDE_LEFT	
	VIEW_IN_MECH

Example Usage: if (Getviewmode(GetPlayerVehicle(epl_player0)) == VIEW_IN_MECH) then
Sets
The following functions are used for setting a variety of variables, properties, and parameters.

SetAlignment:

Sets the alignment of a specific unit or group of units

Format: SetAlignment(who,alignment)

Who = The unit to have it’s alignment changed. Who may be a team or group.
Alignment = The new alignment for the specified unit(s). Possible alignments include the following:

	FA_FRIENDLY
	FA_ENEMY
	FA_NEUTRAL	
	FA_ANY

Returns: Nothing

Example usage: if (iswithin(me,playermech,120)) then setalignment(me,FA_FRIENDLY);
endif;

SetAttackThrottle:

Sets the attack throttle on the specified unit(s). This is how fast the unit moves in combat, stated as a percentage of the unit’s maximum speed. The higher this number, the more deadly the unit will be in combat.

Format: SetAttackThrottle(who,throttle)

Who = The unit(s) to have their throttle changed. Who may be a team or group.

Throttle = The new attack throttle setting

Returns: Nothing

Example usage: SetAttackThrottle(me, 80);

SetCurMood:

Sets the current mood on the specified unit(s). Mood affects the tactic choice of the unit in combat. Note that mood is only important for armed and mobile units.

Format: SetCurMood(who,mood)

Who = The unit(s) to have their current mood changed. Who may be a team or group.
Mood = The new mood setting. Possible moods include the following:

  	DESPERATE_START
  	DESPERATE_END
  	DEFENSIVE_START
  	DEFENSIVE_END
  	NEUTRAL_START
  	NEUTRAL_END
  	AGRESSIVE_START
  	AGRESSIVE_END
  	BRUTAL_START
  	BRUTAL_END

Returns: nothing

Example usage: SetCurMood(me, NEUTRAL_END);

SetEntropyMood:

Sets the entropy mood on the specified unit(s). Mood affects the tactic choice of the unit in combat. Note that mood is only important for armed and mobile units. Entropy mood is the mood that the unit will slowly migrate toward should it not be in combat at the time.

Format: SetEntropyMood(who,mood)

Who = The unit(s) to have their Entropy mood changed. Who may be a team or group.

Mood = The new mood setting. Possible moods include the following:

  	DESPERATE_START
  	DESPERATE_END
  	DEFENSIVE_START
  	DEFENSIVE_END
  	NEUTRAL_START
  	NEUTRAL_END
  	AGRESSIVE_START
  	AGRESSIVE_END
  	BRUTAL_START
  	BRUTAL_END

Returns: nothing

Example usage: SetEntropyMood(me, AGRESSIVE_END);

SetEliteLevel:

Sets the elite level of the specified unit(s). Elite level helps a unit with tactical choices. The higher the elite level the wider variety of options are available to the unit.

Format: SetEliteLevel(who,level)

Who = The unit(s) having their elite level changed. Who may be a team or group.
Level = The new elite level for the specified unit(s). Elite level is a range from 0 (complete rookie) to 100 (Bond, James Bond).

Returns: Nothing

Example usage: SetEliteLevel(me,80);

SetFiringDelay:

Sets the firing delay for the specified unit(s). This operates on a per-weapon basis and is in addition to the weapon’s existing firing delay. The exact delay is determined each time the weapon fires. Example: Suppose you have two weapons with recharge times of 3 and 5 seconds, respectively, and you call SetFiringDelay(ME,2.0,4.0). The weapons will then take 5-7 seconds and 7-9 seconds to fire again, respectively, with the exact delay changing randomly between the aforementioned values each time they are fired. This is designed to simulate the time it takes for a person to aim and decide to fire their weapons. The lower these numbers, the more dangerous the unit is in combat.

Format: SetFiringDelay(who,min,max)

Who = ObjectID for the unit(s) to have their delay numbers changed. Who may be a team or group.

Min = Minimum delay (this is in seconds and is a real number)

Max = Maximum delay (his is in seconds and is a real number)

Returns: nothing

Example usage: SetFiringDelay(me,1.0,2.5);

SetIgnoreFriendlyFire:

Decides whether the unit(s) will ignore friendly fire or not when choosing targets. If “ignore” is true, the object will ignore such accidents in combat. Otherwise, it will ignore the alignment of the shooter when it is shot. “False” is the default for all units.

Format: SetIgnoreFriendlyFire(who,ignore)

Who = The unit(s) to have their ignore variable set. Who may be a team or group.

Ignore = A Boolean variable setting whether the specified unit(s) ignore friendly fire or not. If set to true then the specified unit(s) will not select a friendly unit that has shot them as a target. If set to false, they are allowed to do this.

Returns: nothing

Example usage: SetIgnoreFriendlyFire(me,true);

SetIsShotRadius:

Sets the radius inside of which the specified unit(2) will consider themselves to be shot should an enemy weapon hit or pass inside of said radius. Default radius is 80 meters. If the distance is set to 120 meters for a specific unit, then the unit will return true for the IsShot command if any enemy shot comes within 120 meters of it.

Format: SetIsShotRadius(who,meters)

Who = The units having there IsShot radius set. This may be a team or group.
Meters = The new IsShot radius (integer)

Returns: Nothing

Example usage: SetIsShotRadius(me,140);

SetMemoryInteger:

Stores a value in a unit’s memory cells

Format: SetMemoryInteger(who,index,value)

Who = The unit having it’s memory cells set. The unit may not be a team or group.
Index = The memory cell being set for that unit. There are ten memory cells designated 0 – 9.
Value = The new value for the specified memory cell.

Returns: Nothing

Example: SetMemoryInteger(me,5,230);

SetSkillLevel:

Sets piloting, gunnery, and elite levels for a specific or group of units

Format: SetSkillLevel(who,pilot,gunnery,elite)

Who = the unit(s) having skill levels changed. Who may be a team or group.
Pilot = The new piloting skill level. A value of –1 means to not change that skill.
Gunnery = The new gunnery skill level. A value of –1 means to not change that skill.
Elite = the new elite level. A value of –1 means to not change that skill.

Returns: Nothing

Example Usage: SetSkillLevel(me,50,50,-1);

SetTarget:

Sets the target for a specific unit or group of units

Format: SetTarget (who,target)

Who = The unit having its target set. This may be a team or group.

Target = The new target for the unit(s). Target cannot be set to the player, it must be set to the player’s vehicle. Target may also be a team or group; in this case, the “who” object (or each object in “who”) will set its target to the nearest object in “target.”

Returns: Nothing

Example usage: SetTarget(me,playermech);

SetTargetDesirability:

Sets a desirability value for a specific unit

Format: SetTargetDesirability(who, desirability)

Who = The unit having its target desirability set. 

Desirability = The new target desirability number. This value will be used whenever someone queries the target with a search function such as FindObject() or GetNearestEnemy(). This value will automatically override the value that the function would normally try to determine. A value of 100 indicates the target should always be chosen. A value of 0 indicates that the target should be the last one picked. [Of course, neither of these will apply if the search cannot even consider the unit – if you do a GetNearestEnemy(), it will ignore units allied to the searcher, regardless of its desirability value.] A value of -1 means that the target will never be considered in such a search, rendering it essentially invisible to anyone using such a search function.

Returns: Nothing

Example usage: SetTargetDesirability(me, -1);

SetSearchLight:

Sets a specific search light on an object to be on or off. By default, an AI unit’s search light is set such that it is on in night missions, or off in day missions.

Format: SetSearchLight(who,on)

Who = The unit having its searchlight set on or off. Who may be a team or group.

On = Whether or not the searchlight is on

Returns: Nothing

Example usage: SetSearchLight(me,true);

SetNavpoint:

Reveals a specific navpoint and sets it as the active nav point in the player’s nav system

Format: Setnavpoint(navpoint)

Navpoint = The Nav point being set

Returns: Nothing

Example usage: Setnavpoint(ena_NavAlpha);

SetCombatLeash:

Sets a leash for units to use in combat. When issued an OrderAttack(TRUE) or an OrderAttackTactic(<tactic>,TRUE), the combat AI attached to "who" will not allow it to maneuver more than "meters" meters from point "point." To remove the leash, call this function with "meters" == 0. "who" may optionally be a team or group.

Format: SetCombatLeash(who, point, meters)

Who = The unit(s) having their leash set. Who may be a team or group.

Point = The locpoint for the center point of the leash

Meters = The distance from point that the designated units are allowed to wander during combat

Returns: Nothing

Example usage: SetcombatLeash(me,Locpoint1,600);

SetGuiTarget:

Sets the GUI target in the targeting reticle of a specific player

Format: SetGUITarget(Src,Target)

Src = The player-controlled vehicle that will have its target set
Target = The unit being targeted

Returns: Nothing

Example Usage: SetGUITarget (GetPlayerVehicle(epl_player0),some_enemy);

EnablePerWeaponRayCasting:

Turns per-weapon ray-casting on and off for a specific unit. By default, per-weapon ray-casting is disabled for all units.  The per-weapon ray-casting is an extra step during weapon firing where we make absolutely sure each weapon we fire hits or misses according to our gunnery roll (which still doesn't provide 100 provide certainty, but it does get us much closer). This should be used only for units with a very low chance to hit (to make sure they don't accidentally hit) or a very high chance to hit (to make sure they don't accidentally miss). Note that this can potentially be expensive, especially when enabled for multiple units, so use it with caution. It is best to use it only for specific key units with very good or very poor aim—and only when within range of the player.

Format: EnablePerWeaponRayCasting(Who, Enable)

Who: The unit having per-weapon ray-casting turned on or off

Enable: A Boolean determining if per weapon ray casting is on or off

Returns: Nothing

Example usage: EnablePerWeaponRayCasting(Me, True);

SetSensorVisibility:

Sets an object's visibility on sensors (radar)

Format: SetSensorVisibility(Who,Visible)

Who = The object having sensor visibility set. Who may be a team or group.

Visible: A Boolean determining if sensor visibility is on or off. By default, all objects are visible; calling with visible==false will make the object invisible to radar.

Returns: Nothing

Example usage: SetSensorVisiblity(Eve_StealthMech, False);

SetAutoTargeting:

Turns automatic target switching on or off for a specific unit. Target-switching is on by default for all units (except lancemates given explicit attack commands). “Automatic targeting” means that any unit that has a current target and an attack order (and is perform any tactic other than "defend") may, at its discretion, select a new target during combat. It will keep the same tactic and nothing else will be affected. The decision of what target to pick is based on distance (closer enemies are more likely to be attacked) and who shot the unit most recently (shooting units makes them want to switch their target to you). There is a bias toward the current target, so all attackers being equal, the unit will not switch. Note that in order to prevent thrashing, the unit will not consider switching to a new target within 12 seconds after it has set a new target (or received its original attack order). Once enabled or disabled, the unit's auto-targeting status remains in that state until changed again via SetAutoTargeting().

Format: SetAutoTargeting(who,enabled)

Who = The unit having auto targeting set on or off. Who may be a team or group

Enabled = A Boolean determining if auto targeting is on or off. True = on. False = off.

Returns: Nothing

Example usage: SetAutoTargeting(me,false);

SetCrouchState:

Makes a unit crouch or “uncrouch”

Format: SetCrouchState(who,crouch)

Who = The unit having its crouch state set. Who may be a team or group.

Crouch = A Boolean determining if the unit is crouching or not. True = crouch, false = uncrouch. If the unit is attacking, it may decide to uncrouch on its own, depending on its current tactic. 

Returns: Nothing

Example usage: SetCrouchState(me, True);

SetViewMode:

Sets the current camera viewing mode in a single player mission

Format: SetViewMode(mode)

Mode = The view mode for the player. View modes include the following:

	VIEW_OUTSIDE_CENTER
	VIEW_OUTSIDE_RIGHT
	VIEW_OUTSIDE_LEFT	
	VIEW_IN_MECH

Returns: Nothing

Example usage: SetViewMode(VIEW_OUTSIDE_CENTER);

SetViewModeSwitchingEnabled:

Turns user-controlled view mode switching (the “v” key) on or off. It is enabled by default. This function should only be used in single player missions.

Format: SetViewModeSwitchingEnabled(enabled)

Enabled = a Boolean variable that sets view mode switching on or off. True = on. False = off.

Returns: Nothing

Example usage: Setviewmodeswitchingenabled(True);

MakeColor:

Sets a single value to a specific color so that certain able functions can use that color

Format: MakeColor(red, green, blue, alpha)

Red = The red value for the color. An integer between 0 and 255.
Green = The green value for the color. An integer between 0 and 255.
Blue = The blue value for the color. An integer between 0 and 255.
Alpha = The alpha value for the color. An integer between 0 and 255. 0 is fully transparent and 255 is fully opaque.

Returns: An integer value for the color that can be loaded into a variable

Example usage: NewColor = MakeColor(120,90,255,255);

ShowTimer:

Will show a timer on the screen. The timer can be attached to a specific ObjectiveID.

Format: ShowTimer(timer, objectiveid, timeoffset, timeonleft, color, visible)

Timer = Which timer to show the value of
ObjectiveID = Which objective to use as text with the timer, will use the appropriate text based on success, fail, and so on. If ObjectiveID is 0 then no text will be used, can also use the id of a help message.
TimeOffset = The value the current timer is subtracted from before display, the absolute value is used. Since all timers go up, you can use this to display a timer counting down. If you want a timer counting down from 60 then set this value to 60. You can play with value to get any type of strangeness you want in the time value displayed. 
Timeonleft = Whether to display the timer on the left or the right of the text. It is a Boolean. True = left, false = right.
Color = What color to draw the text and timer value in. You can use this function to create this value. We suggest 255 for the alpha to make it totally opaque.

Visible = Whether or not you want the timer visible. This is a Boolean. True = visible, false = not visible.

Returns: Nothing

Example usage: ShowTimer(gti_timer_1,Eob_killThemAll, 600, true, 255, true);
Orders
Orders are the commands issued to a unit representing a particular action (like attack, flee, and so on). 

Jump:

Tells a unit to jump for a specified number of seconds. The call will be ignored if the specified ‘Mech does not have jump jets.

Format: Jump(who,seconds)

Who = ObjectID for the unit jumping. Who must be an individual ‘Mech.

Seconds = An integer setting how many seconds the unit will fire it’s jump jets for

Returns: Nothing

Example usage: Jump(me,3);

Fall:

Causes a ‘Mech to fall forward

Format: Fall(who)

Who = ObjectID of the ‘Mech being commanded to fall. The who variable must be a ‘Mech and may not be a team or group.

Returns: Nothing

Example usage: Fall(me);

ClearMoveOrder:

Clears all move commands for a unit or group of units

Format: ClearMoveOrder(Who)

Who = The unit or units having their move orders cleared. Who may be a team or group.

Returns: Nothing

Example usage: ClearMoveOrder(me);

OrderDie:

Causes the current unit to die and stop all execution. This can only be called from inside a unit brain and only for the unit being controlled by that brain. This is the last function that will ever be called for a unit.

Format: Orderdie

Returns: Nothing

OrderMoveLookOut :

Causes the current unit to execute a lookout order—to basically just stand there and move the torso around looking for a target

Format: Ordermovelookout

OrderFormationMove:

Causes the specified group to move along a path in formation

Format: OrderFormationMove(Group, Path, Speed, type, formation, density, clear)

Group = The GroupobjectID for the group moving

Path = The path for the group to follow

Speed = The group speed in KpH. Should the speed be higher than a unit’s top speed, the unit will move at its top speed but lag behind.

Type = Patrol type. The unit can follow the path once and then stop, follow the path continually in a circle, or seesaw back and forth. Valid values for this parameter include the following:

	MOVE_NOCYCLE 
	MOVE_CIRCLE	
	MOVE_SEESAW

Formation = The shape of the formation. A unit’s placement in the formation is determined by his order in the group. Possible formations include the following:

FORMATION_2x6line
FORMATION_1x12line
FORMATION_6x2line
FORMATION_3x4line
FORMATION_3x4scout
FORMATION_11wedge
FORMATION_11flyingv
FORMATION_16wedgefill
FORMATION_16flyingVfill
FORMATION_13circlefill

Density = How dense the formation is. Valid values for this parameter include the following:
	FORMTYPE_SPARSE
	FORMTYPE_NORMAL
	FORMTYPE_DENSE

Clear = Whether or not the combatai can take over movement at the end of the path. Value is Boolean. True equals yes the combatai can take over, false equals no.

Returns: True when the path is completed by the lead vehicle. Note that this only happens if type is set to MOVE_NOCYCLE. You can keep issuing this order to check for completion.

Example usage: OrderFormationMove((groupobjectid(12)), epa_Patrolpath1, 50, MOVE_CIRCLE, FORMATION_2x6line, FORMTYPE_NORMAL, true);

OrderMoveTo:

Causes the current unit to follow the specified path. The unit will move to the first point in the path and continue along the path from there.

Format: OrderMoveTo(path,speed,type,Boolean,clear)

Path = Path ID for the path to be followed

Speed = Speed for the unit to travel in KpH. Should the speed be higher than a unit’s top speed then the unit will move at its top speed but lag behind. Negative values for speed indicate reverse.

Type = Patrol type. The unit can follow the path once and then stop, follow the path continually in a circle or seesaw back and forth. Valid values for this prameter include the following:
	MOVE_NOCYCLE 
	MOVE_CIRCLE	
	MOVE_SEESAW

Boolean = No longer used. Set to True.

Clear = Whether or not the combatai can take over movement at the end of the path. Value is Boolean. True = yes the combatai can take over, false = no.

Returns: True when the path is completed by the unit. Note that this only happens if type is set to MOVE_NOCYCLE. You can keep issuing this order to check for completion.

Example usage: OrderMoveTo(epa_BaseBackPath, 90, MOVE_SEESAW, true, true);

OrderMoveToRigid:

Behaves like OrderMoveTo above except that the unit will not leave the path. If an obstacle is in the way, the unit will simply wait for it to clear. All parameters are identical to OrderMoveTo.

OrderMoveResumePatrol:

Causes the current unit to follow the specified path. The unit will move to the nearest point in the path and continue along the path from there.

Format: OrderMoveResumePatrol(path,speed,type,Boolean,clear)

Path = Path ID for the path to be followed.
Speed = Speed for the unit to travel in KpH. Should the speed be higher than a unit’s top speed then the unit will move at its top speed but lag behind. Negative values for speed indicate reverse.

Type = Patrol type. The unit can follow the path once and then stop, follow the path continually in a circle or seesaw back and forth. Valid values for this parameter include the following:
	MOVE_NOCYCLE 
	MOVE_CIRCLE	
	MOVE_SEESAW

Boolean = No longer used. Set to true.

Clear = Whether or not the combatai can take over movement at the end of the path. Value is Boolean. True = yes the combatai can take over, false = no.

Returns: True when the path is completed by the unit. Note that this only happens if Type is set to MOVE_NOCYCLE. You can keep issuing this order to check for completion.

Example usage: OrderMoveResumePatrol(epa_BaseBackPath, 90, MOVE_SEESAW, true, true);

OrderMoveResumePatrolRigid:

Behaves just like OrderMoveResumePatrol above except that the unit will not leave the path. If an obstacle is in the way the unit will simply wait for it to clear. All parameters are identical to OrderMoveResumePatrol.

OrderMoveFlee:

Causes the current unit to flee from a specific object

Format: OrderMoveFlee(who,speed)

Who = ObjectID of the unit being fled from
Speed = The speed to flee at. Should the speed be higher than a unit’s top speed, then the unit will move at its top speed and take punishment. Negative values for speed indicate reverse.

Returns: Nothing

Example usage: OrderMoveFlee(playermech, 600);

OrderMoveFollow:

Causes the current unit to follow another unit

Format: OrderMoveFollow(who,xoffset,yoffset)

Who = ObjectID of the unit being followed

Xoffset = Distance offset from the left of the unit being followed. Positive values are to the left, negative values are to the right. Value is relative to the facing of who. Value is in meters.
Yoffset = Distance offset from in front of the unit being followed. Positive values are in front, negative values are behind. Value is relative to the facing of who. Value is in meters.

Returns: Nothing

Example usage: OrderMoveFollow(EVE_ConvoyLeader, -70, -50);

OrderMoveSit:

Causes the current unit to stop moving and sit down

Format: OrderMoveSit(shutdown)

Shutdown = Whether or not the unit should power down once it has sat down. This is a boolean. True = shut down once sitting. False = remain powered up once sitting.

Returns: Nothing

Example usage: OrderMoveSit(True);

OrderMoveToObject:

Causes the current unit to move toward a specific object

Format: OrderMoveToObject(object,speed)

Object = ObjectID of the object being approached. This can be a mobile object or even the player.

Speed = The speed to travel at in KpH. Negative values indicate travel in reverse.

Returns: True when the object has been reached. You can keep issuing OrderMoveToObject() with the same parameters after this call to check for completion of the path.

Example Usage: OrderMoveToObject(PlayerMech, 600);

OrderAttackTactic

Causes the current unit to attack its current target. The target must have been set first using the SetTarget or FindEnemy commands.

Format: OrderattackTactic(Tactic, OverrideMove)

Tactic = Which tactic to use. The different tactics are listed below.

TACTIC_PICK_BEST = Tells the combat AI to pick the best tactic. 
	TACTIC_STOP_AND_FIRE = Approach the targeted enemy to close range. Attempt to fire continuously at all times on approach and arrival.
	TACTIC_RAM = Move toward the targeted enemy at all times while firing.
	TACTIC_RUSH = Attempt to stay within close range of the enemy at all times and maneuver at a close range. Always fire.
	TACTIC_HIT_AND_RUN = Fire on the enemy, run away to a distant range, and repeat. Always fire.
	TACTIC_FRONT = Attempt to stay in front of the enemy at all times. Always fire.
	TACTIC_REAR = Attempt to stay several meters behind the at all times. Always fire.
	TACTIC_CIRCLE_OF_DEATH = Attempt to circle around the enemy. Always fire.
	TACTIC_BACK_UP_AND_FIRE = Flee the enemy while walking backward to long-weapons range. Always fire.
	TACTIC_RETREAT = Flee the enemy. Do not fire.
	TACTIC_STAND_GROUND = Remain still and fire at the target.
	TACTIC_JUMP_AND_SHOOT = Stay in one place, and if the enemy is in range, jump over the nearby obstacles and shoot it. As with TACTIC_AMBUSH, this is automatically cancelled if the target can see the A.I. unit (i.e., it has a clear line of sight to the unit) when the A.I. unit is standing on the ground.
	TACTIC_SNIPE = Stay at maximum weapons range from the enemy. Wander around a bit to make yourself harder to hit. Fire at the enemy. Give up and switch to a new tactic if you can't fire after a certain amount of time.
	TACTIC_SHOOT_ONLY = Only shoot, do not try to move under any circumstances. This is the only tactic turrets can use.
	TACTIC_DEFEND = Defend the current target from any potential enemies.
	TACTIC_LOCAL_PATROL = Similar to TACTIC_STAND_GROUND, but the ‘Mech patrols randomly in a small area.
	TACTIC_SURRENDER = Stop, pitch torso down, put both arms up, and hold fire.
	TACTIC_AMBUSH = Rush forward from behind your hiding place, fire, and walk backward to the same spot again. As with TACTIC_JUMP_AND_SHOOT, this tactic is automatically cancelled if the target can see the A.I. unit (i.e., it has a clear line of sight to the unit) when the A.I. unit is standing in its hiding place (i.e., the spot where it was first given the attack order with this tactic).
	TACTIC_DFA = Shoot whenever possible, and try to use jump jets to kick the target in the face. This will only be assigned to ‘Mechs with jump jets (or assigned explicitly by a designer—make sure it is a ‘Mech that has jump jets!).
	TACTIC_HELI_POPUP = Pop up and down over hills (for helicopters only).
	TACTIC_DIVE_BOMB = Dive-bomb the target (for Nightshades and Peregrines only).
	TACTIC_FAST_CIRCLE = Like Circle of Death, but only moves forward and tries to avoid stopping
OverrideMove = Whether or not the combatai is allowed to override the movementai. This is a Boolean. True allows the unit to leave a path it is following when attacked. False means the unit will return fire but will not leave its path.

Returns: Nothing

Example usage: OrderAttackTactic(TACTIC_PICK_BEST, true);

OrderStopAttacking:

Causes the unit to stop attacking its target

Format: OrderStopAttacking

Returns: Nothing

OrderTakeOff:

Causes the unit to take off

Format: OrderTakeOff(Meters)

Meters = How many meters to use for take off. This is ignored if the unit is a helicopter.

Returns: True when the unit is in the air. If the unit is not capable of flight (i.e., a ‘Mech, tank, truck, boat, and so on), then this command returns true immediately.

Example usage: OrderTakeOff(50);

OrderLand:

Causes the current unit to land

Format: OrderLand

Returns: True when the unit is on the ground

OrderDoorOpen:

Causes the current unit to open its doors. This command only works if the unit is a dropship and if the dropship is on the ground.

Format: OrderDoorOpen

Returns: True when the doors are open

OrderDoorClose:

Causes the current unit to close its doors. This command only works if the unit is a dropship and if the dropship is on the ground.

Format: OrderDoorClose

Returns: True when the doors are closed

BoardDropShip:

Causes the group or team to approach and board the dropship

Format: BoardDropShip(group,dropship)

Group = ObjectID of the group boarding the dropship
Dropship = ObjectID of the dropship being boarded

Returns: True when all units are aboard

Example usage: BoardDropDhip((Groupobjectid(12)),eve_Dropship2);

Startup:

Causes the specified unit to start up

Format: Startup(who)

Who = the ObjectID of the unit that is to start up

Returns: Nothing

Example usage: Startup(me);

ShutDown:

Causes the specified unit to shut down

Format: ShutDown(who)

Who = The ObjectID of the unit that is to shut down

Returns: Nothing

Example usage: ShutDown(me);

StopExecute:

Causes the specified unit to stop executing. The unit will no longer run scripts, it’s A.I. will be shut off.

Format: StopExecute(who)

Who = The ObjectID of the unit that is to stop executing

Returns: Nothing

Example usage: StopExecute(me);

StartExecute:

Causes the specified unit to start executing its scripts again

Format: StartExecute(who)

Who = The ObjectID of the unit that is to start executing

Returns: Nothing.

Example usage: StartExecute(me);

FlyBy:

Causes the current unit to execute a flyby. The unit will descend to just low altitude and fly over, then ascend back to cruising altitude. If a potential collision can occur, then it will either abort early or not perform the flyby.

Format: FlyBy(Who)

Who = The ObjectID of the unit being buzzed

Returns: True when the flyby is done

Example usage: FlyBy(PlayerMech);

SelfDestruct:

Causes the specified unit to self destruct

Format: SelfDestruct(who)

Who = The unit that is to self destruct

Returns: Nothing

Example usage: SelfDestruct(me);

LancemateCommand:

Issues a lancemate command to a specific unit

Format: LancemateCommand(who,command)

Who = The ObjectID of the unit receiving the command. Who must be an A.I. unit and should belong to a group (not a team) whose A.I. is set to the “lancemate” A.I.

Command = The command being issued. Valid commands include the following:
	LANCEMATE_DEFAULT
	LANCEMATE_ATTACKPLAYERSTARGET
	LANCEMATE_DEFENDPLAYERSTARGET
	LANCEMATE_FORMONME
	LANCEMATE_HOLDFIRE
	LANCEMATE_GOTOMYNAVPOINT
	LANCEMATE_STOP
	LANCEMATE_SHUTDOWN
	LANCEMATE_ATTACKNEARESTTHREAT
	LANCEMATE_REPAIRATNEARESTREPAIRBAY

Returns: Nothing

Example usage: LancemateCommand(eve_Lancemate2, LANCEMATE_STOP);

Destroy:

Instantly destroys the specified object

Format: Destroy(who)

Who = The ObjectID for the object being destroyed. Who may be a team or group.

Returns: Nothing

Example usage: Destroy(eve_patrol1);

Conditionals (Expressions)
The following is the list of valid conditionals used in the “expressions” fields of FSMs. When returning TRUE, the FSM will execute the “statements” within and transition to the new state.

IsShot:

Determines whether a unit has been shot within the last 5 seconds

Format: IsShot(who)

Who = The unit being checked. Who may be a team or group.

Returns: True if the unit has been shot within the last 5 seconds. Note that this function will return true if a shot fired by an enemy unit has passed close to the unit as well (range determined by the “isshotradius” command). In addition, this command will return true if the unit is shot by friendly fire unless the “Setignorefriendlyfire” command is used.

Example usage: if ((isshot(me)) == true) then

IsWithin:

Determines if two objects are within a specified range of one another

Format: IsWithin(Object1,Object2,meters)

Object1 = The first object of the two to check. Object 1 may be a team or group.
Object2 = The second object of the two to check. Object 2 may be a team or group. (Note that if both are teams/groups, there may be performance concerns, especially if object 1 and object 2 are large groups, and if this function is called every frame. Avoid using this between two teams/groups with more than four or five units each.)

Meters = The distance to check for

Returns: True if any member of Object 1 and any member of Object 2 are within the specified range of one another

Example usage: if ((iswithin(PlayerMech,(groupobjectid(14)),600)) == TRUE) then

IsDead:

Determines if the specified object is dead

Format: Isdead(Who)

Who = The object being checked. Who may be a team or group.

Returns: True if “who” is dead. If “who” is a team or group then this function will return true only if the entire team or group is dead.

Example usage: If (not (isdead(playermech))) then

IsEqual:

Determines if two numbers are equal to one another

Format: IsEqual(Num1, Num2)

Num1 = The first number. This can be a real.
Num2 = The second number. This can be a real.

Returns: True if Num1 is equal to Num2.

Example usage: If (isequal(deadcount,objectivenumber)) then

IsLesser:

Determines if one number is less than another

Format: IsLesser(Num1,Num2)

Num1 = The first number. This can be a real.
Num2 = The second number. This can be a real.

Returns: True if Num1 is Less then Num2.

Example usage: If (isLesser(deadcount,objectivenumber)) then

IsGreater

Determines if one number is Greater than another.

Format: IsGreater(Num1, Num2)

Num1 = the first number. This can be a real.
Num2 = The second number. This can be a real.

Returns: True if Num1 is greater then Num2

Example usage: If (isGreater(deadcount,objectivenumber)) then

EqualId:

Determines if one number is less than another

Format: Equalid(Who1,Who2)

Who1 = ObjectID for the first object
Who2 = ObjectID for the second object

Returns: True if Num1 is Less then Num2

Example usage: If (Equalid(EVE_APC1,Mytarget)) then

IsShutdown:

Detemines if the selected unit is shutdown

Format: IsShutdown(who)

Who = The unit being checked. Does not work for teams or groups.

Returns: True if the selected unit is shut down. Note that for destroyed objects, it will still return false, since “dead” and “shut down” are not the same thing. 

Example usage: If ((isShutdown(mytarget)) == true) then

IsWithinLocPoint:

Determines if a specific unit or any member of a specific group of units is within a specified range of a specified loc point

Format: IsWithinLocPoint(who,point,meters)

Who = The unit being checked. Who may be a team or group.
Point = The loc point being checked.
Meters = The range from the loc point that is being checked

Returns: True if the unit is within range of the loc point. If “who” is a team or group, it will return true if any member of that team or group is within range of the loc point.

Example usage: if ((iswithinLocpoint(playermech,Locpoint1,450)) == true) then

PlayerShooting: 

Determines if a specific player has fired his weapons within a specified time period

Format: PlayerShooting(who,seconds)

Who = The player being checked
Seconds = The time period to check

Returns: True if the specified player has fired weapons within the specified number of seconds

Example usage: If (playershooting(GetplayerVehicle(epl_player0),7) == false) then

TacticIsFinished:

Determines if the specified unit is using a special ambush-type tactic (TACTIC_AMBUSH, TACTIC_JUMP_AND_SHOOT, TACTIC_HELI_POPUP) and the tactic considers itself to be “finished”—i.e., it believes that the player can see it when it is “hidden” so the tactic will no longer be effective

Format: TacticIsFinished(who)

Who = The unit being checked. Does not work for teams or groups.

Returns: True if the tactic is finished

Example Usage: if (Tacticisfinished(eve_ambushMech1)) then
Group/Team Functions
Groups are organized in the mission script and are deliberate groupings of units in a single-player mission designed to make organization and coding of the mission easier.

Teams are teams in a multiplayer game.

GroupObjectID:

Converts a GroupID to a GroupObjectID. You must use this function to convert a group ID to an ObjectID for any function that takes a group as an object ID (i.e. any function that uses groups).

Format: GroupObjectID(Group_id)

Group_id = The Number assigned to that group by the group add object command

Returns: The ObjectID for that group

Example Usage: If (isdead(Groupobjectid(12))) then

TeamObjectID:

Converts a team number to a special TeamObjectID. This is identical to GroupObjectID(), but allows you to work with teams as if they were groups for any ABL functions that work with groups—i.e., you may use this function to convert a team number to an ObjectID for any function that takes a group as an object ID (any function that uses groups)

Format: TeamObjectID(Team)

Team = The team number to be converted to an ObjectID. The value of “team” must be a group number between 1 and 8 to specify all the members of a given group, or 0 to indicate all vehicles which are members of any valid groups. For example, if you want to destroy all members of team 2, call Destroy(TeamObjectID(2));

Returns: Nothing

Example usage: If (isdead(Teamobjectid(2))) then
	
GroupAddObject:

Adds a specific object to a specific group. This is the way a group is created; if the group did not exist before, the addition of an object to the group summons it into existence implicitly. Group 1 is the player’s group in a single-player mission and should not be used. Valid group IDs are 2 through 9999.

Format: GroupAddObject(Group,who)

Group = The ObjectID of the group that the unit is being added to
Who = The unit being added

Returns: Nothing

Example usage: GroupAddObject(GroupObjectid(5),eve_Convoy1);

GroupAllDead:

Determines if all members of a specific group or team are dead.

Format: GroupAllDead(Group)

Group = the ObjectID for the group or team being checked

Returns: True if all members of the group or team are dead

Example usage: if (Groupalldead(Groupobjectid(4))) then

GroupRemoveObject:

Removes the specified unit from the specified group. This function does not work with teams.

Format: GroupRemoveObject(Group,Who)

Group = The group that the unit is to be removed from

Who = The unit being removed

Returns: Nothing

Example usage: GroupRemoveObject(Groupobjectid(23),EVE_Barge3);

GroupNumDead

Determines the number of units dead in a specific group. This function does not work with teams.

Format: GroupNumDead(Group)

Group = The Group being checked

Returns: The number of units dead in that group

Example usage: if ((groupnumdead(groupobjecid(32))) > 4) then

GroupSize:

Determines the number of units in a specific group.

Format: GroupSize(Group)

Group = The group being checked. This function works with teams as well.

Returns: The size of the group. If there is no such group this function will return 0.

Example Usage: NuminTeam = Groupsize(TeamObjectid(4));

GroupContainsObject: 

Determines if the specified object is in the specified group. This function does not work with teams.

Format: GroupContainsObject(group,object)

Group = ObjectID of the group being checked
Object = ObjectID of the object being checked

Returns: True if the specified group contains the specified object

Example Usage: If ((GroupContainsObject(Groupbjectid(31),EVE_Attacker3)) == TRUE) then

GroupAllWithin:

Determines if all members of a specific group are in a specific area. This function does not work with teams.

Format: GroupAllWithin (group,target,range)

Group = ObjectID of the group that is being checked
Target = ObjectID of the object being checked against
Range = Range from the object to be checked

Returns: True if all members of the group still alive are within the specified range of the specified object

Example usage: if (groupallwithin(groupobjectid(11), ena_navAlpha, 400)) then

SetGroupAI:

Sets a specific A.I. type to a specific group. This function does not work with teams.

Format: SetGroupAI(Group,ai)

Group = ObjectID of the group having its A.I. set.
AI = The A.I. type to be assigned to that group. A.I. types include the following:

	GROUPAI_NONE = No group A.I. Used to remove a groupai from a group that already has one.
	GROUPAI_LANCEMATE = Uses lancemate A.I.— all vehicles after the first are considered lancemates of the first.
	GROUPAI_RADIOSQUAD = Serves no purpose other than to propagate IsShot () notifications through all members of the group. If one member of the group is shot, then the IsShot function will return true for all members.
	GROUPAI_MOODSQUAD = Same as a "radio squad," but members' moods are shared—i.e., there is a single "group mood" that is affected proportionally by anything that happens to any individual unit, and each unit responds according to this group mood.
	GROUPAI_FOCUSFIRESQUAD = Same as a “radio squad” but all members of a group will tend to choose the same target more often.

Returns: Nothing

Example Usage: SetGroupAI((GroupObjectid(8)),GROUPAI_RADIOSQUAD);
Timer Functions
All timer functions use one of 32 different timers. These timers are named gti_timer_0 through gti_timer_31.

Gettimer:

Determines the current value of a specific timer

Format: GettTimer(Timer)

Timer = The ID of the timer being checked

Returns: The current value of the timer, in seconds, rounded to the nearest integer

Example usage: Currenttime = Gettimer(gti_timer_3);

Settimer

Sets a specific timer to a specific value

Format: Settimer(timer,value)

Timer = The ID of the timer being set
Value = The new value for the timer. This is an integer and is in seconds.

Returns: Nothing

Example usage: Settimer(gti_timer_2,45);

TimeLesser:

Determines if the current value of a specific timer is less than a specific number of seconds.

Format: TimeLesser(timer,num)

Timer = The ID of the timer being checked.
Num = The number of seconds being checked against.

Returns: True if the current value of the timer is less than the number of seconds being checked against.

Example usage: if (timelesser(gti_timer_1,24)) then

TimeGreater:

Determines if the current value of a specific timer is greater than a specific number of seconds

Format: TimeGreater(timer,num)

Timer = The ID of the timer being checked
Num = The number of seconds being checked against

Returns: True if the current value of the timer is greater than the number of seconds being checked against

Example usage: if (timeGreater(gti_timer_1,24)) then

StartTimer:

Causes a timer to start counting up from 0

Format: StartTimer(Timer)

Timer = The ID of the timer being started.

Returns: Nothing

Example usage: Starttimer(gti_Timer_5);

KillTimer:

Causes the specified timer to stop counting. Note that this command does NOT reset the timer to 0.

Format: KillTimer(timer)

Timer = The ID of the timer being killed.

Returns: Nothing

Example usage: KillTimer(gti_timer_5);

ResetTimer:

Resets the specified timer to 0 and starts it counting again.

Format: ResetTimer(Timer)

Timer = The ID of the timer being reset

Returns: Nothing

Example usage: ResetTimer(gti_timer_20);

PauseTimer:

Pauses or “unpauses” a specific timer

Format: PauseTimer(timer,pause)

Timer = The ID of the timer to be paused or unpaused
Pause = A Boolean setting whether to pause or unpause the timer. True is pause and false is unpause. Pausing is nested—i.e., if you call pause (5,true) two times then you need to call pause (5,false) twice to start running again.

Returns: Nothing

Example usage: PauseTimer(gti_timer_8,true);
Objective Functions

RevealObjective:

Reveals a specific objective in the mission

Format: RevealObjective(ObjectiveID)

ObjectiveID = The objective being revealed

Returns: Nothing

Example usage: RevealObjective(eob_Killemall);

HideObjective:

Hides a specific objective from the player

Format: HideObjective(ObjectiveID)

ObjectiveID = The objective being hidden

Returns: Nothing

Example usage: HideObjective(eob_findWarehouse);

FailObjective

Causes a specific objective to be failed

Format: FailObjective(ObjectiveID)

ObjectiveID = The objective being failed

Returns: Nothing

Example usage: FailObjective(eob_stayalive);
	
SuccessObjective:

Causes a specific objective to be marked successful

Format: SuccessObjective(ObjectiveID)

ObjectiveID = The objective being succeeded.

Returns: Nothing

Example usage: SuccessObjective(eob_stayalive);

ShowAllRevealedObjectives:

Causes all currently revealed objectives to be visible on the screen

Format: ShowAllRevealedObjectives

Returns: Nothing

Example usage: ShowAllRevealedObjectives

CheckObjectiveCompletion:

Determines the current state of a specific objective

Format: CheckObjectiveCompletion(ObjectiveID)

ObjectiveID = The objective being checked.

Returns: The status of the objective. Different statuses include the following:

	OBJECTIVE_NEUTRAL
	OBJECTIVE_SUCCEEDED
	OBJECTIVE_FAILED

Example usage: if ((CheckObjectiveCompletion(eob_BlowUpFactory)) == OBJECTIVE_SUCCEEDED) then

HelpMessage:

Causes the specified help message to be displayed on the screen for the specified amount of time

Format: HelpMessage(helpid,time)

Helpid = The ID of the help message being displayed. A help message is an objective with the help message flag set.
Time = The number of seconds to display the message. Time is an integer.

Returns: Nothing

Example usage: HelpMessage(eob_tellthemtoturnright, 15);

EndMission:

Causes the mission to end if either success or failure with a delay of a specified number of seconds.

Format: EndMission(Successful, time)

Successful = a Boolean that determines if the mission was a success or failure. TRUE = success, FALSE = failed.
Time = delay before mission end.

Returns: Nothing

Example usage: EndMission(False, 15);

Audio Functions

Sounds come in three types: generic sounds, mission-specific sounds, and music.

Generic sounds

Generic sounds are those sounds that are always loaded into the game. They do not need to be specifically called out in any of the mission’s files as the game already knows they exist. A list of all generic sounds can be found in Audio_Generic.rtf.

Mission-Specific Sounds

Mission-specific sounds are sounds created for use in a specified mission only. Should a designer create sounds for use in a specific mission, those sounds must be listed in the .sounds file for that mission. Format for listing sound is as follows:

[VO\OP1\MI1\Boom_Pet.wav]
cached=no
streamed=no

Line 1 is the location and name of the file. The system assumes that the path begins in the game’s root\content\audio folder. Such a folder will have to be made in order to hold the sounds. For example, the above line is telling the system that the sound Boom_Pet.wav is located off the game’s root directory in \content\audio\VO\OP1\MI1\. 

The name of the sound MUST have a talker ID attached to it via an underscore. The talker ID is comprised of the three letters after the underscore. Only that one underscore may be in the name of the sound. For example, the talker ID for the above sound is “pet.” Valid Talker IDs include the following: 

TALKER_IAN, TALKER_RAT, TALKER_CAS, TALKER_GON,	TALKER_JEN, TALKER_TER, TALKER_DAM, TALKER_RES, TALKER_65C, TALKER_EV1, TALKER_EV2, TALKER_SAL, TALKER_REC, TALKER_SUP, TALKER_FO1, TALKER_FO2, TALKER_FO3, TALKER_FO4, TALKER_FO5, TALKER_FO6, TALKER_PI1, TALKER_PI2, TALKER_PI3, TALKER_PI4, TALKER_ART, TALKER_SHE, TALKER_BD1, TALKER_BD2, TALKER_FOX, TALKER_KIL, TALKER_SGT, TALKER_ROM, TALKER_XRY, TALKER_CCG, TALKER_ERL, TALKER_PA1, TALKER_PA2, TALKER_PA3, TALKER_PA4, TALKER_BRV, TALKER_CHL, TALKER_DEN, TALKER_RCG, TALKER_VRD, TALKER_VOR, TALKER_HQ1, TALKER_HQ2, TALKER_HQ3, TALKER_MED, TALKER_SFQ, TALKER_CJK, TALKER_ABC, TALKER_BRK, TALKER_CST, TALKER_ROL, TALKER_WIL, TALKER_EPS, TALKER_PET, TALKER_EP2, TALKER_BET

Cached and streamed are set to no for most sounds. They should be set to yes only for extremely large sounds causing problems with performance.

All sounds must be recorded as 22 kHz, 16 bit, mono .wav files.

Music

All available music is listed in the Audio_Music.rtf file.

Sound Commands

PlayVoiceOver:

Plays the specified sound. If called more than once, the sound will be played more than once.

Format: Playvoiceover(“sound”,talker_id)

Sound = The location and name of the sound. Location is the location of the sound from the audio directory. The name of the sound is the file name of the sound MINUS the talker id and extension. This is a string and therefore must be placed in quotes. For example… let’s say that Mech IV is sitting in c:\mw4. Inside that I make sure there is a folder named “content”, then I make sure there is a folder in THAT named “audio”. The game will assume that all sounds are in that folder and will add that location to all sound names. So if I list as a sound name “VO\OP3\MI2\Joe” the system will look for a file named Joe in c:\mw4\content\audio\ VO\OP3\MI2. The file “Joe” will also have an underscore and talker id attached to it.
Talker_id = the talker id of the sound being played. Using the example above, let’s say I was using FO2 as my talker id for joe. The file would actually be named Joe_FO2.Wav

Returns: Nothing

Example Usage: PlayVoiceOver("VO\OP3\MI1\Intro",talker_rat);

PlayVoiceOverOnce:

Works exactly as PlayVoiceover above. The only difference is that the sound will only be played once, no matter how many times the command is called.

KillVoiceOvers:

Kills all voiceovers currently playing

Format: KillVoiceovers

Returns: Nothing

Example usage: KillVoiceOvers;

StartMusic:

Plays a specified piece of music

Format: StartMusic(“Music”,old_timeout,new_timein,new_volume)

Music = tTshe name of the music file. The name must have music\ in front of it. As the name of the music is a string, it must be surrounded by quotes.
Old_timeout = How quickly to bring down the volume on any old music playing at the time this function is called. This is a real.
New_timein = How long, in seconds, it will take for the new music to fade in. This is a real.
New_volume = The final volume level of the new music. This is an integer with a range of 0 to 100.

Returns: Nothing

Example usage: StartMusic(“Music\Sander",3.5,3.0,50);

IsMusicPlaying:

Determines if there is any music playing

Format: IsMusicPlaying

Returns: True if music is playing. False if no music is playing.

Example usage: if (not ismusicplaying) then

Miscellaneous Functions

Distance:

Determines the distance between two loc points

Format: Distance (p1,p2)

P1 = The first loc point
P2 = The second loc point

Returns: Distance between the two points in meters. This is an integer. Height differential is ignored.

Example usage: if ((distance(Locpoint1,locpoint2)) < 400) then

PlayerAI:

Turns on and off player’s control of his or her ‘Mech

Format: Playerai(objectid,Boolean)

Objectid = Tshe objectID of the unit being placed under control of player.abl. This must be set to a player ID.
Boolean = Whether or not the player’s ‘Mech is under the control of the player.abl script. If true, the player does not have control of his or her ‘Mech. Instead, the ‘Mech is under the control of the player.abl script. If false, the player has control of his or her ‘Mech.

Returns: Nothing

Example usage: Playerai(epl_player0,true);

Rand:

Generates a random number between two specific numbers, inclusive

Format: Rand(low,high)

Low = The low end of the range for the random number to be generated. This is an integer.
High = The high end of the range for the random number to be generated. This is an integer.

Returns: A random integer between the low number and the high one, inclusive

Example Usage: SetSkillLevel(me,(rand(40,80)),50,-1);

PlayEffect:

Causes the specified effect to play

Format: PlayEffect(what)

What = The effect being played

Returns: Nothing

Example Usage: Playeffect(ede_FlareAlpha);

KillEffect:

Causes the specified effect to stop playing

Format: KillEffect(what)

What = The effect being killed

Returns: Nothing

Example usage: Killeffect(ede_FlareAlpha);

RevealNavpoint:

Reveals a specific nav point but (unlike SetNavPoint) does NOT set it as the active nav point in the player’s nav system

Format: Revealnavpoint(navpoint)

Navpoint = The nav point being revealed

Returns: Nothing

Example usage: Revealnavpoint(ena_NavAlpha);

Teleport:

Causes a specific unit to teleport to a specific spot in the world. The unit will automatically snap to the ground upon teleporting.

Format: Teleport(who,point)

Who = The object being teleported.  Who may not be a team or group.
Point = A loc point for the spot in the world where the unit will teleport to

Returns: Nothing

Example Usage: Teleport(me,Locpoint3);

TeleportToHell:

Causes a specific unit to move to coordinates that are off the map. This command will not work properly if the unit is under a move order (even ordermovelookout) or is in combat. As such, the unit should first perform a shutdown command to ensure that it is not attempting to move in any way.

Format: TeleportToHell(who)

Who = The unit being teleported

Returns: Nothing

Example usage: TeleportToHell(me);

The following two Commands only apply to ‘Mechs (due to expense), and only two or three should be active at the same time.

CreateHeatSphere:

Creates a sphere of influence wherein heat behaves differently than normal

Format: CreateHeatSphere(object,radius,seconds,percentage)

Object = ObjectID for the object which the sphere will be centered upon

Radius = The radius of the sphere in meters

Seconds = How many seconds the sphere will last

Percentage = What effect the sphere has on heat generation. A value of 100 means that heat generation is normal. The higher above 100, the more heat is generated. The lower the number, the less heat generated. Therefore, a value of 200 means that all weapons fire will generate twice as much heat as normal, whereas a value of 50 means that heat generated will be halved.

Returns: Nothing

Example usage: CreateHeatSphere(EBU_Gastank1,50,15,200);

CreateRadarSphere:

Creates a sphere of influence that affects the sensors’ ability to work.

Format: CreateRadarSphere(object,radius,seconds,percentage)

Object = ObjectID for the object which the sphere will be centered upon

Radius = The radius of the sphere in meters

Seconds = How many seconds the sphere will last

Percentage = The efficiency of radar while someone is inside the sphere. For example, if you put 50 in, every ‘Mech's radar in the sphere's distance will be cut in half, while 0 would render sensors useless, 200 would double the range, and so on. 

Returns: Nothing

Example usage: CreateRadarSphere(EBU_Generator1, 400, 20, 45);

Switch:

Performs a series of difference commands based on the incrementing value of a specific value

Format: switch (Switchvariable)

	Case X:
		
		Commandset1;

	Endcase;

	Case Y:
		
		Commandset2;

		Endcase;

		Endswitch;

Switchvariable = The value to be checked
X = The first value to check against
Commandset1 = The first set of commands to run. If Switchvariable = X then all the commands in commandset1 will be run.
Y = The second value to check against
Commandset2 = The second set of commands to run. If Switchvariable = Y then all the commands in commandset2 will be run.

Note that there can be more than two cases checked.

Returns: Nothing

Example usage: 

	switch (getmemoryinteger(me,9))

	case 1:
		//AlphaMechs
		attackrange = 650;
		path = epa_Alphapath;
	endcase;
						
	case 2:
		//BetaMechs
		attackrange = 700;
		mytactic = tactic_circle;
		path = epa_Betapath;
	endcase;

	endswitch;
Debugging Functions

Note that all of the below functions take no parameters whatsoever and should be used solely for debugging purposes.

EnableAIStats:
Turns on the on-screen A.I. and diagnostics statistics

DisableAIStats:
Turns off the on-screen A.I. and diagnostics statistics

EnableMoveLines:
Turns on the movement lines for A.I. units. Shows the last destination that the combat A.I. issued to the movement A.I.

DisableMoveLines:
Turns off the movement lines for A.I. units [see EnableMoveLines()]

EnableGlobalInvulnerable:
Makes all non-A.I. units invulnerable

DisableGlobalInvulnerable 
Turns off invulnerability for all non-A.I. units

ShowLattice:
Displays the lattice for the current mission
In-Game Cinema Related Functions
These functions work ONLY when plotting out an in engine cinema. Real numbers or floats are numbers with decimal places (such as 1.5 ). The cinema requires sub-meter and sub-second resolution, and it is easier to do with real numbers than with centimeters and tenths of seconds.

Each camera actually consists of two objects that can be manipulated. These are called the camera and the target. The camera is defined by where the player will be looking from during the cinema. The target is what he is looking at. Both may be manipulated to create a variety of effects.

CinemaStart:

Activates the cinema system. Turns off the HUD, turns on letterboxing.

Format: CinemaStart

Returns: Nothing

Example usage: CinemaStart;

StopCinema:

Deactivates the cinema system

Format: StopCinema

Returns: Nothing

Example usage: StopCinema;

CinemaSkip:

Detects if someone has pressed the space bar during a cinema

Format: CinemaSkip

Returns: True if the space bar is pressed during a cinema

Example usage: if (cinemaskip) then

SetActiveCamera:

Switches view to a specific camera

Format: SetActiveCamera(Camera)

Camera = The ObjectID for a specific camera

Returns: Nothing

Example Usage: SetActiveCamera(eca_Cameraship1);

CameraFollowObject:

Causes the currently active camera to follow a specific object

Format: CameraFollowObject(Object)

Object = The ID of the object for the active camera to follow. The camera will place itself in the center of the object unless the CameraOffset command is used.

Returns: Nothing

Example usage: CameraFollowObject(PlayerMech);

CameraFollowPath:

Causes the currently active camera to follow the specified path

Format: CameraFollowPath(path,speed)

Path = The ID of the path the camera is to follow. The camera will follow the path directly. If you want the camera to follow the path at an offset (i.e., the path is on the ground and you want the camera to be 10 meters above the ground), you must use the cameraoffset command as well.

Speed = The speed for the camera to move in KpH. This is an integer.

Returns: Nothing

Example usage: CameraFollowPath(epa_Basepath, 60);

CameraOffset:

Offsets the camera from whatever object or path it is currently following. Without the camera offset command, the camera will follow an object by sitting in the object’s center point. This command is also very useful causing graceful arcs around an object, even when that object is moving.

Format: CameraOffset(X,Y,Z,time,local)

X = Offset distance in meters along the X axis. This is a real.
Y = Offset distance in meters along the Y axis This is a real.
Z = Offset distance in meters along the Z axis This is a real.
Time = The time that the camera will take to get from its old position to its new one. This is a real. If time is set to 0, the camera will teleport to its new location.
Local = A Boolean. If set to true, the camera will follow terrain as it travels. If set to FALSE, it will not.

Returns: Nothing

Example usage: CameraOffset(30.5, -50.0, 73.0, 8.0, TRUE);

CameraPosition:

Detaches the camera and moves it to the specified world position

Format: CameraPosition(X,Y,Z,time)

X = World position in meters along the X axis. This is a real.
Y = World position in meters along the Y axis This is a real.
Z = World position in meters along the Z axis This is a real.
Time = The time that the camera will take to get from its old position to its new one. This is a real. If time is set to 0, the camera will teleport to its new location.

Returns: Nothing

Example usage: CameraPosition(2032.0,1000.0,-750.0,20.0);

CameraDetach:

Detaches the current camera and stops its movement

Format: CameraDetach

Returns: Nothing

Example usage: CameraDetach;

OverrideCameraPitch, OverrideCameraRoll, OverrideCameraYaw: 

Turns off pointing at the target in the appropriate axis and rotates the camera the specified number of degrees. The time value allows you to smoothly get to the new position over the time period. This can force level views or simple pan/rotate effects without utilizing the target.

Format: OverrideCameraPitch(degrees,time)

Degrees = How many degrees to move the camera. This is a real.
Time = The time that the camera will take to get from its old position to the new one. This is a real. 

Returns: Nothing

Example usage: OverrideCameraRoll(20.0,10.0);

ResetCameraOverrides:

Turns off all camera overrides

Format: ResetCameraOverrides

Returns: Nothing

Example usage: ResetCameraOverrides;

TargetFollowObject:

Causes the target attached to the currently active camera to follow a specific object

Format: TargetFollowObject(Object)

Object = The ID of the object for the target to follow. The target will place itself in the center of the object unless the TargetOffset command is used.

Returns: Nothing

Example usage: TargetFollowObject(PlayerMech);

TargetFollowPath:

Causes the currently active target to follow the specified path

Format: TargetFollowPath(Path,Speed)

Path = The ID of the path the target is to follow. Note that the target will follow the path directly. If you want the target to follow the path at an offset (i.e., the path is on the ground and you want the target to be 10 meters above the ground), you must use the targetoffset command as well.

Speed = The speed for the Target to move in KpH. This is an integer.

Returns: Nothing

Example usage: TargetFollowPath(epa_Basepath, 60);

TargetOffset:

Offsets the target from whatever object or path it is currently following. Without the targetoffset command, the target will follow an object by sitting in the object’s center point.

Format: TargetOffset(X,Y,Z,time,local)

X = Offset distance in meters along the X axis. This is a real.
Y = Offset distance in meters along the Y axis This is a real.
Z = Offset distance in meters along the Z axis This is a real.
Time = The time that the target will take to get from its old position to the new one. This is a real. If time is set to 0, the target will teleport to its new location.
Local = A Boolean. If set to True, the target will follow terrain as it travels. If set to false, it will not.

Returns: Nothing

Example usage: TargetOffset(30.5, -50.0, 73.0, 8.0, TRUE);

TargetPosition:

Detaches the target and moves it to the specified world position

Format: TargetPosition(X,Y,Z,Time)

X = World position in meters along the X axis. This is a real.
Y = World position in meters along the Y axis This is a real.
Z = World position in meters along the Z axis This is a real.
Time = The time that the Target will take to get from it’s old position to the new one. This is a real. If time is set to 0, the target will teleport to its new location.

Returns: Nothing

Example sage: TargetPosition(2032.0,1000.0,-750.0,20.0);

TargetDetach:

Detaches the current target and stops its movement.

Format: TargetDetach

Returns: Nothing

Example usage: TargetDetach;
 
SetCameraFOV:

Changes the Field of View for the camera

Format: SetCameraFOV(Degrees, time)

Degrees = The new FOV in degrees. This is a real.
Time = The number of seconds to make this change over. This is a real.

Returns: Nothing

Example usage: SetCameraFOV(45.0,6.0);

SetCameraFootShake: 

Determines whether a specified ‘Mech will shake the camera with its footfalls, and if so, the distance from the unit at which a “normal” amount of foot-shaking will occur. Closer distances will cause the camera to shake more with each footstep, and farther distances will cause it to shake less (a distance of “0” turns off the foot-shaking).

Format: SetCameraFootShake(who,distance)

Who = The unit that will affect the camera with its footfalls. This unit must be a ‘Mech.
Distance = The distance in meters at which foot shaking will be considered “normal.” Closer than this distance will cause the shaking to increase. Further than this distance will cause the shaking to decrease.

Returns: Nothing

Example usage: SetCameraFootShake(playermech,200);

FadeToBlack, FadeToWhite, FadeFromBlack, FadeFromWhite:

Fades to and from black and white over a specified time period. Note that the system keeps track of cinema states. Should you fade to black, end the cinema, then start a new cinema later you will still be in black.

Format: FadeToBlack(time)

Time = How long to spend fading to/from black/white. This is a real.

Returns: Nothing

Example usage: FadeFromWhite(7.0); 

SetCompositingEnabled

Turns terrain compositing on or off. It is enabled ("on") by default. This should be used only during cinematic sequences, to eliminate the piece-wise terrain loading effect during a cut scene. If you turn off compositing in this way, be careful to ensure that you call SetCompositingEnabled(TRUE) again when the cinema ends or is skipped if you disable it at any point during a cinematic sequence.

Format: SetCompositingEnabled(enabled)

Enabled = A Boolean that determines if compositing enabled is on or off. True = on, false = off.

Returns: Nothing

Example usage: SetCompositingEnabled(False);

Multiplayer Support and Buckets

MechWarrior4 uses a score “bucket” system to track events and scores. The values of these buckets can then be “poured” into a custom bucket to total up scores based on game events, triggers, or time. Below is a list of buckets supported by the game engine. 

Note Some of these were not used in the final game, so not all of these have been fully tested.

Here’s a quick sample of a script used in team attrition:

function SetupScoring_TeamAttrition;
 code
SetFlagsEnabled(FLAGS_HIDE);		
TrackBucket(Bucket_KILLS,0,true);		
TrackBucket(Bucket_DEATHS,0,true);		
TrackBucket(Bucket_CUSTOM,0,true);		
AddCustomBucketParameter(Bucket_ENEMY_DAMAGE_INFLICT,1);	 
AddCustomBucketParameter(Bucket_FRIENDLY_DAMAGE_INFLICT,-1);
AddCustomBucketParameter(Bucket_ENEMY_KILLS,500);
AddCustomBucketParameter(Bucket_FRIENDLY_KILLS,-500);
AddCustomBucketParameter(Bucket_SUICIDES,-1500);
AddCustomBucketParameter(Bucket_ENEMY_KILLS_BY_TONNAGE,5);
AddCustomBucketParameter(Bucket_ENEMY_COMPONENT_KILLS,50);
AddCustomBucketParameter(Bucket_FRIENDLY_COMPONENT_KILLS,-50);
endfunction;

In English++, this function turns off flags. It tracks kills, deaths, and a custom (total) bucket. The custom parameters apply score modifiers into the custom bucket. For each point of damage a player deals to an enemy he gets one point in the custom bucket, etc.

Valid Bucket Types:

Bucket_KILLS: How many kills I can take credit for
Bucket_FRIENDLY_KILLS: How many friendly-fire kills I've committed
Bucket_ENEMY_KILLS: How many enemies I've killed
Bucket_KILLS_BY_TONNAGE: Total tonnage of everyone I've killed
Bucket_FRIENDLY_KILLS_BY_TONNAGE: Total tonnage of all friendlies I've killed
Bucket_ENEMY_KILLS_BY_TONNAGE : Total tonnage of all enemies I've killed
Bucket_DEATHS: How many times I've died
Bucket_SUICIDES: How many times I killed myself
Bucket_DAMAGE_INFLICT: How much damage I've inflicted
Bucket_FRIENDLY_DAMAGE_INFLICT: How much damage I've inflicted on friendlies
Bucket_ENEMY_DAMAGE_INFLICT: How much damage I've inflicted on enemies
Bucket_DAMAGE_RECEIVE: How much damage I've received
Bucket_FRIENDLY_DAMAGE_RECEIVE: How much damage I've received from friendlies
Bucket_ENEMY_DAMAGE_RECEIVE: How much damage I've received from enemies
Bucket_COMPONENT_KILLS: How many components I've killed
Bucket_COMPONENT_DEATHS	: How many components I've lost
Bucket_FRIENDLY_COMPONENT_KILLS: How many friendly units' components I've killed
Bucket_FRIENDLY_COMPONENT_DEATHS: How many components I've lost to friendly fire
Bucket_ENEMY_COMPONENT_KILLS: How many enemy units' components I've killed
Bucket_ENEMY_COMPONENT_DEATHS: How many components I've lost to enemy units
Bucket_DFA: How many times I've been able to pull off a DFA
Bucket_SHOTS_HIT: How many of my shots have hit
Bucket_SHOTS_FIRED: How many shots I've fired
Bucket_HEAD_SHOTS: How many of my shots have hit a 'Mech's head
Bucket_ARM_SHOTS: How many of my shots have hit a 'Mech's arm
Bucket_LEG_SHOTS: How many of my shots have hit a 'Mech's leg
Bucket_TORSO_SHOTS: How many of my shots have hit a 'Mech's torso
Bucket_KILLS_PC: Unknown
Bucket_KILLS_AI: Unknown
Bucket_BLANK: Unknown
Bucket_SHUTDOWN_TIMER: Unknown
Bucket_OBJECTIVE: How many seconds (total) I've remained within an objective area
Bucket_OBJECTIVE_CONTESTED: How many seconds (total) I've remained within an objective area with enemies in the same area
Bucket_OBJECTIVE_UNCONTESTED: How many seconds (total) I've remained within an objective area with no enemies in the same area
Bucket_FLAGS_TAKEN: How many flags I've picked up
Bucket_FLAGS_DROPPED: How many flags I've dropped due to dying while carrying the flag

Bucket_FLAGS_CAPTURED: How many flags I've successfully returned to my capture zone

Bucket_FLAG_HOLD_TIME: Total amount of time I've held any flags
Bucket_TIME: Unknown
Bucket_ALIVE_PLAYERS: Unknown
Bucket_DEAD_PLAYERS:Unknown
Bucket_CUSTOM: A holder bucket used to track total score values

integer AddBucket (type,id,affects,mod2): Creates a new scoring bucket and return the its ID. Type, ID, affects, and mod2 are used to determine what the bucket holds.

ShowBucket(integer id): Causes the bucket value to be visible to the player

HideBucket(integer id): Causes the bucket value to be hidden from the player

real GetBucketValue(integer id): Returns the value of the bucket

SetBucketValue(integer id,real value): Sets the value of the bucket

SetBucketMult(integer id, real mult): Sets the multiplier for a bucket

TrackBucket (type,mod2, boolean visible): Automatically adds and removes buckets for the type and mod2. Visible determines if the bucket should be shown on the screen.

TrackObjectBucket (integer type, ObjectID object, integer distance, boolean visible): Automatically adds and removes buckets for tracking distance to an objective, or for tracking based on a flag. Visible determines if the bucket should be shown on the screen.

integer FindBucket (integer type, integer id, integer affects, integer mod2): Return the ID of the bucket that matches the parameters

AddCustomBucketParameter(integer bucketType, integer multiplier): Adds a multiplier for a "Bucket_CUSTOM." The bucketType parameter indicates the type of event that will be multiplied, and the multiplier indicates how much to add or subtract to the custom score if the event occurs. “multiplier" may any positive or negative number, or 0 to begin ignoring the given event type. As an example, AddCustomBucketParameter(Bucket_KILLS,666) will add 666 points for each kill to the custom score bucket. You may add any and all of the various bucket types as events via multiple such calls to AddCustomBucketParameter().

SetCustomBucketName(string name):
SetCustomBucketNameIndex(integer index): Allows you to set the name of the "custom" scoring bucket. SetCustomBucketName(): Allows you to specify a specific string as the name of the score. The second allows you to specify the string ID of a string in the MissionLang string resource file. Use the second version for any missions that will ship with MechWarrior4, since they need to be localized. The default name if not specified is "Custom."

AddPoints(ObjectID who, integer points): Adds the specified number of multiplayer scoring points to the object(s) specified by who. This affects the "custom"-type score only. "Points" may be negative to subtract points. "Who" may optionally be a group or team.

AttachFlag:

Attaches the specified flag to the specified object.

Format: AttachFlag(flagid,objectid)

Flagid = The ID of the flab being attached
Objectid = The ObjectID of the object having the flag attached to it

Returns: Nothing

Example usage: AttachFlag(Flag1,(Getplayervehicle(epl_player3));

DropFlag:

Causes a specific flag to drop to the ground if it is currently attached, or nothing if not attached.

Format: DropFlag(flagid)

Flagid = The ObjectID of the flag being dropped.

Returns: Nothing

Example usage: DropFlag(Flag3);

DeactiveFlag:

Turns off automatic attachment for a specific flag for a specific amount of time.

Format: DeactiveFlag(flagid,time)

Flagid = The ObjectID of the flag being deactivated
Time = The number of seconds the flag will be deactivated

Returns: Nothing

Example usage: DeactiveFlag(Flag4,10);

FlagRadius

Changes the automatic attachment radius for the specified flag

Format: FlagRadius(flagid,radius)

Flagid = The ObjectID of the flag having its radius changed
Radius = The new radius

Returns: Nothing

Example usage: Flagradius(Flag5,75);

SetMaxFlagsCarried:

Sets the maximum number of flags a given unit (or team or group) may carry at a time

Format: SetMaxFlagsCarried(who,maxFlags)

Who = The ObjectID for an individual unit, a team or group, or "NO_UNIT" to affect all units
MacFlags = The number of flags the unit may carry. "maxFlags" may be 0 to indicate that the unit may not carry flags, or a positive number to indicate that it may carry one or more flags. The default is one for all units.

Returns: Nothing

Example usage: SetMaxFlagsCarried(NO_UNIT,3);

SetFlagReturnTime:

Sets the amount of time a flag will take to return to its origin (where it was originally put in the map) after a 'Mech carrying it is destroyed. This affects all flags in the game simultaneously. 

Format: SetFlagReturnTime(time)

Time = The number of seconds that the flag will remain in a specific position before returning to it’s origin. "Time" may be 0 (instantaneous return to origin), -1 (the flag never returns to its origin; it remains where it was dropped), or a positive number (to indicate a number of seconds, after which the flag returns home automatically).

Returns: Nothing

Example usage: SetFlagReturnTime(17);

SetFlagCaptureReturnTime:

Sets the amount of time a flag will take to return to its origin (where it was originally put in the map) after it has been captured by an opposing team and brought to the opposing team’s home base. This affects all flags in the game simultaneously. 

Format: SetFlagCaptureReturnTime(time)

Time = The number of seconds that the flag will remain in a specific position before returning to it’s origin. "Time" may be 0 (instantaneous return to origin), -1 (the flag never returns to its origin), or a positive number (to indicate a number of seconds, after which the flag returns home automatically).

Returns: Nothing

Example usage: SetFlagCaptureReturnTime(17);

SetFlagCaptureEnabled:

Enables or disables the capturing of flags at team spawn drop zones or "TeamCapture#" drop zones. Flag capturing is enabled by default.

Format: SetFlagCaptureEnabled(enabled)

Enabled = Whether Flag Capture is enabled. True sets it to enabled, False to disabled.

Returns: Nothing

Example usage: SetFlagCaptureEnabled(TRUE);

SetFlagsEnabled:

Enables or disables flags in that mission. This is useful when multiple mission types are being done on the same map. Disabling flags makes the flags invisible in those mission types where flags are not used.

Format: SetFlagsEnabled(enabled)

Enabled = A Boolean that determines whether flags are enabled for that mission or not. If set to true then flags will be visible and available in that mission. If set to false then that mission will have no flags in it.

Returns: Nothing

Example Usage: SetFlagsEnabled(TRUE);

ChatMessage:

Sends the specified message through the chat system to all players

Format: ChatMessage(“Text”)

Text = The string to show up in the chat system

Returns: Nothing

Example usage: ChatMessage(“Check, one, two. Check, one, two. Is this thing on?”);

TeamSetNavs:

Sets the current nav point for all players on a team

Fomat: TeamSetNav(integer, navpoint)

Returns: Nothing

Example usage: TeamSetNav(1,ena_kill_box);  // Sets nav for team 1.

SetAlignment:

Sets alignments for multiple team games

Format: SetAligment(team,objectid,alignment)

Returns: Nothing

Example usage: 
      
SetAligment(TeamObjectID(1),FRIENDLY_ALIGNMENT);

SetAligment(TeamObjectID(2),FRIENDLY_ALIGNMENT);

SetAligment(TeamObjectID(3),ENEMY_ALIGNMENT);

// Makes team 1,2 friendly to each other and team 3 enemy to all.

PlayTeamBettySound:

Plays audio in multiplayer games. For a list of valid audio trigger files, see Multiplayer SoundTriggers.rtf

Format: PlayTeamBettySound(integer team,sound_trigger_event_name);

Returns: Nothing

Example usage: PlayTeamBettySound(1,SOUND_TRIGGER_MISSILE_LOCKED_ON_ME);

// Plays the incoming-missile sound for all players on team 1.

ShowBucket

	Makes a scoring bucket visible to the user in scoring window

	Format:	ShowBucket(integer id)

	Returns: Nothing

	Example usage: ShowBucket(Bucket_Flag_Hold_Time);
	
HideBucket:

Causes the bucket value to be hidden from the player

	Format: HideBucket(integer id)
	
	Returns: Nothing

	Example usage: HideBucket(Bucket_Flag_Hold_Time);

GetBucketValue:

Will return the value held in a bucket.

Format:	real GetBucketValue(integer id)

Return: Real value of a bucket

Example usage: Current_Score = GetBucketValue(Bucket_Kills);

SetBucketValue:

	Will set the value held in a bucket

	Format:	 SetBucketValue(integer id,real value)

	Returns: Nothing.

	Example usage: SetBucketValue(New_Score, Bucket_Kills);

TrackBucket:s

Enables tracking of a scoring bucket and determines if it will be visible to the player. 

Note Kills and deaths are always tracked regardless of this command. However, if they are not tracked they won’t show up in the in-game scoring window but will show up in the end of mission screen. The MOD2 command is not used.

Format: TrackBucket (type,mod2,boolean visible)

Returns: Nothing

Example usage: TrackBucket(Bucket_Kills,0,true);

TrackObjectBucket:

Will automatically add and remove buckets for tracking distance to an objective, or for tracking based on a flag. Visible determines if the bucket should be shown on the screen.

Format: TrackObjectBucket (integertype,ObjectIDobject,integerdistance,booleanvisible)

	Returns: Nothing.

	Example usage: TrackObjectBucket(BucketObjective, ena_nav_alpha, 100, true); OR:
				
			 Track ObjectBucket(Bucket_Objective_Contested, hill, radius, false);

AddCustomBucketParameter: 

Adds a multiplier for a "Bucket_CUSTOM." The bucketType parameter indicates the type of event that will be multiplied, and the multiplier indicates how much to add or subtract to the custom score if the event occurs. The “multiplier" may any positive or negative number, or 0 to begin ignoring the given event type. 

Format: AddCustomBucketParameter(integer bucketType, integer multiplier)

Returns: Nothing

Example usage: AddCustomeBucketParameter(Bucket_Kill,500) 
This will add 500 points to the custom (totaled) bucket for each kill the player gets.

SetCustomBucketName:

Allows you to set the name of the "custom" scoring bucket which will be displayed in the in-game score window.

	Format: SetCustomBucketName(string name)
	
	Returns: Nothing
	
	Example usage: SetCustomBucketName(“Kill Them All”);

AddPoints

Adds the specified number of multiplayer scoring points to the object(s) specified by who. This affects the "custom"-type score only. "Points" may be negative to subtract points. "Who" may optionally be a group or team. It is a very helpful command when making custom missions.

	Format: AddPoints(ObjectID who, integer points)

	Returns: Nothing

	Example usage: AddPoints(TeamObjectId(1), 500) or 
			 AddPoints(who_Killed), 500);