Skip to main content

An interface to request SC2 matches and launch the client for human and/or AI/bot play

Project description

PyPI Build Status Coverage Status

Play Starcraft 2 on a ladder as a human or AI against other human AI


The objective of this repository is enable casual Starcraft 2 players, AI developers and proficient coders to all create a player that competes against others in a Starcraft 2 match. The strategy is to create an increasingly user-friendly interface so that most anybody can readily set up matches and play against

Rationale: Why Create this Repository?

There is an existing ladder for AI-only developers, While that project is under active development as of July 6, 2018, its roadmap doesn't support several critical features which impedes developers' efforts (such as ours) to create AI that is publicly visible. Here are several features which this ladder supports that may not.

  • Play on your own machine against others on their own machines. You're no longer limited by some other person's machine who is sharing system resources with other players in the game.
  • Support AI vs AI, AI vs human and human vs human play.
  • AI developers aren't required to share their source code or any executable.
  • Fast, user-friendly setup that non-programmers or programmers with lower proficiency in a specific language can set up. No need to hunt + edit files by hand.

Brief Functional Overview

This sc2gameLobby package's primary functions are as follows:

  1. Issue match requests such that other available players or static bots can be matched against you. When being matched against opponents, if no valid opponents are available for a match with you in the queue, you are automatically matched instead against other publicly available bot algorithms or Blizzard's built-in bots depending on your estimated proficiency.
  2. Launch a Starcraft 2 client that will automatically manage the match along with other Starcraft 2 clients (as needed). The match is played until its finished.
  3. Each player using sc2gameLobby reports results back to the ladder. The ladder verifies each player's reported results against its own intimate knowledge of the match to accurately determine the proper match result and update the ladder accordingly.

Communication with the ladder server occurs via TCP connection with a django server available on the internet. It is possible to communicate with alternative ladders, but we've established this server form normal sc2gameLobby gameplay.


System Requirements

  • sc2gameLobby is proven using both Linux (using wine) and Windows. While untested on OSX, because OSX is also widely tested using pysc2, sc2gameLobby is also expected to work without issue. NOTE: Linux is not a platform officially supported by Blizzard for Starcraft 2, but it does work, both using headless and regular setups using full graphics.
  • As a human, your own system must be able to support a Starcraft 2 client application (the window that actually plays the game). Reference standard Starcraft 2 game requirements for details.
  • As an AI, in addition to the requirements for human play, as well as any other resources your AI may require. If your AI architecture can run, it is allowed on this ladder.


  1. Install Starcraft 2 normally. IMPORTANT If you use an install destination path other than the default, ensure the environment variable SC2PATH is set with the path to your customized installation path.
  2. Install any(?) version of python that is compatible with your system.
  3. Use conda or pip via instructions below to install sc2gameLobby.

NOTE: you can also install this package via other means, but you may have to manage your environment to ensure all dependencies are available on your system. If you're not familiar with these utilities, follow the installation instructions provided by their authors available on the internet.


From a command line, enter a standard conda install command that's compatible with your system setup. Be sure you're targeting the intended environment!

EXAMPLE: conda install sc2gameLobby -n <your development environment name>


From a command line, enter a standard pip install command that's compatible with your system setup.

EXAMPLE: pip install sc2gameLobby


This sc2gameLobby package is indended to run with python version >= 3.5. Package dependencies are defined in requirements.txt. Dependencies are installed automatically when using the installation methods above.

Verification of Valid Installation

If your setup is fully successful, the following test commands should work as follows:

test command: python -m sc2gameLobby --help

usage: [-h] [--nogui] [--search PLAYERS] [--history] [-l] [-p]
PURPOSE: front-end interface to easily and reliably match against opponents
and run Starcraft2 opponents.
version: 1.0.0

test command: > python -m sc2gameLobby --versions

   base-version: 65895
      data-hash: BF41339C22AE2EDEBEEADC8C75028F7D
          label: 4.4.0
        version: 65895

test command: python -m sc2gameLobby --search mapexplorer

<PlayerRecord mapexplorer ai>
           type : <PlayerDesigns ai>
     difficulty : None
        initCmd : sc2ai.agents.newExplorer
         rating : 0
        created : 2018-05-28


ERROR: A connection could not be made. <Ladder versentiedge> may not be available or you may not be connected to the internet.

This means that the ladder server instance you are attempting to communicate with could not be reached. It may not be online or your connection to the internet may be compromised.

<reserved for additional issues if/when such are reported>

Recommended Usage

Great, now you're set to rock ladder matches versus humans and AI opponents! Refer to python-specific or non python-specific usage documents. Good luck!

Further Development and Augmentation

Add New Features to the Code?

This is an open-use repository. Feel free to fork and issue pull requests. Feature enhancements, especially for to-be-developed features, and bug fixes are especially appreciated.

Anticipated Useful, To-Be-Developed Features
  • User-friendly GUI front end that abstracts the command-line utilities.
  • Web browser integration to perform match requests.
  • Publicly available web page statistics from data mining match results.
  • Additional game modes beyond 1v1.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sc2gameLobby, version 1.1.13
Filename, size File type Python version Upload date Hashes
Filename, size sc2gameLobby-1.1.13-py3.6.egg (838.1 kB) File type Egg Python version 3.6 Upload date Hashes View hashes
Filename, size sc2gameLobby-1.1.13-py3-none-any.whl (789.2 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size sc2gameLobby-1.1.13.tar.gz (190.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page