node-sc2

node-sc2 is a lightweight node.js framework to facilitate fast development of agents (or "bots") for Starcraft II in JavaScript.

• Motivation
• Getting started
  • Hello World
• Overview and Tutorial
• Feature Layer and Rendered Interfaces
• Notice of Active Development
• Contributing
• Ladder and Tournament Submission
• Features and Roadmap
• Environmental Variables
  • Speed Control
  • Debugging
• Getting Help
• Changelog

Motivation

There are a few existing libraries in the node.js ecosystem to work with the C++ API (sc2client-api), but node-sc2 is a pure javascript implementation of sc2client-proto, with the goal of being ergonomic across a variety of environments without the need for additional build tools. Under the hood it uses @node-sc2/proto as the transport layer.

Getting started

npm install --save @node-sc2/core

You must also have any maps you expect to load available in the standard location (/Maps relative to your SC2 directory). Official map downloads can be found here. For a more up-to-date pack of maps, join the SC2 AI discord (https://discord.gg/Emm5Ztz) and type !maps in #general.

Hello World

The 'hello world' of sc2 bots seems to be a worker rush, so... here we go:

// main.js
const { createAgent, createEngine, createPlayer } = require('@node-sc2/core');
const { Difficulty, Race } = require('@node-sc2/core/constants/enums');

const bot = createAgent({
    async onGameStart({ resources }) {
        const { units, actions, map } = resources.get();

        const workers = units.getWorkers();
        return actions.attackMove(workers, map.getEnemyMain().townhallPosition);
    }
});

const engine = createEngine();

engine.connect().then(() => {
    return engine.runGame('Blueshift LE', [
        createPlayer({ race: Race.RANDOM }, bot),
        createPlayer({ race: Race.RANDOM, difficulty: Difficulty.MEDIUM }),
    ]);
});

Now you can run it with node main.js. Wasn't that easy? Now this isn't going to win you any awards... but it might win you a few games against the built-in AI.

NOTE: The first time you run the bot, it will take up to 15 seconds to launch the SC2 client. After that, the default behavior is to keep the client running, so starting a new game will take only a moment. Also, feel free to manage the client yourself, as node-sc2 will just use the existing instance listening on the selected port.

Overview and Tutorial

An overview of the library and its usage is available by clicking here. The overview is the recommended place to get started. If you want to skip it and go straight to a tutorial of a bot that can consistently win against the built-in Elite AI, click here.

Feature Layer and Rendered Interfaces

Although most of the supported features of node-sc2 are based on the raw data interface, there is initial support for both the Feature Layer and the Rendered interfaces. Importantly, you must set your NODE_ENV to production if you don't want the rendered interface to crawl (unless you need long stack trace support). For example, on windows that would be: set NODE_ENV=production. The feature layer interface is pretty slow either way (on windows, linux should be significantly better). Currently there are no abstractions but you can get access the exposed data as such:

/** @type {SC2APIProtocol.SpatialCameraSetup} */
const camera = {
    // you can experiment with various resolutions
    resolution: {
        x: 640,
        y: 480,
    },
    // you can also leave this off if you don't want the minimap to render
    minimapResolution: {
        x: 128,
        y: 128,
    }
};

// the 'interface' prop of your agent blueprint is of SC2APIProtocol.InterfaceOptions
const bot = createAgent({
    settings: {
        race: Race.PROTOSS,
    },
    interface: {
        raw: true,
        score: true, // optional, score data
        render: camera, // turns on the rendered interface
        featureLayer: camera, // turns on the feature layer interface
    },
    async onStep(world) {
        const { frame } = world.resources.get();
        console.log(frame.getRender(), frame.getFeatureLayer());
    }
});

The shape of the data is of types SC2APIProtocol.ObservationRander and SC2APIProtocol.ObservationFeatureLayer. More can be read about it in the blizzard proto definitions.

Notice of Active Development

The goal of @node-sc2/core is to use semver. As long as @node-sc2/core is pre v1.0.0, the library is under very active development. It may be missing obvious features, even ones that are simple to implement. It may expose APIs that are fundimentally broken. It may even break backwards compatibility (although we're going to try really hard not to without major version bumps). The goal is to get to v1.0.0 rapidly and remove this notice.

Contributing

Any contributions are appreciated. That includes detailed issue reports (with repro if possible), comments, concerns, API design/suggestions, and PRs. I will try to work together with everyone as much as feasible to create the best user experience possible.

Ladder and Tournament Submission

Currently the following method is available as a stop-gap to be able to submit your node-sc2-based bot to a tournament or ladder (such as one using software like Sc2LadderServer).

First install pkg, which is what we're going to use to package up your bot: npm install --save-dev pkg

Then add the bin directive, and this npm script to your package.json under scripts:

"bin": "main.js", // change main.js to your entrypoint file name, if different
...
"scripts": {
    "build": "pkg ./ --target win-x64 --out-path ./dist",
}

Finally, run the script: npm run build. Your compiled bot will be in dist/your-bot-name.exe and will be compatible with the CLI commands needed to run it using the ladder manager or similar software.

In the future, this will be built into node-sc2 and be a cli command. It is on the major timeline and should be ready by v1.0.0.

Features and Roadmap

This readme will be updated with a link to a Trello board shortly, outlining feature development roadmap progress. On top of that, github issues can be used to discuss features and bugs.

Environmental Variables

Various settings can be adjusted through env vars in your shell. In a windows command shell, this is done with the set command, eg: set DEBUG=sc2:debug:*.

Speed Control

Default is 4 frames per step. This can be adjusted with the STEP_COUNT env var... for example, STEP_COUNT=8 for faster simulations.

Debugging

node-sc2 makes use of the debug library. Run your agent with DEBUG=sc2:debug:* for additional helpful output, or DEBUG=sc2:* for way too much output that's probably not too helpful :) For extra fun, run your script with node --inspect, open a chrome instance, navigate to chrome://inspect and click on "Open dedicated DevTools for Node". Enjoy the full debugging experience (including cpu and memory profiling, pausing, breakpoints, etc).

Getting Help

First I would encourage you to read through all available documentation. Beyond this readme, three other user documents are available:

• Overview
• Tutorial
• API Reference

Beyond that, there are also two documents aimed towards those wanting to help develop the core library, or just understanding more about how it works:

• Design
• Internals

Beyond the documentation, Starcraft 2 AI has a very active community, available through this discord invitation link: https://discord.gg/Emm5Ztz - This library specifically can be discussed in the #javascript channel. Come say hi!

Changelog

The changelog has been moved to a dedicated document: changelog.md.