MapGoal

## Map Goal Properties

### CreateOnLoad

False to not create the goal at load time, but keep the data around for when created by the interface.

### DefaultPriority

Default priority of the goal, if no class/team specific priorities.

### DefaultRenderHeight

Goal height offset where rendering will take place.

### DefaultRenderRadius

Maximal distance from player to display text (goal options).

### DisableForControllingTeam

Goal will be made unavailable for the team which controls it (GetOwner). It is used by CHECKPOINT goal.

### DontSave

Don't save this goal into the map goal script.

### DynamicOrientation

Goal should update its orientation from its entity. It is used by BUILD goal to repair vehicles.

### DynamicPosition

Goal should update its position from its entity. It is used by BUILD goal to repair vehicles.

### ExtraDebugText

Additional debug text to render in RenderDefault function.

### RemoveWithEntity

Goal should be removed if its entity is removed. Default is true. It is used by FLAG, FLAGRETURN, DEFUSE goals.

### RenderDefaultCurrentAvailability

Draw the current availability of the goal.

### RenderDefaultInitialAvailability

Draw the initial availability of the goal.

### RenderGoal

Enable rendering for this goal. It is set by console command /bot draw\_goals

### RenderRandomUsePoint

Draw whether or not the goal randomly selects a usepoint.

### RenderRangeLimit

Draw whether or not the goal randomly selects a usepoint.

### RenderRoutes

Enable rendering of the routes for this goal. It is set by console command /bot draw\_goalroutes

**See:**
Routing

### RolePriorityBonus

Role priority bonus of the goal, for users matching role.

**See:**
Roles

### Version

Gets the goal version. Omni-bot 0.8 sets goal version to 1.

### SerialNum

Auto generated unique serial number of the goal.

## Map Goal Callbacks

### InitNewGoal

Called on goal creation (command /bot goal\_create) to initialize any internal variables and set properties to default values.
For example, camping goals can initialize aim vectors to the player facing.

### UpgradeVersion

Called after the goal properties have been loaded from a goals file. This function should validate schema and upgrade the goal to the latest used version.

### Render

Called when draw\_goals is enabled for this goal. Used to render itself.

### Update

Called every frame to update the state of the goal if needed. For example, GRENADE goal calls TraceLine function to check if the goal has been destroyed.

### SaveToTable

Called when the goals are saved to a file. Allows the goal to serialize persistent information.

### SetProperty

Called on command /bot goal\_setproperty x y, where x is a property name and y is a value or keyword.

### Help

Called on commands /bot goal\_help or /bot goal\_create to print requirements and available properties for the goal.

### HudDisplay

Called when debug window is enabled and goal is highlighted to create gui elements for debug visualization.

## Map Goal Functions

### AddRoute

**See:**
Routing

**Parameters:** (start, end, weight)

**Returns:** none

**Example:**

```
 mg.AddRoute("ROUTE\_spawn", "ROUTE\_gate", 1.0);

```

**Utility function:** Util.Routes

### AddUsePoint

Adds a use point to the goal. Use points are used by RouteTo function. The goal can have multiple use points. Bots choose the nearest use point if goal property RandomUsePoint is false.

**Parameters:** (Vector3, relative[optional, default false])

**Returns:** none

**Example:**

```
 mg.AddUsePoint(Vector3(10,50,0), true);

```

**Utility functions:** Util.AddUsePoint, Util.AddUseWp

### ClearRoles

Removes the given roles from this goal.

**Parameters:** (roleId, ...)

**Returns:** none

**Example:**

```
 mg.ClearRoles(ROLE.DEFENDER1, ROLE.DEFENDER2);

```

**Utility functions:** ClearGoalRole, Util.ClearRoleForGroup, Util.ClearRoleForTable

**See:** Roles

### CreateGuiFromSchema

Used in HudDisplay callback if debug window is enabled.

**Example:**

```
 this.CreateGuiFromSchema(this.Schema);

```

### DeleteIfEntityFlag

Sets one or more entity flags that will cause the goal to be deleted.

**Parameters:** (entFlagId, ...)

**Returns:** none

**Example:**

```
 mg.DeleteIfEntityFlag(ENTFLAG.DISABLED);

```

### DisableGoal

Sets whether the goal is currently disabled.

**Parameters:** (true/false)

**Returns:** none

**Example:**

```
 mg.DisableGoal(true);

```

### DisableIfEntityFlag

Sets one or more entity flags that will cause the goal to be disabled.

**Parameters:** (entFlagId, ...)

**Returns:** none

**Example:**

```
 mg.DisableIfEntityFlag(ENTFLAG.DISABLED);

```

### GetCenterBounds

Gets the center of the bounding box.

**Parameters:** none

**Returns:** Vector3

**Example:**

```
 center = mg.GetCenterBounds();

```

### GetEntity

