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')
)
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 thatBWAPI.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 theNuke
. If the target location is not visible andBWAPI.Flag.CompleteMapInformation
is disabled, then target will beBWAPI.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.
- player (BWAPI.Player) – The
-
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
.See also
-
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 anExtractor
, theDrone
is removed from the game and theVespene Geyser
morphs into anExtractor
.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.
See also
-
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.
See also
-
BWAPI.
onUnitMorph
(unit)¶ Called when a unit changes its
UnitType
.For example, when a
Drone
transforms into aHatchery
, aSiege Tank
usesSiege Mode
, or aVespene Geyser
receives aRefinery
.Parameters: unit (BWAPI.Unit) – The Unit
that just had itsUnitType
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, orfalse
if this is a RELEASE buildReturn 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 intofilter
.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 intofilter
.Return type: function
Classes¶
- Bullet
- BulletType
- BulletTypeset
- Bulletset
- Color
- DamageType
- DamageTypeset
- Error
- Errorset
- ExplosionType
- ExplosionTypeset
- Force
- Forceset
- Game
- GameType
- GameTypeset
- Order
- Orderset
- Player
- PlayerType
- PlayerTypeset
- Playerset
- Position
- Race
- Raceset
- Region
- Regionset
- TechType
- TechTypeset
- TilePosition
- Unit
- UnitCommand
- UnitCommandType
- UnitCommandTypeset
- UnitSizeType
- UnitSizeTypeset
- UnitType
- UnitTypeset
- Unitset
- UpgradeType
- UpgradeTypeset
- WalkPosition
- WeaponType
- WeaponTypeset