Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Zamiell/s2client-api-typescript
The StarCraft 2 API for TypeScript
https://github.com/Zamiell/s2client-api-typescript
Last synced: 3 months ago
JSON representation
The StarCraft 2 API for TypeScript
- Host: GitHub
- URL: https://github.com/Zamiell/s2client-api-typescript
- Owner: Zamiell
- License: mit
- Created: 2022-04-21T07:32:29.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-23T07:33:36.000Z (9 months ago)
- Last Synced: 2024-03-24T19:20:21.121Z (8 months ago)
- Language: TypeScript
- Homepage:
- Size: 2.9 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-sc2-ai - s2client-api-typescript
README
# s2client-api-typescript
[](https://www.npmjs.com/package/s2client-api-typescript)
This is a package that allows you to communicate with the [StarCraft 2](https://starcraft2.com/en-us/) API with a bot written in [TypeScript](https://www.typescriptlang.org/).
It uses [protobuf-ts](https://github.com/timostamm/protobuf-ts) to convert [the official protocol files](https://github.com/Blizzard/s2client-proto/tree/master/s2clientprotocol) to TypeScript interfaces, enums, and serialization methods.
This project is similar to [@node-sc2/core](https://github.com/node-sc2/core) and [@node-sc2/proto](https://github.com/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](https://en.wikipedia.org/wiki/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:
```ts
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](https://github.com/Blizzard/s2client-proto/tree/master/s2clientprotocol) contain the interfaces and enums that are used in the API. These are automatically converted to TypeScript with the [protobuf-ts](https://github.com/timostamm/protobuf-ts) tool and are exported from this library your use.
```ts
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](https://cspell.org/), then you can import the StarCraft 2 dictionary by adding an "import" line to your "cspell.json" file:
```json
"import": ["s2client-api-typescript/dictionaries/cspell-starcraft2.json"],
```
## Docs
See the [automatically generated TypeDoc documentation](https://zamiell.github.io/s2client-api-typescript/modules.html) for every export that this library provides.