Coordinator of one or more clients. Used to start, step and stop games and replays. More...

#include <sc2_coordinator.h>

Public Member Functions
bool	LoadSettings (int argc, char **argv)

void	SetMultithreaded (bool value)

void	SetRealtime (bool value)

void	SetStepSize (int step_size)

void	SetProcessPath (const std::string &path)

void	SetDataVersion (const std::string &version)

void	SetTimeoutMS (uint32_t timeout_ms=kDefaultProtoInterfaceTimeout)

void	SetPortStart (int port_start)

void	SetFeatureLayers (const FeatureLayerSettings &settings)

void	SetRender (const RenderSettings &settings)

void	SetWindowSize (int width, int height)

void	SetWindowLocation (int x, int y)

void	SetUseGeneralizedAbilityId (bool value)

void	SetReplayPerspective (int player_id)
	Sets the replay perspective. Use 0 to observe all players.

void	AddCommandLine (const std::string &option)
	Appends a command line argument to be fed to StarCraft II when starting.

void	SetRawAffectsSelection (bool value)

void	SetFullScreen (bool value)

void	SetParticipants (const std::vector< PlayerSetup > &participants)
	Sets up the bots and whether they are controlled by in-built AI, human or a custom bot.

void	SetReplayRecovery (bool value)

void	AddReplayObserver (ReplayObserver *replay_observer)
	Add an instance of ReplayObserver, each ReplayObserver will run a separate StarCraft II client.

void	LaunchStarcraft ()
	Uses settings gathered from LoadSettings, specifically the path to the executable, to run StarCraft II.

void	Connect (int port)
	Attaches to a running Starcraft.

bool	StartGame (const std::string &map_path=std::string())

bool	CreateGame (const std::string &map_path=std::string())

bool	JoinGame ()

void	SetupPorts (size_t num_agents, int port_start, bool check_single=true)

bool	Update ()

void	LeaveGame ()
	Requests for the currently running game to end.

bool	AllGamesEnded () const
	Returns true if all running games have ended.

bool	SetReplayPath (const std::string &path)
	Sets the path for to a folder of replays to analyze.

bool	LoadReplayList (const std::string &file_path)
	Loads replays from a file.

void	SaveReplayList (const std::string &file_path)
	Saves replays to a file.

bool	HasReplays () const

void	WaitForAllResponses ()
	Blocks for all bots to receive any pending responses.

bool	RemoteSaveMap (const void *data, int data_size, std::string remote_path)
	Saves a binary blob as a map to a remote location. More...

std::string	GetExePath () const

Detailed Description

Coordinator of one or more clients. Used to start, step and stop games and replays.

Member Function Documentation

◆ CreateGame()

bool sc2::Coordinator::CreateGame ( const std::string & map_path = std::string() )

Creates a game but does not join the agents to the game

Parameters

map_path Path to the map to run. Returns true if the game was successfully created

◆ GetExePath()

std::string sc2::Coordinator::GetExePath ( ) const

Gets the game executable path.

Returns: The game executable path.

◆ HasReplays()

bool sc2::Coordinator::HasReplays ( ) const

Determines if there are unprocessed replays.

Returns: Is true if there are replays left.

◆ JoinGame()

bool sc2::Coordinator::JoinGame ( )

Joins agents to the game Returns true if the agents were successfully connected to the game

◆ LoadSettings()

bool sc2::Coordinator::LoadSettings	(	int	argc,
		char **	argv
	)

Used to load settings. Settings will be discovered in the following order:

If command line arguments are provided it will use them. Invoke binary with –help to see expected arguments.
(Recommended) If the StarCraft II binary has been run the function will auto discover its location.
Parameters

argc Provided in main signature.

argv Provided in main signature.

game_settings The name of the settings file.

Returns
True if settings were found or discovered, false otherwise.

◆ RemoteSaveMap()

bool sc2::Coordinator::RemoteSaveMap	(	const void *	data,
		int	data_size,
		std::string	remote_path
	)

Saves a binary blob as a map to a remote location.

<

Returns: Is true if the save is successful.

◆ SetDataVersion()

void sc2::Coordinator::SetDataVersion ( const std::string & version )

Set the correct data version of a replay to allow faster replay loading. Saves a few seconds if replay is not up to date. Works only in combination with correct process path set by "SetProcessPath".

Parameters

version Look in "protocol/buildinfo/versions.json" for the property "data-hash". Or read it from "ReplayInfo.data_version".

◆ SetFeatureLayers()

void sc2::Coordinator::SetFeatureLayers ( const FeatureLayerSettings & settings )

Indicates whether feature layers should be provided in the observation.

Parameters

settings Configuration of feature layer settings.

See also: FeatureLayerSettings

◆ SetFullScreen()

void sc2::Coordinator::SetFullScreen ( bool value )

Specifies whether the game should run in fullscreen or not. This usually indicates that a real player (the first registered participant) is using the first launched instance to play (the first registered participant). The game will be launched in the windowed mode for the second player (second participant). It should be used in combination with SetRealtime(true), otherwise the game has no sound.