Gets the entity of the map goal.

**Parameters:** none

**Returns:** GameEntity

**Example:**

```
 ent = mg.GetEntity();

```

### GetFacing

Gets the facing of the map goal.

**Parameters:** none

**Returns:** Vector3 facing

**Example:**

```
 face = mg.GetFacing();

```

### GetGoalPriority

Gets the priority for a given class/team. Default priority is returned if class or team is 0.

If the parameter is bot, role priority bonus is added if the bot has any of the goals roles.

**Parameters:** (bot)

**Parameters:** (teamId, classId)

**Returns:** float

**Example:**

```
 priority = mg.GetGoalPriority(bot);
 // OR
 priority = mg.GetGoalPriority(TEAM.AXIS,CLASS.MEDIC);

```

### GetGoalState

Gets the goal state of the map goal.

**Parameters:** none

**Returns:** goal state id

**Example:**

```
 state = mg.GetGoalState();

```

### GetGoalType

Gets goal type. Examples: Attack, BUILD, CapPoint, PLANT.

**Parameters:** none

**Returns:** string

**Example:**

```
 type = mg.GetGoalType();

```

### GetGroupName

Gets the current group this goal is assigned to.

**Parameters:** none

**Returns:** string

**Example:**

```
 group = mg.GetGroupName();

```

### GetName

Gets the name of the map goal.

**Parameters:** none

**Returns:** name of mapgoal

**Example:**

```
 name = mg.GetName();

```

### GetNumUsePoint

Gets the number of use points the goal has.

**Parameters:** none

**Returns:** # use points

**Example:**

```
 n = mg.GetNumUsePoint();

```

### GetOwner

Gets the owner of the map goal. Typically someone that is carrying it.

**Parameters:** none

**Returns:** Owner GameId, or null if no owner

**Example:**

```
 owner = mg.GetOwner();

```

### GetPosition

Gets the position of the map goal.

**Parameters:** none

**Returns:** Vector3 position

**Example:**

```
 pos = mg.GetPosition();

```

### GetRadius

Gets the radius of the map goal.

**Parameters:** none

**Returns:** float radius

**Example:**

```
 radius = mg.GetRadius();

```

### GetTagName

Gets the tag name of the map goal. This is usually a mash of the entity name and goal type.

**Parameters:** none

**Returns:** tag name

**Example:**

```
 tag = mg.GetTagName();

```

### GetTypeName

Gets the type name of the map goal.

**Parameters:** none

**Returns:** type name

**Example:**

```
 type = mg.GetTypeName();

```

### GetUsePoint

Gets a use point, by index. If no index provided, returns a random one.

**Parameters:** (index<optional>)

**Returns:** Vector3 use point

**Example:**

```
 pt = mg.GetUsePoint();
 // OR
 pt = mg.GetUsePoint(2);

```

### HasRole

Returns true if the goal has any of the roles provided as parameters.

**Parameters:** (roleId, ...)

**Returns:** true/false

**Example:**

```
 if(mg.HasRole(ROLE.ATTACKER))
 {
 }

```

**See:** Roles

### IsAvailable

Checks if the map goal is currently available to a certain team.

**Parameters:** (team id)

**Returns:** true if goal is available for team, false if not

**Example:**

```
 if(mg.IsAvailable(TEAM.RED))
 {
 }

```

### IsAvailableInitial

Is goal available for team initially (before OnMapLoad is executed).

**Parameters:** (team id)

**Returns:** true if goal is available for team, false if not

**Example:**

```
 if (mg.IsAvailableInitial(TEAM.RED))
 {
 }

```

### IsDisabled

Gets whether the goal is currently disabled.

**Parameters:** none

**Returns:** true/false

**Example:**

```
 if(mg.IsDisabled())
 {
 }

```

### LimitToWeapon

Adds a list of weapons that are required from any user of the goal.

Warning: This function does not work for weapons that have ID greater than 63.

**Parameters:** (weaponId, ...)

**Returns:** none

**Example:**

```
 mg.LimitToWeapon(WEAPON.FG42);

```

### MaxUsers\_InProgress

Get or set the max number of users that can go to the goal.

**Parameters:** none or (integer)

**Returns:** integer

**Example:**

```
 num = mg.MaxUsers\_InProgress();
 // OR
 mg.MaxUsers\_InProgress(2);

```

**Utility functions:** Util.SetMaxUsers, Util.SetMaxUsersInProgress, Util.GetMaxUsersInProgress, Util.SetPercentInProgress

### MaxUsers\_InUse

Get or set the max number of users that can use the goal after they come to the goal position.

**Parameters:** none or (integer)

**Returns:** integer

**Example:**

```
 num = mg.MaxUsers\_InUse();
 // OR
 mg.MaxUsers\_InUse(1);

```

