MapGoal

Script Reference

MapGoal Functions

Map Goal Properties

---

CreateOnLoad

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

---

DefaultPriority

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

---

DefaultRenderHeight

Goal height offset where rendering will take place.

---

DefaultRenderRadius

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

---

DisableForControllingTeam

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

---

DontSave

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

---

DynamicOrientation

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

---

DynamicPosition

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

---

ExtraDebugText

Additional debug text to render in RenderDefault function.

---

GoalState

Gets the goal state.

---

GoalStateFunction

internal

---

GoalType

Type of goal.

---

InUse

Goal is inuse and should not be chosen.

---

MarkForRemoval

Mark the goal for deletion.

---

MinRadius

Minimum allowed radius of the goal.

---

Radius

Radius of the goal.

---

RemoveWithEntity

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

---

RenderDefaultCurrentAvailability

Draw the current availability of the goal.

---

RenderDefaultGroup

Draw the group of the goal.

---

RenderDefaultInitialAvailability

Draw the initial availability of the goal.

---

RenderDefaultName

Draw the name of the goal.

---

RenderDefaultRadius

Draw the radius of the goal.

---

RenderDefaultRole

Draw the roles for the goal.

---

RenderGoal

Enable rendering for this goal. It is set by console command /bot draw_goals

---

RenderRandomUsePoint

Draw whether or not the goal randomly selects a usepoint.

---

RenderRangeLimit

Draw whether or not the goal randomly selects a usepoint.

---

RenderRoutes

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

See: 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 or table)

Returns: none

Example:

 mg.SetRoles(ROLE.DEFENDER);

Utility functions: SetGoalRole, Util.SetRoleForGroup

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

---