◆ SetMultithreaded()

void sc2::Coordinator::SetMultithreaded ( bool value )

Specifies whether bots or replays OnStep function should be run in parallel. If set to true make sure your bots are thread-safe if they reach into shared code.

Parameters

value True to multithread, false otherwise.

◆ SetPortStart()

void sc2::Coordinator::SetPortStart ( int port_start )

Sets the first port number to use. Subsequent port assignments are sequential.

Parameters

port_start First port number.

◆ SetProcessPath()

void sc2::Coordinator::SetProcessPath ( const std::string & path )

Sets the path to the StarCraft II binary.

Parameters

path	Absolute file path.

◆ SetRawAffectsSelection()

void sc2::Coordinator::SetRawAffectsSelection ( bool value )

When set to true, less actions will be generated because the game will not try to keep your unit selection. Useful to reduce the number of actions, but may complicate the debugging process.

◆ SetRealtime()

void sc2::Coordinator::SetRealtime ( bool value )

Specifies whether the game should run in realtime or not. If the game is running in real time that means the coordinator is not stepping it forward. The game is running and your bot reaches into it asynchronously to read state.

Parameters

value True to be realtime, false otherwise.

◆ SetRender()

void sc2::Coordinator::SetRender ( const RenderSettings & settings )

See also: RenderSettings

◆ SetStepSize()

void sc2::Coordinator::SetStepSize ( int step_size )

Sets the number of game loops to run for each step.

Parameters

step_size Number of gameloops to run for each step.

◆ SetTimeoutMS()

void sc2::Coordinator::SetTimeoutMS ( uint32_t timeout_ms = kDefaultProtoInterfaceTimeout )

Sets the timeout for network operations.

Parameters

value timeout_ms in milliseconds.

◆ SetupPorts()

void sc2::Coordinator::SetupPorts	(	size_t	num_agents,
		int	port_start,
		bool	check_single = `true`
	)

Sets up the sc2 game ports to use param num_agents Number of agents in the game param port_start Starting port number param check_single Checks if the game is a single player or multiplayer game

◆ SetUseGeneralizedAbilityId()

void sc2::Coordinator::SetUseGeneralizedAbilityId ( bool value )

Uses generalized abilities where possible. Example: BUILD_TECHLAB_BARRACKS, BUILD_TECHLAB_FACTORY, BUILD_TECHLAB_STARPORT ability ids are generalized to BUILD_TECHLAB ability id in the observation.

◆ SetWindowLocation()

void sc2::Coordinator::SetWindowLocation	(	int	x,
		int	y
	)

Sets the game window location.

Parameters

x	X position of game window.
y	y position of game window.

◆ SetWindowSize()

void sc2::Coordinator::SetWindowSize	(	int	width,
		int	height
	)

Sets the game window dimensions.

Parameters

width	Width of game window.
height	Height of game window.

◆ StartGame()

bool sc2::Coordinator::StartGame ( const std::string & map_path = std::string() )

Starts a game on a certain map. There are multiple ways to specify a map: Absolute path: Any .SC2Map file. Relative path: Any .SC2Map file relative to either the library or installation maps folder. Map name: Any BattleNet published map that has been locally cached.

Parameters

map_path Path to the map to run.

Returns: True if the game started, false if there was errors or the game didn't start, override OnError callback to see the exact errors.

◆ Update()

bool sc2::Coordinator::Update ( )

Helper function used to actually run a bot. This function will behave differently in real-time compared to non real-time. In real-time there is no step sent over the wire but instead will request and read observations as the game runs.

For non-real time Update will perform the following:
1. Step the simulation forward by a certain amount of game steps, this essentially moves the game loops forward.
2. Wait for the step to complete, the step is completed when a response is received and read from the StarCraft II binary.
  - When the step is completed an Observation has been received. It is parsed and various client events are dispatched.
3. Call the user's OnStep function.
Real time applications will perform the following:
1. The Observation is directly requested. The process will block while waiting for it.
2. The Observation is parsed and client events are dispatched.
3. Unit actions batched from the ActionInterface are dispatched.
  Returns
  False if the game has ended, true otherwise.

The documentation for this class was generated from the following file:

include/sc2api/sc2_coordinator.h

argc	Provided in main signature.
argv	Provided in main signature.
game_settings	The name of the settings file.

Public Member Functions

Detailed Description

Member Function Documentation

◆ CreateGame()

◆ GetExePath()

◆ HasReplays()

◆ JoinGame()

◆ LoadSettings()

◆ RemoteSaveMap()

◆ SetDataVersion()

◆ SetFeatureLayers()

◆ SetFullScreen()

◆ SetMultithreaded()

◆ SetPortStart()

◆ SetProcessPath()

◆ SetRawAffectsSelection()

◆ SetRealtime()

◆ SetRender()

◆ SetStepSize()

◆ SetTimeoutMS()

◆ SetupPorts()

◆ SetUseGeneralizedAbilityId()

◆ SetWindowLocation()

◆ SetWindowSize()

◆ StartGame()

◆ Update()