Configuration

Configuration

The configuration file bwapi.ini found under Starcraft/bwapi-data/ can be used to configure various options in BWAPI. The options are key=value pairs, and the keys are grouped into sections, for example, the key lan_mode is in the section auto_menu.

Overriding

It is possible to override the bwapi.ini settings by starting Starcraft with environment variables named in the following manner:

Section	Key	Value	Environment variable override
ai	ai	bot.dll	BWAPI_CONFIG_AI__AI=bot.dll
auto_menu	lan_mode	Local PC	BWAPI_CONFIG_AUTO_MENU__LAN_MODE=Local PC
section	key	value	BWAPI_CONFIG_SECTION__KEY=value

• Upper case section and key.
• Double underscores between section and key.

Additionally, it's possible to override which bwapi.ini file to use altogether with the BWAPI_CONFIG_INI environment variable.

Configuration Settings

ai

Contains settings for loading a user's AI module or tournament module. Commas can be used to separate the module loaded by multiple instances of Starcraft.

Absolute paths are acceptable (with or without quotations). These paths can easily be obtained in the Windows operating systems by holding SHIFT and right clicking your AI module DLL, followed by selecting Copy as path or equivalent.

Example: ai = "C:\Users\Adam\bwapi\bwapi\Release\TestAIModule.dll"

ai

This is a path to the AI module.

ai_dbg

Like ai, only this is the path to the AI module used in DEBUG mode.

tournament

This is a path to a tournament module. Tournament modules can only be DLLs.

auto_menu

Contains settings pertaining to automatic menu navigation and automation.

auto_menu

Value	Description
OFF	Disables menu automation.
SINGLE_PLAYER	Automates the navigation to a single-player game.
LAN	Automates the navigation to a specific multi-player mode chosen by the lan_mode option.
BATTLE_NET	Automates the navigation to Battle.net. Beyond that this feature is non-functional.

character_name

Value	Description
FIRST	Use the first character in the list.
WAIT	Wait for the user to select a character.
name	Use the character with the given name. Create it if it doesn't exist.

pause_dbg

Value	Description
ON	Waits for a debugger to be attached when running in DEBUG mode, before navigating automatic menus.
OFF	Does not wait.

lan_mode

The name of the network mode in the multiplayer menu. Must be the fully-qualified name of the user's locale.

Examples:

• Local Area Network (IPX)
• Direct Cable Connection
• Local Area Network (UDP)
• Local PC
• Direct IP

Note that lan_mode = Local Area Network (UDP) will match the network name in the english locale, but not necessarily the german locale.

auto_restart

This specifies what to do at the end of a match or replay.

Value	Description
ON	Automatically skips the match results screen.
OFF	Waits for the user to skip the match results screen.

map

A relative path to the map or replay file for loading. This path can contain characters ? and * for single and multi character wildcards respectively. The order of the map or replay files being chosen is determined by the mapiteration option. If there are no wildcard characters, then only one map will be chosen.

Examples:

• map = maps/(2)Boxer.scm
• map = maps/BroodWar/WebMaps/(?)*.sc?
• map = maps/replays/LastReplay.rep
• map =

game

Name of the network game to join. If the game does not exist, and the map entry is not blank, then a game is created instead of joined. If this entry is blank, then the rules of the map entry are followed.

mapiteration

Value	Description
RANDOM	Randomly chooses a map file.
SEQUENCE	Plays through every map file in a sequence.

race

Value	Description
Terran	Selecting Terran from the dropdown.
Protoss	Selecting Protoss from the dropdown.
Zerg	Selecting Zerg from the dropdown.
Random	Selecting Random from the dropdown.

enemy_count

The number of enemy computer players that will be added to the match.

enemy_race

The default race of the enemy computer players.

Value	Description
Terran	Selecting Terran from the dropdown.
Protoss	Selecting Protoss from the dropdown.
Zerg	Selecting Zerg from the dropdown.
Random	Selecting Random from the dropdown.
RandomTP	Randomly selects either Terran or Protoss.
RandomTZ	Randomly selects either Terran or Zerg.
RandomPZ	Randomly selects either Protoss or Zerg.
RandomTPZ	Randomly selects either Terran, Protoss, or Zerg.

