s2protocol-ts

TypeScript port of Blizzard's s2protocol library for parsing StarCraft II replay files. Designed to work with Bun.

Installation

``bash
bun add s2protocol-ts
`

The package includes mpyqjs2 as a dependency for reading .SC2Replay (MPQ archive) files.

Usage

$3

`typescript
import { latest, build, decodeString, toJsonSafe } from 's2protocol-ts';

// Get the latest protocol
const protocol = latest();

// Or get a specific protocol version
const protocol95299 = build(95299);

// Decode replay header (from MPQ archive user data)
const header = protocol.decode_replay_header(headerContents);
console.log('Base build:', header.m_version.m_baseBuild);

// Decode game details
const details = protocol.decode_replay_details(detailsContents);
console.log('Map:', decodeString(details.m_title));

// Decode game events
for (const event of protocol.decode_replay_game_events(gameEventsContents)) {
console.log(event._event, event._gameloop);
}

// Decode tracker events
for (const event of protocol.decode_replay_tracker_events(trackerContents)) {
console.log(event._event);
}

// Convert to JSON-safe format (Uint8Array -> string, BigInt -> string)
const jsonSafe = toJsonSafe(details);
console.log(JSON.stringify(jsonSafe, null, 2));
`

$3

SC2Replay files are MPQ archives. The package includes mpyqjs2 for reading them:

`typescript
const mpyqjs = require('mpyqjs2/mpyq.js');
import { latest, build, processDetailsData } from 's2protocol-ts';

// Open replay file
const archive = new mpyqjs.MPQArchive('replay.SC2Replay');

// Read header using latest protocol
const headerContents = new Uint8Array(archive.header.user_data_header.content);
const header = latest().decode_replay_header(headerContents);

// Get correct protocol for this replay
const protocol = build(header.m_version.m_baseBuild);

// Read and decode details
const detailsContents = new Uint8Array(archive.readFile('replay.details'));
let details = protocol.decode_replay_details(detailsContents);

// Convert cache handles to URLs
details = processDetailsData(details);
console.log('Cache handles:', details.m_cacheHandles);
`

$3

`bash


Show available options

bun run ./src/cli.ts --help

Print replay header

bun run ./src/cli.ts --header replay.SC2Replay

Print game details

bun run ./src/cli.ts --details replay.SC2Replay

Print all game events

bun run ./src/cli.ts --gameevents replay.SC2Replay

Print tracker events as JSON

bun run ./src/cli.ts --trackerevents --json replay.SC2Replay

Print everything

bun run ./src/cli.ts --all replay.SC2Replay

List supported protocol versions

bun run ./src/cli.ts --versions
`

API Reference

$3

- latest() - Get the latest protocol module
- build(version: number) - Get a specific protocol version
- listAll() - List all supported protocol versions
- isSupported(version: number) - Check if a version is supported

$3

Each protocol module provides:

- decode_replay_header(contents) - Decode replay header
- decode_replay_details(contents) - Decode game details
- decode_replay_initdata(contents) - Decode init data
- decode_replay_game_events(contents) - Generator for game events
- decode_replay_message_events(contents) - Generator for message events
- decode_replay_tracker_events(contents) - Generator for tracker events
- decode_replay_attributes_events(contents) - Decode attributes

$3

- cacheHandleUri(handle) - Convert cache handle to URL
- processDetailsData(details) - Process details with cache handle URLs
- processInitData(initdata) - Process init data with cache handle URLs
- processScopeAttributes(scopes, callback) - Process attributes
- decodeString(data) - Decode Uint8Array as UTF-8 string
- toJsonSafe(obj) - Convert to JSON-safe format

$3

- BitPackedBuffer - Low-level bit buffer reading
- BitPackedDecoder - Bit-packed protocol decoder
- VersionedDecoder - Versioned protocol decoder (with skip markers)

$3

- BitPackedWriteBuffer - Low-level bit buffer writing
- BitPackedEncoder - Bit-packed protocol encoder
- VersionedEncoder - Versioned protocol encoder

$3

Game attribute constants are exported from attributes:

`typescript
import { attributes } from 's2protocol-ts';

console.log(attributes.RACE); // 3001
console.log(attributes.GAME_SPEED); // 3000
`

Supported Protocol Versions

This package includes all 89 protocol versions from build 15405 to 95299, covering StarCraft II replays from all game versions:

- Oldest: 15405 (Wings of Liberty beta)
- Newest: 95299 (current patch 5.0.15)

Protocol versions are automatically selected based on the replay's base build number. Use listAll() to see all supported versions or isSupported(version)` to check if a specific version is available.

License

MIT License - Based on code copyright (c) 2013-2017 Blizzard Entertainment

Credits

Original Python implementation by Blizzard Entertainment.
TypeScript port designed for Bun runtime.