SC2 AI

So, you wanted to be a pro gamer, but made a life-typo. All good, friendo.
Let’s put those weathered hands and whetted wits to work and play and slay some nerds, ok?

The sc2ai gem provides a Ruby interface for StarCraft® II.

The game is now available, free to play, at starcraft2.blizzard.com.
This Ruby language is also now available, free to play, at www.ruby-lang.org.

Mac (Apple® silicon / Intel®), Microsoft© Windows, WSL and Linux® are all supported.

Have a look around and then proceed to the tutorials.
They’ll skill you up, even if you’ve never played before.

I am Jack’s digital fury

The things we write are called “bots”. They beat crap out of each other on aiarena.net.
There are regular tournaments and a permanent live stream here www.twitch.tv/aiarenastream.

That’s right, you just stumbled upon the final boss of competitive coding. Welcome to Fight Club for Nerds, nerd. This is the only door in.🚪

running.jpg

Installation

Game

Download StarCraft® II installer and use the default paths.

Maps

After install, download the latest aiarena.net ladder maps from the top.

Extract them into your SC2 location in a subdirectory Maps, i.e.
Mac: /Applications/StarCraft II/Maps/
Windows: C:\Program Files (x86)\StarCraft II\Maps\
(Create the folder if it isn’t there.)

Write down one of the map names, we’ll use it in a bit when starting a match.

Get the gem

The gem is compatible with latest stable Ruby and the previous stable Ruby. On the AI Arena ladder, bots run on the latest stable Ruby.

gem install 'sc2ai'
Give it a minute
If your computer is older, it can take 2-3mins for the rumale dependency to build native extensions.
It's compiling some kick-ass math accelerators for your benefit - worth a moment.

Create a new project

Let’s create a new bot project folder. Execute from the command line:

sc2ai new BOTNAME RACE

BOTNAME: In choosing your botname, remember that this name will be both a class and an executable. No spaces and don’t start with a number. Any case is acceptable, myBot123, myBot123, my_bot_123, etc.

RACE:

  • Terran: Human. Tactical, resourceful, harnessing mechanical assault.

  • Zerg: Swarm of alien creatures, overwhelming numbers, biological warfare.

  • Protoss: Advanced alien race, psionic powers, sophisticated technology, honorable warriors.

  • Random: One of the above at random.

Example:

sc2ai new myCleverBot Terran

This creates a bot called MyCleverBot in the folder mycleverbot.

cd mycleverbot && bundle install

Project folder summary

File/Folder Notes
api/ API proto definitions for quick API reference. (Purely aesthetic, deletable)
my_clever_bot.rb Our very own bot!
run_example_match.rb An example local match. We will run this soon.
boot.rb Ladder: Requires “my_clever_bot” and sets $bot = MyCleverBot.new(…)
.ladderignore Ladder: Ignored files when uploading to aiarena
Gemfile
Gemfile.lock

We are almost there!
We just need the game client configured.

If you’re running on Windows with the Windows Ruby installer, or you’re on MacOS, you’re ready to launch! Skip to Configure StarCraft® II.
For WSL and Linux, see these configuration steps below first.

Windows, WSL setup

On Windows, for speed and enjoyment, we recommend installing WSL 2.

WSL
In this case, SC2 is installed on Windows and your code is executed on Linux.
To allow the two systems two to talk to each other, open the firewall between them as follows from PowerShell as Admin:
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
That should be it for most typical cases. You are ready to launch.

Linux, Wine setup

In this scenario is only if you installed SC2 itself on Linux.
Meaning, the SC2 client you installed is either headless, via Lutris or Wine.

Wine On Linux: You might initially install StarCraft II via BattleNet using Proton, because BattleNet can be troublesome. This is fine.
Simply ensure that a valid SC2 wine runner, such as Wine GE is installed.
Ensure you set BattleNet configuration to "Launch Battle.net when I start my computer", else you will get an icuuc52.dll error.

Environment config
You can manually set your client PATH and the detected Platform with environment variables.
ENV['SC2PATH'] can be set manually to StarCraft 2 base directory for Linux, if using Lutris. This is the folder which contains the “Versions” folder. ENV['SC2PF'] should be manually set to “WineLinux” when running Wine
ENV['WINE'] should be manually set to your wine binary

For example, a Lutris config might look like this:

SC2PATH="/home/YOUR_USERNAME/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/"
SC2PF="WineLinux"
WINE="/home/YOUR_USERNAME/.local/share/lutris/runners/wine/wine-ge-8-26-x86_64/bin/wine64"

You can set these in your shell, boot.rb, configure your IDE, use dotenv, or anywhere before launching a Match.

Additional options which are useful for Linux can be set via Sc2::Configuration.

Configure StarCraft® II

Our competitive ladder is normally a version behind Blizzard’s retail version. It’s recommended (but not required) to run on the same version as we are patched on the ladder (5.0.14 at the time of writing).

Method 1 - Automatic (recommended)

From your project directory execute:

bundle exec sc2ai download_ladder_version

This launches the client and connects with a special replay file which will handle the downloads.
It will automatically write sc2ai.yml with the correct configuration.
When the maps rotate and the ladder version upgrades, you can execute this same command for the upgrade.

Method 2 - Manual

Check on the Discord what the current patch version is, i.e. 5.0.14
Find and watch any replay from that patch version.

Then create sc2ai.yaml in your project root with the version set to “5.0.14” or “ladder”.

---
version: "ladder"

or configure with code:

Sc2.config do |config|
    config.version = "ladder"
end

Running your first Match

The Hello World of botting is a worker rush.
Given the example above, lets inspect the created bot file my_clever_bot.rb.

The Bot:

require "sc2ai"

