s2client-api-typescript

This is a package that allows you to communicate with the StarCraft 2 API with a bot written in TypeScript.

It uses protobuf-ts to convert the official protocol files to TypeScript interfaces, enums, and serialization methods.

This project is similar to @node-sc2/core and @node-sc2/proto, which are written in JavaScript and use pbjs to convert the official proto files to JSON (instead of TypeScript).

Usage

This library provides several things:

1) The StarCraft2Client Class

StarCraft 2 exposes its API via a WebSocket server built-in to the game. (It is only available if you launch the game with some specific flags.) The StarCraft2Client class is an abstraction that can be used to easily send messages over the WebSocket connection.

For example:

import { launchStarCraft2, StarCraft2Client } from "s2client-api-typescript";

main().catch((err) => {
  console.error("Failed to run the program:", err);
});

async function main() {
  await launchStarCraft2();

  const client = new StarCraft2Client();
  await client.connect(); // Establishes a WebSocket connection with the game.

  const pingResponse = await client.ping();
  console.log(pingResponse);
}

2) StarCraft 2 API Interfaces and Enums

The official StarCraft 2 protocol files contain the interfaces and enums that are used in the API. These are automatically converted to TypeScript with the protobuf-ts tool and are exported from this library your use.

import { Race } from "s2client-api-typescript";

const MY_RACE = Race.Protoss;

Additionally, this library includes enums that were parsed from the "stableid.json" file (which maps unit/ability/upgrade numbers to names).

3) Helper Functions

When writing your bot, this library offers some helper functions that can get you up and running faster:

• launchStarCraft2
• getMapPath

The helper functions are described in more detail in the documentation; see below.

4) CSpell Dictionary

If you use CSpell, then you can import the StarCraft 2 dictionary by adding an "import" line to your "cspell.json" file:

"import": ["s2client-api-typescript/dictionaries/cspell-starcraft2.json"],

Docs

See the automatically generated TypeDoc documentation for every export that this library provides.