Introduction

dotnet wrapper for Blizzards s2protocol for decoding/parsing StarCraft II replays (*.SC2Replay) using IronPython (2.7)

Getting started

Installation

• dotnet 8:

dotnet add package IronPython.StdLib --version 2.7.12
dotnet add package s2protocol.NET

• dotnet 6/7:

dotnet add package IronPython.StdLib --version 2.7.12
dotnet add package s2protocol.NET --version 0.6.12

Usage

IronPyhton has a known memory leak Issue - try initializing the ReplayDecoder just once and reusing it.

public static readonly string? assemblyPath = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);

ReplayDecoder decoder = new(assemblyPath);
Sc2Replay? replay = await decoder.DecodeAsync(pathToSC2Replay);
Console.WriteLine(replay.Header.BaseBuild);

Optional options:

ReplayDecoder decoder = new(assemblyPath);

ReplayDecoderOptions options = new ReplayDecoderOptions()
{
    Details = false,
    Metadata = false,
    MessageEvents = false,
    TrackerEvents = true,
    GameEvents = false,
    AttributeEvents = false
};

CancellationTokenSource cts = new();

Sc2Replay? replay = await decoder.DecodeAsync(pathToSC2Replay, options, cts.Token);
Console.WriteLine(replay.TrackerEvents.SUnitBornEvents.FirstOrDefault());

Multiple replays:

ReplayDecoder decoder = new(assemblyPath);
var folder = "path_to_replay_folder";
List<string> replays = Directory.GetFiles(folder, "*.SC2Replay").ToList();
ReplayDecoderOptions options = new ReplayDecoderOptions() { TrackerEvents = false };
int threads = 8;
CancellationTokenSource cts = new();

int decoded = 0;
int errors = 0;
await foreach (DecodeParallelResult decodeResult in decoder.DecodeParallelWithErrorReport(replays, 2, options, cts.Token))
{
    if (decodeResult.Sc2Replay == null)
    {
        Console.WriteLine($"failed decoding replay {decodeResult.ReplayPath}: {decodeResult.Exception}");
        errors++;
    }
    else
    {
        Console.WriteLine($"{decoded} {decodeResult.Sc2Replay.Details?.DateTimeUTC}");
        decoded++;
    }
}

Known Limitations / ToDo

GameEvents

STriggerSoundLengthSyncEvent => no data SControlGroupUpdateEvent => no mask

ChangeLog

v0.8.0

Breaking Changes

• dotnet 8
• SC2 Patch 5.0.13 - s2protocol 92028
• PingMessageEvents

v0.8.0-rc1.0

Breaking Changes

• dotnet 8
• removed logging
• improved error handling

v0.6.12

• Protocol 91115

v0.6.11

• Protocol 90136

v0.6.10

• Protocol 89720

v0.6.9

• Protocol 89634
• Fix Gametime to UTC

v0.6.8

• Catch UnitIndex BigInteger
• New parallel decoding with ErrorReport: decoder.DecodeParallelWithErrorReport
• Parallel decoding tests

v0.6.7

• Catch Currupted Trackerevents
• Protocoll 88500 fix

v0.6.6

• Call GC.Collect() in dispose to release file locks
• Disabled default console-logging
• Added Test for protocol 88500 (5.0.10)

v0.6.5

• Save full path in FileName

v0.6.4

• Patch 5.0.9 - Protocol 87702

v0.6.3

• Python.StdLib to version 2.7.12
• JsonIgnore on UnitBorn <-> UnitDied cycles

v0.6.2

• GameEvents
• AttributeEvents
• Tracker-Unit-Events mapping (Born -> Died ...)
• Tracker-Unit-Events UnitIndex from protocol.unit_tag(index, recycle)

v0.6.1

• Fixed some types (nullable/BigInteger/long)
• Initdata is now available
• Json de-/serialization

v0.6.0

• Init