s2protocol-ts

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

Installation

bun add s2protocol-ts

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

Usage

As a Library

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));

With MPQ Archive

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

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);

CLI Usage

# 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

Protocol Functions

• 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

Protocol Module Methods

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

Utility Functions

• 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

Decoders

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

Encoders

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

Attributes

Game attribute constants are exported from attributes:

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.