class MyCleverBot < Sc2::Player::Bot
  def on_step
    if game_loop == 0
      units.workers.attack(target: geo.enemy_start_position)
    end

    # If your attack fails, "good game" and exit
    if units.workers.size.zero?
      action_chat("gg", channel: Api::ActionChat::Channel::BROADCAST)
      leave_game
    end
  end
end

The on_step method executes whenever the game stepped forward. The very first game loop, we send all our workers to attack the enemy’s start position.

The Match:
To run a match, you can simply create a file which includes your bot and executes it the following way:

require_relative "my_clever_bot.rb"
Sc2::Match.new(
  players: [
    MyCleverBot.new(name: "myCleverBot", race: Api::Race::TERRAN),
    Sc2::Player::Computer.new(race: Api::Race::RANDOM, difficulty: Api::Difficulty::VERY_EASY)
  ],
  map: "PylonAIE_v4" # Or any of the downloaded map names
).run

One such file is ready-made for you in your project run_example_match.rb. You can alter this as you see fit and run the example:

bundle exec ruby run_example_match.rb

Congrats, you’re botting!

The replay is auto-saved as replays/autosave-#{botname}.SC2Replay for casual review.

While the code might seem foreign right now, fear not! The syntax is generally quite friendly while also forcibly teaching you the API. We have some extremely useful tutorials ahead once you’re done skimming the next two sections.

Competing on the ladder

We build a compatible and semi-portable Ruby via docker and ship your source code with it.

What the process does

We will execute docker compose to pull a Ruby linux image, copy your bot directory, bundle install and zip up what we need.

Includes: Everything in your current folder is added, including data/ where you should store persisted and growing files like databases. Then excludes are applied.

Excludes: - all dot folders and file (.git .github .bundler) - replays (replays/*)

You can add additional excludes by adding entries to .ladderignore.

Build a Ladder Zip

Disclaimers: 1. Commit your code before building. 2. If you have sensitive source in your folder, review the zip file before upload.

The build command is sc2ai ladderzip BOTNAME

You must ensure that BOTNAME matches your aiarena “Name” exactly.

So lets build your bot. Execute this command with your actual BOTNAME instead of MyCleverBot:

bundle exec sc2ai ladderzip MyCleverBot

This should generate ./build.zip.

Uploading

If this is the first time you are creating a bot, the form is here: aiarena.net/botupload/ Upload build.zip to aiarena.net and select “Type” “cpplinux”. You must join a competition for your bot to be scheduled. You can also use Request Match to challenge someone directly and immediately.

Troubleshooting

If you need to debug anything, the logs online are for stderr only. Use it sparingly. $stderr.puts "I really needed this log entry"

Practice vs built-in AI

A good practice partner is the built-in AI at Api::Difficulty from recommended Hard through to CheatInsane. You can also choose an ai_build preset.


Sc2::Player::Computer.new(

  difficulty: Api::Difficulty::HARD, 

  ai_build: Api::AIBuild::AIR

)

Play offline against another bot

To play against yourself or a friend, from the same computer, just setup a multi-bot match. Two instances of the game will load.

# require_relative "../friendo/some_other_bot.rb"
class SomeOtherBot < Sc2::Player::Bot
  def on_step; end
end


Sc2::Match.new(
  players: [
    MyBot.new(name: "Rubocop", race: Api::Race::TERRAN),
    SomeOtherBot.new(
      name: "Jean-ClawsVD",   # :)
      race: Api::Race::ZERG
    )
  ],
  map: "PylonAIE_v4",
).run

Usage

You’ve done so excellent thus far, that we should reward you with ending this README.

I bet you have so many questions about training units, building structures, research and abilities…
Commanding your army units, making groups and knowing your enemy…
Info about your resources, supply, reading the minimap, vision, creep and pathing…
Or even how is ANY OF THIS possible?

Let’s go through all of the above in byte sized chunks with the tutorials which follows. The README is over, but check out Acknowledgements below which answers one of these questions.

Onwards, to the tutorials! ➡️

Development

After checking out the repo, run bin/setup to install dependencies.
To install this gem onto your local machine, run rake install.

Contributing

Conventional commits preferred, please.
Fork and create a branch feature-name-here, fixes-this-problem and create a pull request.
Bug reports and pull requests are welcome on GitHub at gitlab.com/dysonreturns/sc2ai.
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Acknowledgements

The good people at Blizzard Entertainment® and DeepMind Technologies Limited (“Google DeepMind”) collaborated on SC2 AI an research project called AlphaStar. By the good graces of Blizzard (and now Microsoft©), their machine learning interface for StarCraft® II remains open for those who wish to experiment with AI in this seemingly stochastic, yet repeatable training environment.
Thanks Microsoft!

Much of the runner standardization, tech tree and parsing was made using Dentosal and BuRny’s python libraries as reference.
Their work is brilliant and I am eternally grateful to have walked in their footsteps.

License

The gem is available as open source under the terms of the MIT License.

StarCraft® II is governed by the Blizzard End User License Agreement.

The StarCraft® II AI and Machine Learning Interface, Blizzard map packs and replay packs are governed by the AI and Machine Learning License.
More info on those packages here: github.com/Blizzard/s2client-proto#downloads/
It’s a permissive License Agreement, which grants you more freedoms than it takes away. Thanks Blizzard, sincerely.

StarCraft® II: Wings of Liberty™
©2010 Blizzard Entertainment, Inc. All rights reserved. Wings of Liberty is a trademark, and StarCraft and Blizzard Entertainment are trademarks or registered trademarks of Blizzard Entertainment, Inc. in the U.S. and/or other countries.

Code of Conduct

Everyone interacting in the sc2ai project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.