The BWAPI Module

The BWAPI bindings are all loaded into the BWAPI module, which is loaded as BWAPI into the global environment and can also be found in the "BWAPI" key in package.loaded (retrieved by doing require('BWAPI'))

Constants

BWAPI.Broodwar

The currently running Game instance

Callbacks

Note

Replays are considered games and call all of the same callbacks as a standard game would.

BWAPI.onStart()

Called only once at the beginning of a game.

It is intended that the AI module do any data initialization in this function.

Note

init.lua is loaded with the same environment that BWAPI.onStart() is called with, so the use of this callback is optional

BWAPI.onFrame()

Called once for every execution of a logical frame in Broodwar.

Users will generally put most of their code in this function.

BWAPI.onEnd(isWinner)

Called once at the end of a game.

Parameters:isWinner (boolean) – A boolean value to determine if the current player has won the match. This value will be true if the current player has won, and false if either the player has lost or the game is actually a replay.
BWAPI.onError(msg)

If defined, then all Lua error messages will be redirected to this function (instead of the default functionality of the error message being printed to the screen). Can be used for custom error handling/logging errors to file/etc.

Parameters:msg (string) – The error message.
-- cwd is the StarCraft .exe directory, so this is relative to that
-- make sure that the target directory exists!
local logFilePath = "bwapi-data/lua-ai-example-error.log"

function BWAPI.onError(msg)
  -- print to the screen
  print(msg)

  -- RFC1123 date
  local fmt = "!%a, %d %b %Y %T GMT"
  local date = os.date(fmt)

  -- log to file
  local log = io.open(logFilePath, "a")
  local str = string.format("[%s] %s\n", date, msg)
  log:write(str)
  log:close()
end

function BWAPI.onStart()
  -- lets trigger an error!
  local missing = nil
  print(missing.index)
end
BWAPI.onNukeDetect(target)

Called when a Nuke has been launched somewhere on the map.

Parameters:target (BWAPI.Position) – A Position containing the target location of the Nuke. If the target location is not visible and BWAPI.Flag.CompleteMapInformation is disabled, then target will be BWAPI.Positions.Unknown.
BWAPI.onPlayerLeft(player)

Called when a Player leaves the game.

All of their units are automatically given to the neutral player with their colour and alliance parameters preserved.

Parameters:player (BWAPI.Player) – The Player that has left the game.
BWAPI.onReceiveText(player, text)

Called when the client receives a message from another Player.

This function can be used to retrieve information from allies in team games, or just to respond to other players.

Parameters:
  • player (BWAPI.Player) – The Player that sent the message.
  • text (string) – The text message that the player sent.
BWAPI.onSaveGame(gameName)

Called when the state of the Broodwar game is saved to file.

Parameters:gameName (string) – The file name that the game was saved as
BWAPI.onSendText(text)

Called when the user attempts to send a text message.

This function can be used to make the bot execute text commands entered by the user for debugging purposes.

Parameters:text (string) – The exact text message that was sent by the user.

Note

If BWAPI.Flag.UserInput is disabled, then this function is not called.

-- very basic REPL using the text entered by the client
-- any syntax/execution errors are handled by the default error handler,

function BWAPI.onStart()
  BWAPI.Broodwar:enableFlag(BWAPI.Flag.UserInput)
  print("Anything you type will be executed as Lua!")
end

function BWAPI.onSendText(text)
  -- execute the text as Lua and print the result
  local fn = assert(loadstring(text))
  local ret = {fn()}
  if #ret > 0 then
    print(unpack(ret))
  end
end
BWAPI.onUnitComplete(unit)

Called when the state of a unit changes from incomplete to complete.

Parameters:unit (BWAPI.Unit) – The Unit that has been completed.
BWAPI.onUnitCreate(unit)

Called when any unit is created.

Parameters:unit (BWAPI.Unit) – The Unit that has just been created.

Note

Due to the internal workings of Broodwar, this function excludes Zerg morphing and the construction of structures over a Vespene Geyser.

BWAPI.onUnitDestroy(unit)

Called when a unit is removed from the game either through death or other means.

Parameters:unit (BWAPI.Unit) – The Unit that has just been destroyed or otherwise completely removed from the game.

Note

When a Drone morphs into an Extractor, the Drone is removed from the game and the Vespene Geyser morphs into an Extractor.

Note

If a unit is visible and destroyed, then BWAPI.onUnitHide() is called just before this.

BWAPI.onUnitDiscover(unit)

Called when a Unit becomes accessible.

Parameters:unit (BWAPI.Unit) – The Unit that has just become accessible.

Note

This function INCLUDES the state of BWAPI.Flag.CompleteMapInformation.

See also

BWAPI.onUnitShow()

BWAPI.onUnitEvade(unit)

Called when a Unit becomes inaccessible.

Parameters:unit (BWAPI.Unit) – The Unit that has just become inaccessible.

Note

This function INCLUDES the state of BWAPI.Flag.CompleteMapInformation.

BWAPI.onUnitHide(unit)

Called just as a visible unit is becoming invisible.

Parameters:unit (BWAPI.Unit) – The Unit that is about to go out of scope.

Note

This function EXCLUDES the state of BWAPI.Flag.CompleteMapInformation.

BWAPI.onUnitMorph(unit)

Called when a unit changes its UnitType.

For example, when a Drone transforms into a Hatchery, a Siege Tank uses Siege Mode, or a Vespene Geyser receives a Refinery.

Parameters:unit (BWAPI.Unit) – The Unit that just had its UnitType change.

Note

This is NOT called if the unit type changes to or from Unknown.

Functions

static BWAPI.print(text)

Prints the text to the client chat window, with no owner

Parameters:text (string) – The text to be printed

Note

This function does not automatically append a newline to the output

static BWAPI.getRevision()

Retrieves the revision of the BWAPILIB module currently being used.

Returns:An integer representing the revision number of the library.
Return type:number
static BWAPI.isDebug()

Checks if the BWAPILIB module was compiled in DEBUG mode.

Returns:true if this is a DEBUG build, or false if this is a RELEASE build
Return type:boolean
static BWAPI.Lowest(filter) → bestFilter

Takes a comparison filter (or similar function) and converts it into a ‘best’ function intended for use with Game.getBestUnit().

Parameters:filter (function) – A function that takes a Unit and returns a value that will be used for comparison. The returned value must be of a type that can be compared using the less than operator.
Returns:A function that takes two Unit objects, and returns the object with the lowest value returned when passing it into filter.
Return type:function
static BWAPI.Highest(filter) → bestFilter

Takes a comparison filter (or similar function) and converts it into a ‘best’ function intended for use with Game.getBestUnit().

Parameters:filter (function) – A function that takes a Unit and returns a value that will be used for comparison. The returned value must be of a type that can be compared using the greater than operator.
Returns:A function that takes two Unit objects, and returns the object with the highest value returned when passing it into filter.
Return type:function