Region.rst

Region

BWAPI

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.

Game.getAllRegions, Game.getRegionAt, Unit.getRegion

Constructors

This class is not constructable through Lua.

Member Variables

Member Functions

getBoundsBottom() -> int

Retrieves the approximate bottom boundary of the region.

return

The y coordinate, in pixels, of the approximate bottom boundary of the region.

rtype

int

getBoundsLeft() -> int

Retrieves the approximate left boundary of the region.

return

The x coordinate, in pixels, of the approximate left boundary of the region.

rtype

int

getBoundsRight() -> int

Retrieves the approximate right boundary of the region.

return

The x coordinate, in pixels, of the approximate right boundary of the region.

rtype

int

getBoundsTop() -> int

Retrieves the approximate top boundary of the region.

return

The y coordinate, in pixels, of the approximate top boundary of the region.

rtype

int

getCenter() -> Position

Retrieves the center of the region.

This position is used as the node of the region.

return

A Position indicating the center location of the Region, in pixels.

rtype

BWAPI.Position

getClosestAccessibleRegion() -> Region

Retrieves the closest accessible neighbor region.

return

The closest Region that is accessible.

rtype

BWAPI.Region

getClosestInaccessibleRegion() -> Region

Retrieves the closest inaccessible neighbor region.

return

The closest Region that is inaccessible.

rtype

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.

return

An integer indicating this region's strategic potential.

rtype

int

Note

This value is explicitly assigned by Broodwar.

getDistance(other) -> int

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

param BWAPI.Region other

The target Region to calculate distance to.

return

The integer distance from this Region to other.

rtype

int

Note

Ignores all collisions.

getID() -> int

Retrieves a unique identifier for this region.

return

An integer that represents this region.

rtype

int

Note

This identifier is explicitly assigned by Broodwar.

Game.getRegion

getNeighbors() -> Regionset

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

return

A reference to a ~BWAPI.Regionset containing the neighboring Regions.

rtype

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.

return

An integer that represents the group of regions that this one is attached to.

rtype

int

Note

This identifier is explicitly assigned by Broodwar.

getUnits([pred = nil]) -> Unitset

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

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

param function pred

(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 <unary-filters>). Defaults to nil, which means no filter.

return

A ~BWAPI.Unitset containing all units in this region that have met the requirements of pred.

rtype

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.

return

true if ground units can traverse this region, and false if the tiles in this region are inaccessible or unwalkable.

rtype

boolean

isHigherGround() -> boolean

Checks if this region is part of higher ground.

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

return

true if this region is part of strategic higher ground, and false otherwise.

rtype

boolean