Region

class BWAPI.Region

Region objects are created by Starcraft: Broodwar to contain several tiles with the same properties, and create a node in pathfinding and other algorithms.

Regions may not contain detailed information, but have a sufficient amount of data to identify general chokepoints, accessibility to neighboring terrain, be used in general pathing algorithms, and used as nodes to rally units to.

Most parameters that are available are explicitly assigned by Broodwar itself.

See also

Game.getAllRegions(), Game.getRegionAt(), Unit.getRegion()

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

getBoundsBottom() → int

Retrieves the approximate bottom boundary of the region.

Returns:The y coordinate, in pixels, of the approximate bottom boundary of the region. Return type:int

getBoundsLeft() → int

Retrieves the approximate left boundary of the region.

Returns:The x coordinate, in pixels, of the approximate left boundary of the region. Return type:int

getBoundsRight() → int

Retrieves the approximate right boundary of the region.

Returns:The x coordinate, in pixels, of the approximate right boundary of the region. Return type:int

getBoundsTop() → int

Retrieves the approximate top boundary of the region.

Returns:The y coordinate, in pixels, of the approximate top boundary of the region. Return type:int

getCenter() → Position

Retrieves the center of the region.

This position is used as the node of the region.

Returns:A Position indicating the center location of the Region, in pixels. Return type:BWAPI.Position

getClosestAccessibleRegion() → Region

Retrieves the closest accessible neighbor region.

Returns:The closest Region that is accessible. Return type:BWAPI.Region

getClosestInaccessibleRegion() → Region

Retrieves the closest inaccessible neighbor region.

Returns:The closest Region that is inaccessible. Return type:BWAPI.Region

getDefensePriority() → int

Retrieves a value that represents the strategic advantage of this region relative to other regions.

A value of 2 may indicate a possible choke point, and a value of 3 indicates a signficant strategic position.

Returns:An integer indicating this region’s strategic potential. Return type:int

Note

This value is explicitly assigned by Broodwar.

getDistance(other) → int

Retrieves the center-to-center distance between two regions.

Parameters:other (BWAPI.Region) – The target Region to calculate distance to. Returns:The integer distance from this Region to other. Return type:int

Note

Ignores all collisions.

getID() → int

Retrieves a unique identifier for this region.

Returns:An integer that represents this region. Return type:int

Note

This identifier is explicitly assigned by Broodwar.

See also

Game.getRegion()

getNeighbors() → Regionset

Retrieves the set of neighbor Regions that this one is connected to.

Returns:A reference to a Regionset containing the neighboring Regions. Return type:BWAPI.Regionset

getRegionGroupID() → int

Retrieves a unique identifier for a group of regions that are all connected and accessible by each other.

That is, all accessible regions will have the same group ID. This function is generally used to check if a path is available between two points in constant time.

Returns:An integer that represents the group of regions that this one is attached to. Return type:int

Note

This identifier is explicitly assigned by Broodwar.

getUnits([pred = nil]) → Unitset

Retrieves a Unitset containing all the units that are in this region.

Also has the ability to filter the units before the creation of the Unitset.

Parameters:pred (function) – (optional) A predicate function that takes a Unit and returns true for units that satisfy the intended filter and false otherwise (can be a BWAPI.Filter unary filter). Defaults to nil, which means no filter. Returns:A Unitset containing all units in this region that have met the requirements of pred. Return type:BWAPI.Unitset

isAccessible() → boolean

Retrieves the state of accessibility of the region.

The region is considered accessible if it can be accessed by ground units.

Returns:true if ground units can traverse this region, and false if the tiles in this region are inaccessible or unwalkable. Return type:boolean

isHigherGround() → boolean

Checks if this region is part of higher ground.

Higher ground may be used in strategic placement of units and structures.

Returns:true if this region is part of strategic higher ground, and false otherwise. Return type:boolean

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.