OpprimoBot - AIGuy.org

OpprimoBot Project Documentation
Version:
Release date:
Project manager:
Project homepage:
License:
15.2
February 18:th, 2015
Johan Hagelbäck (johan.hagelback@gmail.com)
http://code.google.com/p/bthai
MIT
1
Introduction
OpprimoBot (previously known as BTHAI) is a fully featured AI bot for the RTS game StarCraft:Broodwar.
It uses the BWAPI project 1 to communicate with the StarCraft engine, and the BWTA2 project 2 for
analysing maps.
This document contains all information you need to install, use and develop with OpprimoBot.
You are free to use the bot as a basis for your own StarCraft bot projects. The only requirement is that
if you publish any articles about your work, you must add the following reference:
Johan Hagelbäck. "Potential-Field Based navigation in Starcraft". In
Proceedings of 2012 IEEE Conference on Computational Intelligence
and Games (CIG), 2012.
Source code and binaries can be download from the project webpage 3 If you are interested in
contributing to the project, don’t hesitate to contact the project manager. OpprimoBot currently uses
the 4.1.0-Beta version of BWAPI.
2
Installing and using the bot
Follow these step-by-step instructions to install the bot:
1. Install StarCraft and the Broodwar expansion. If you don’t have a copy, you can buy and
download from Battle.net.
2. Upgrade StarCraft:Broodwar to version 1.16.1.
3. Your Windows user must have full access to the StarCraft directory. You can check it by rightclicking on the StarCraft folder and select Properties. Go to the Security tab and make sure
your user have a check mark in the Allow column in the Full control row (see left screenshot
below).
4. Download OpprimoBot from the project homepage (if you haven’t done so already). If you
wish to develop with OpprimoBot choose the source version, otherwise the binary version.
5. Un-zip the contents of the zip-file to your harddrive. Open the StarCraft folder.
6. Copy the bwapi-data folder to your StarCraft installation directory.
7. Copy the Chaoslauncher folder to your StarCraft installation directory.
8. If you have downloaded the source version, copy the OpprimoBot folder to your StarCraft
installation directory.
9. Copy the contents of the WINDOWS folder to your Windows installation directory, usually
C:/Windows/.
10. Go to the Chaoslauncher folder and right-click on Chaoslauncher.exe, select Properties. Go to
the Compatibility tab and select the Run this program as an administrator checkbox. Click OK
(see right screenshot below).
1
BWAPI - https://github.com/bwapi/bwapi
BWTA2 - https://bitbucket.org/auriarte/bwta2
3
Project webpage - http://code.google.com/p/bthai
2
2
11. Run Chaoslauncher.exe. Go to the Settings tab and change the StarCraft install path to your
StarCraft installation directory. Sometimes a warning window about incorrect side-by-side
configuration is shown. Just close it.
12. Go to the Plugin tabs in Chaoslauncher. Select the BWAPI Injector (1.16.1) RELEASE and the
W-MODE 1.02 checkboxes.
13. Click the Start button in Chaoslauncher. If everything has been installed correctly a game
should automatically be started with the bot playing against the built-in AI. If it is the first time
you start StarCraft, you need to skip the video sequence before the game is started.
In the bwapi-data/bwapi.ini file you can change the game type, map, and race (Terran, Protoss
or Zerg) for the bot and the opponent. OpprimoBot can play all three races, but is strongest when
playing Terrans.
2.1
Installing development tools
The OpprimoBot source project requires Visual Studio 2013. You can use the free Express version
which can be downloaded from Microsoft’s website (or another download service).
When you have installed Visual Studio, open the SCProjects solution in the Opprimobot/SCProjects
folder. The project files contain links to libraries and header files so you should be able to compile
the project without any changes. The output file OpprimoBot.dll will automatically be placed in the
bwapi-data/AI folder.
3
3
Bot visualization system
OpprimoBot has an extensive visualization system where lots of information about what the bot is
doing are shown.
3.1
Main information panels
The visualization system contains four main information panels (Techs/upgrades, Squads, Strategy
Plan and Next to build/In progress) as seen in the screenshot below. It also contains information
about bot version (top left corner), a game timer, current strategy (the bot switches between a few predefined strategies), and which pathfinding system currently is in use (bottom right corner). Strategies
and pathfinding systems will be explained in more detail in later chapters of this document.
Strategy Plan
The Strategy Plan panel shows information about the next four buildings or upgrades the bot plans to
do. It also shows when they are planned (at which supply, for example @50 means when the supply
is 50 or more). The panel can be toggled on and off by writing b in the terminal (press Enter, write a
b, press Enter again).
Next to build/In progress
This panel shows buildings that are waiting to be constructed (Next to build) and buildings that are
currently being constructed (In progress). It can be toggled on and off by writing b in the terminal.
Techs/Upgrades
This panel shows all technologies that have been researched and all upgrades that have been constructed. In case of upgrades, it also shows the level (current/max) of the upgrade. It can be toggled
4
on and off by writing t in the terminal.
Squads
This panel shows all the squads (a squad is a group of units) the AI has, and if the AI is in a Defending
or Attacking state. Each squad is listed with SQ and the squad id number, the current number of units
in the squad and the total number of units when the squad is full. Squads marked with a * is Required.
When all Required squads are full the bot goes into Attacking state and launches an attack on the
opponent. The panel can be toggled on and off by writing s in the terminal.
5
3.2
Unit/structure panel
When selecting a unit or building an information panel is shown. The panel can be toggled on and off
by writing i in the terminal.
The screenshot shows an example of the information panel when a Protoss Dragoon is selected.
The following information is shown:
• Id. BWAPI id number of the unit.
• Position. The current position (in tiles) for the unit.
• Goal. The current goal to move to (in tiles).
• Squad. The squad number of the squad the unit belongs to (or None if the unit does not belong
to a squad).
• Range. The visibility range of the unit (highest value of seek range and sight range).
• Enemies seen. Number of enemy units within range.
• Attacking. If the unit is currently attacking or not.
• Ground CD. Cooldown left until the unit’s ground weapon is ready to fire, or Ready if the unit
can attack. Only shown if the unit can attack ground targets.
• Air CD. Cooldown for the unit’s air weapon. Only shown if the unit can attack air targets.
• Target. The unit type of the unit’s current target, or blank if the unit does not have a target.
• Defensive. If the unit is in a defensive state or not. Defensive units typically kite and keep
distance to enemy targets.
6
The upper screenshot shows an example of the information panel when a Terran Bunker is selected. The panel shows the BWAPI id number of the building, the position (in tiles) and squad id
number if the building belongs to a squad (Terran Bunkers only). In case of Terran Bunkers, the units
inside the bunker are listed with type and BWAPI unit id.
The lower screenshot shows an example of the information panel when a worker unit is selected.
It also shows the current state (a worker is implemented using a finite state machine) for the worker
unit.
7
3.3
Squad panel
An information panel for each squad can be shown by writing sq# in the terminal, where # is the
squad id (see the Squads main panel). Writing sq in the terminal closes the panel.
The following information is shown:
• Id. Squad id number.
• Goal. The current navigation goal of the squad (in tiles). The actual goal position is marked on
the map with a grey circle and yellow text showing SQ and squad id (to the left in the figure).
• Type. Squads can be Air or Ground, and Offensive/Defensive/Exploration/Rush/BunkerDefend.
• Priority. Current priority of the squad. No units are added to a squad unless all squads with
lower priority are filled.
• Required. If the squad is Required or not (see the Squads main panel for more information
about required squads).
• Full. If the squad is full (all units in the squad have been created) or not.
• Active. If the squad is active (ready to execute orders) or not. Once a squad is full it is set to
active. It is switched back to inactive when 90% or more of its units are destroyed.
The lower part of the panel shows the types of units in the squad, the current number of a unit type
and the maximum number of units of each type.
8
3.4
Placing new buildings
Information about where new buildings are planned to be placed can be toggled on and off by writing
bp in the terminal. All tiles that are already occupied by buildings or terrain are marked with brown
squares. Available tiles are not marked. In the upper screenshot a worker has decided where to place
a new Terran Barracks building. The tiles that are to be occupied by the new building are temporary
blocked (marked with green squares).
In the lower screenshot the worker has started to construct the Terran Barracks. The tiles are now
blocked and are marked with brown squares. Note that the Terran Supply Depot blocks very few tiles,
while the Command Center and Barracks has at least one tile free space around them. The reason is
to avoid placing buildings that can construct units too close to each other, and some Terran buildings
also need space to place addons at.
9
3.5
Progress bars
The information visualization system shows a number of progress bars to get a good overview of
what is going on in a base. The screenshot shows orange progress bars placed over minerals and the
Refinery. They show the amount of minerals/gas left in the resource. The Command Center has a
blue bar showing the progress of creating a new Terran SCV worker unit. In the bottom right corner
of the screenshot a blue bar shows the progress of creating a new building.
The second screenshot shows a green progress bar on top of a Terran Bunker, displaying the
number of units loaded in the bunker.
10
3.6
Navigation system
OpprimoBot uses a hybrid pathfinding system where the standard pathfinding algorithm in StarCraft
is combined with either potential fields 4 or flocking with boids algoritms 5 . The system works as
follows:
• When no enemy unit or building is within sight range of a unit, the unit uses the built-in
pathfinding system in Starcraft. The information visualization show the goals of selected units
with light-green lines (see screenshot below), or red lines for units that have a target. To avoid
spreading our the units in a squad, the squad gathers up at several waypoints along the path to
the goal.
• When at least one enemy unit or building is within sight range, the bot switches to use potential
fields or boids algorithms for pathfinding.
You can switch between built-in pathfinding only, hybrid pathfinding with boids or hybrid pathfinding
with potential fields by writing spf in the terminal.
When using the potential fields version of the hybrid pathfinding system, a visualization of the potential fields for a selected unit can be toggled on and off by writing pf in the terminal (see screenshot
below). In the visualization attracting areas are shown in blue, and lighter blue are more attracting
than darker blue. Repelling areas are shown in red, and lighter red are more repelling than darker red.
Areas without any influence are shown in black.
4
5
Tutorial about potential fields - aigamedev.com/open/tutorials/potential-fields/
Introduction to boids - http://www.kfish.org/boids/pseudocode.html
11
4
Source code overview
As seen in the screenshot the source code is organized into a number of modules. Each module is
responsible for a sub-part of the bot logic.
Commander
Contains all logic for defending a base, attacking the opponent and commanding squads. It also
contains the strategies, i.e. which buildings to construct and configuration of squads, used by the bot.
Important classes are:
• Protoss. Each class in this sub-module handles a specific strategy for Protoss.
• Terran. Each class in this sub-module handles a specific strategy for Terrans.
• Zerg. Each class in this sub-module handles a specific strategy for Zerg.
• Commander. This class handles the Commander. The Commander is responsible for controlling the squads to defend bases or attack the enemy.
• Squad. This class handles the two main squad types Offensive and Defensive. It also serves as
a base class for specialized squads such as the RushSquad.
• ExplorationSquad. Is together with ExplorationManager responsible for units used for exploration.
• StrategySelector. Decides which strategy to use in a game. If more than one strategy exists,
one is randomly selected with a higher probability of being selected if it has a high win ratio.
Statistics about win ratio is stored in the Strategies_Opprimobot.csv file in the bwapi-data/AI/
folder.
InfluenceMapping
An influence maps based system for deciding where to defend bases and checking own and enemy
influence in different regions. It also keeps track of when a base location last was visible, which is
used by squads when attacking an enemy that has not yet been located.
12
MainAgents
Base logic for different agents. Each in-game unit or building is controlled as an autonomous agent.
An agent is basically logic for controlling an entity in a system, in this case units and buildings.
Important classes are:
• AgentFactory. Creates an agent object for an in-game unit. It first looks for a specific unit
agent class (for example MarineAgent for Terran Marines). If no specific agent class is found,
it creates an instance of the base class UnitAgent (for units) or StructureAgent (for buildings).
• BaseAgent. Base class for all agents.
• TargetingAgent. A smarter targeting of enemy units or buildings than the built-in targeting
system.
• WorkerAgent. Handles all the worker related tasks, i.e. resource gathering, building construction and repairing.
Managers
Contains logic for managers. A manager controls some important non-combat task such as building
placement, research and upgrades, exploration and resource management. Important classes are:
• AgentManager. A container that holds references to all agent objects. It also contains lots
of decision support methods such as how many of a specific unit or building that has been
constructed or how many units of a specific type that is located in a specific area.
• BuildingPlacer. Decides where to place new buildings.
• Constructor. Manages the build queue of planned buildings and decides when to construct
buildings.
• ExplorationManager. Decides where to send exploration units to get new information about
where the enemy is located.
• Upgrader. Manages unit upgrades and technology research.
• ResourceManager. Handles resource management (Minerals and Vespene gas). Each time
something that cost resources (buildings, units, upgrades, research) is needed, the resource
manager is requested to check if the bot has enough resources available.
Pathfinding
Contains all logic for the hybrid pathfinding system (see previous chapter). Important classes are:
• NavigationAgent. Used by every unit agent when deciding where to move next. It is responsible for handling the switches, between the built-in pathfinding system and potential fields/boids,
in the hybrid pathfinder.
• PFFunctions. Calculates the potential fields generated by the different in-game units and buildings. It is together with NavigationAgent responsible for the potential fields system.
• Pathfinder. This class is responsible for calculating a path using the built-in pathfinding system.
When an agent requests a path it is queued in the pathfinder, and the path requests are pulled
from the queue and calculated one at a time. The pathfinder uses a separate thread to avoid path
calculation taking up too much computation time.
13
Strategy
The contents of this package was moved to the Commander package in OpprimoBot version 15.2.
StructureAgents
This module contains all agents controlling buildings. Important classes are:
• StructureAgent. The main agent class for agents controlling buildings. It contains logic for
most building tasks such as unit construction, research and upgrades.
• RefineryAgent. Agent class for refineries. It contains logic for handling workers that gather
vespene gas.
• Protoss. This sub-module contains all specific building agents used by Protoss.
• Terran. This sub-module contains all specific building agents used by Terrans.
• Zerg. This sub-module contains all specific building agents used by Zerg.
UnitAgents
This module contains all agents controlling units. Important classes are:
• UnitAgent. The main agent class for agents controlling units. It contains logic for the most
basic unit tasks such as moving and attacking. It has no logic for using special abilities, so each
unit with special abilities have their own specific agent class.
• Protoss. This sub-module contains all specific unit agents used by Protoss.
• Terran. This sub-module contains all specific unit agents used by Terrans.
• Zerg. This sub-module contains all specific unit agents used by Zerg.
Utils
Contains useful helper classes. Important classes are:
• Config. Handles global configuration settings for the bot.
• cthread. Makes it easier to handle multiple threads.
• FileReaderUtils. Contains useful functions for reading and saving text files.
• Profiler. Used for performance profiling of the bot. The profiler measures the execution time
of code blocks, which can be very useful when searching for inefficient code. The results are
stored in the Profiling_Opprimobot.html file in the bwapi-data/AI/ folder.
• Statistics. Stores win information and scores for each game played. The results are stored in
the Statistics_Opprimobot.csv file in the bwapi-data/AI/ folder.
• Sets. Contains declarations of container data structures that is more efficient than the std::vector
used in earlier bot versions.
14
Main classes
There are some other important classes that are not placed in modules:
• OpprimoBot (previously BotModule). Main class for the bot. It contains all event methods called by BWAPI, for example when a new unit has been created or a building has been
destroyed.
• AIloop. This class is called each frame, and is responsible for calling all other classes in the
system.
15
5
Scouting
OpprimoBot does not require perfect information in a game and can use scouting to locate the enemy.
There are two versions of scouting depending on the type of squad.
ExplorationSquad
The ExplorationManager has a list of each Region (from BWTA2) in the map and the game frame
it last was visible. Each update frame the ExplorationManager checks if the center of the Region is
visible by a friendly unit or building. If so, the last visible frame for the Region is updated to the
current game frame. The ExplorationSquad moves towards the Region with the lowest last visible
frame value because it is the longest time since it was visited.
Other squads
The ExplorationManager keeps track of seen enemy buildings even if they are currently not visible.
When a squad is ordered to attack, it moves towards the closest enemy building located. If no enemy
buildings have been located when a squad is ordered to attack, it moves towards the base location
with the lowest last visible frame value. The system, handled by the MapManager class, works in
the same way as the system used for Exploration squads, but keeps track of each BaseLocation (from
BWTA2) instead of regions.
16