Force

class BWAPI.Force

The Force class is used to get information about each force in a match.

Normally this is considered a team.

Note

It is not called a team because players on the same force do not necessarily need to be allied at the beginning of a match.

Constructors

This class is not constructable through Lua.

Member Variables

clientInfo

A Lua table that can be used to store arbitrary data associated with the current object.

Example usage

obj.clientInfo["test"] = 5
print(obj.clientInfo["test"]) -- prints "5"

See also

The differences between the C++ and Lua implementations

Member Functions

getID() → int

Retrieves the unique ID that represents this Force.

Returns:An integer containing the ID for the Force. Return type:int

getName() → string

Retrieves the name of the Force.

Returns:A string containing the name of the force. Return type:string

Example usage

local myForce = BWAPI.Broodwar:self():getForce()
if myForce:getName() == "Observers" then
  print("Looks like we're observing a match")
end

getPlayers() → set

Retrieves the set of players that belong to this Force.

Returns:A Playerset object containing the players that are part of this Force. Return type:BWAPI.Playerset

Example usage

-- Get the enemy force, but make sure we have an enemy
if BWAPI.Broodwar:enemy() then
  local myEnemyForce = BWAPI.Broodwar:enemy():getForce()
  print("The allies of my enemy are...")
  for ally in myEnemyForce:iterator() do
    print("  - " .. ally:getName())
  end
end

registerEvent(action[, condition = nil][, timesToRun = -1][, framesToCheck = 0])

Registers an event and associates it with the current object.

Events can be used to automate tasks (like train X Marines until Y of them have been created by the given Barracks) or to create user-defined callbacks.

Parameters:

• action (function) – The callback to be executed when the event conditions are true.
• condition (function) – (optional) The condition callback which will return true if the action is intended to be executed. The condition will always be true if omitted.
• timesToRun (int) – (optional) The number of times to execute the action before the event is removed. If the value is negative, then the event will never be removed. The value will be -1 if omitted, causing the event to execute until the game ends.
• framesToCheck (int) – (optional) The number of frames to skip between checks. If this value is 0, then a condition check is made once per frame. If this value is 1, then the condition for this event is only checked every other frame. This value is 0 by default, meaning the event’s condition is checked every frame.