enemy_race_#

The race of a specified enemy computer player. Can be any one of the values from enemy_race, along with one additional value.

Value	Description
Default	Uses the value specified by enemy_race.

game_type

Selects the desired game type from the dropdown menu. Can be any of the values found in GameTypes, provided that value is visible in the dropdown menu.

game_type_extra

Some game types have an extra dropdown menu, the value specified here will be selected from that dropdown. e.g. 3 vs 1

save_replay

Specifies the file to write when automatically saving a replay file at the end of a match. May contain environment variables and date formatting strings.

Environment variables are specified as %VARIABLE_NAME%. Time variables are specified as $Format.

Environment Variables

Value	Description	Sample
BOTNAME	The full name of the BWAPI Player.	Undermind
BOTNAME6	The name of the BWAPI Player truncated to 6 characters.	MimicB
BOTRACE	The race of the BWAPI Player represented as a single character.	P
MAP	The name of the map truncated to 16 characters.	Challenger
ALLYNAMES	The names of all allied players, each truncated to 6 characters.	krasi0Overmi
ALLYRACES	The races of all allied players, each race being represented as a single character.	TZ
ENEMYNAMES	The names of all enemy players, each truncated to 6 characters. Computer players will have the name Comp.	UAlberSkynet
ENEMYRACES	The races of all enemy players, each race being represented as a single character.	ZP
GAMERESULT	The result of the match, either win or loss.	loss

Time Formatting

Specified by this function. Make sure to use the dollar sign ($) as a formatting prefix instead of %.

wait_for_min_players

Number of players to wait for before starting a network game. This includes the BWAPI player. The game will start immediately when it is full.

wait_for_max_players

The network game will be started when the number of players reaches this value. This includes the BWAPI player. The game will start immediately when it is full.

wait_for_time

The time in milliseconds (ms) to wait after the game has met the min_players requirement. The game will start immediately when it is full.

config

Contains settings associated with BWAPI functionality.

holiday

Value	Description
ON	Enables the use of special graphics and sounds around certain times of the year.
OFF	Disables the use of special easter eggs.

As of right now there are no special holiday settings so this option currently does nothing.

shared_memory

This is specifically used to disable shared memory (BWAPI Server) as a workaround for a bug in the Windows Emulator "WINE".

Value	Description
ON	BWAPI Server is enabled.
OFF	BWAPI Server is disabled.

window

Settings for BWAPI's windowed mode hack.

windowed

Value	Description
ON	Starcraft will be launched inside of a window, instead of full screen.
OFF	Starcraft will run in full screen.

Window settings

The left, top, width, and height settings for the window position. These values will be overwritten if a window is active.

starcraft

Settings that alter the behaviour of Starcraft.

sound

Used to override the state of the game's sound engine to gain a small performance boost. Note that muting in-game sound will not disable the sound engine. In-game music and sound effects are still processed, even if muted.

Value	Description
ON	The Starcraft sound engine will be enabled.
OFF	The Starcraft sound engine will be disabled. Sound will not play, and in-game sound settings will be disabled.

screenshots

Value	Description
gif	Writes screenshots in .gif format.
pcx	Writes screenshots in .pcx format (Starcraft default).
tga	Writes screenshots in .tga format.
bmp	Writes screenshots in .bmp format.

seed_override

This uses a fixed seed at the start of the game so that if played out the exact same way, the same occurrences will happen every time. This value must be a decimal integer.

Note: This option affects both single AND multi-player modes (for game hosts only). This means that hosting a multi-player game with this option enabled will distribute this fixed seed to all other players in the game.

speed_override

This overrides the default game speed setting and prevents bots from changing the game speed. Enabling this option causes it to take effect. The value is the number of milliseconds per frame. A negative value uses the game's default speed value.

drop_players

This specifies if BWAPI should drop other players from the game when the timeout dialog reaches 0. Players usually time out when there are connection issues or their client is not responding. Setting this to OFF will cause BWAPI to wait an infinite amount of time until the player reconnects.

Value	Description
ON	BWAPI will drop players from the game when they have timed out.
OFF	BWAPI will leave the time-out dialog open and wait for the other players to reconnect.