**Utility functions:** Util.SetMaxUsers, Util.SetMaxUsersInUse, Util.GetMaxUsersInUse

### RenderDefault

Draws goal name, radius, availability, use points, ExtraDebugText, ...

**Parameters:** none

**Returns:** none

**Example:**

```
 mg.RenderDefault();

```

### ResetGoalPriorities

Clears all the current priorities.

**Parameters:** none

**Returns:** none

**Example:**

```
 mg.ResetGoalPriorities();

```

### SetAvailable

Sets the map goal available for a certain team.

NOTE: Map scripts usually use global function SetAvailableMapGoals instead of calling SetAvailable directly on map goal object.

**Parameters:** (team id, true/false)

**Returns:** none

**Example:**

```
 mg.SetAvailable(TEAM.RED, false);

```

### SetAvailableInitial

Sets goal available for team initially.

**Parameters:** (team id, true/false)

**Returns:** none

**Example:**

```
 mg.SetAvailableInitial(TEAM.AXIS, true);

```

### SetBaseGoalType

Clones a base goal type. Should be done first thing in goal script.

**Parameters:** (fileName)

**Returns:** none

**Example:**

```
 this.SetBaseGoalType("mapgoal\_camp.gm");

```

### SetBounds

Sets the bounds for a map goal. This is the local space bounds. It will automatically be transformed to the world position of the map goal.

**Parameters:** (AABB)

**Returns:** none

**Example:**

```
 AABB aabb;
 // initialize it somehow
 mg.SetBounds(aabb);

```

### SetEntity

Sets the entity for a map goal. It is usually not needed because most entities are detected automatically.

**Parameters:** (entity)

**Returns:** none

**Example:**

```
 GetGoal("MOUNTMG42\_assault\_tower\_mg").SetEntity(GetEntityByName("assault\_tower\_mg"));;

```

### SetFacing

Sets the facing for a map goal.

**Parameters:** (Vector3)

**Returns:** none

**Example:**

```
 mg.SetFacing(Vector3(1,0,0));

```

### SetGoalPriority

Sets the priority for a given class/team. The first parameter can be 0 to set priority for all teams. The second parameter can be 0 to set priority for all classes.

NOTE: Map scripts usually use global function SetGoalPriority instead of calling SetGoalPriority directly on map goal object.

**Parameters:** (teamId, classId, priority)

**Returns:** none

**Example:**

```
 mg.SetGoalPriority(TEAM.ALLIES, CLASS.SOLDIER, 0.8);

```

### SetGroupName

Sets the current group this goal is assigned to.

**Parameters:** (groupName)

**Returns:** none

**Example:**

```
 mg.SetGroupName("group1");

```

### SetPosition

Sets the position for a map goal.

**Parameters:** (Vector3)

**Returns:** none

**Example:**

```
 mg.SetPosition(Vector3(10,10,10));

```

### SetRadius

Sets the radius for a map goal.

**Parameters:** (radius)

**Returns:** none

**Example:**

```
 mg.SetRadius(65);

```

### SetRange

Sets the range for a script based map goal. The QueryGoals functions does not return goals which are out of range. Default range for all goals is 0 which means unlimited. Goals will not be interrupted if the range changes after the bot has activated the goal.

**Parameters:** (range)

**Returns:** none

**Example:**

```
 mg.SetRange(1000);

```

**Utility function:** Util.SetGoalRange

### SetRemoveFlag

Marks the goal for removal.

**Parameters:** (true/false)

**Returns:** none

**Example:**

```
 mg.SetRemoveFlag(true);

```

### SetRoles

Sets the roles that are allowed to use this goal.

**Parameters:** (roleId, ...)

**Returns:** none

**Example:**

```
 mg.SetRoles(ROLE.DEFENDER);

```

**Utility functions:** SetGoalRole, Util.SetRoleForGroup, Util.SetRoleForTable

**See:** Roles

## Obsolete Functions

### GetBounds

Gets the AABB bounds of the map goal.

**Parameters:** none

**Returns:** AABB

**Example:**

```
 bounds = mg.GetBounds();

```

### GetLocalBounds

Gets the local space bounds of the map goal.

**Parameters:** none

**Returns:** AABB bounds

**Example:**

```
 localbounds = mg.GetLocalBounds();

```

### GetMatrix

Gets the Matrix3 transform of the map goal.

**Parameters:** none

**Returns:** Matrix3 transform

**Example:**

```
 m = mg.GetMatrix();

```

### SetEnableDraw

Enables debug rendering for this map goal.

**Parameters:** (true/false)

**Returns:** none

**Example:**

```
 mg.SetEnableDraw(true);

```

### SetMatrix

Sets the matrix for a map goal.

**Parameters:** (Matrix3)

**Returns:** none

**Example:**

```
 m = Matrix3();
 // initialize it somehow
 mg.SetMatrix(m);

```