blizzard / s2protocol

Python library to decode StarCraft II replay protocols

S2 Protocol

s2protocol is a reference Python library and standalone tool to decode StarCraft II replay files into Python data structures.

Currently s2protocol can decode these structures and events:

• replay header
• game details
• replay init data
• game events
• message events
• tracker events

s2protocol can be used as a base-build-specific library to decode binary blobs, or it can be run as a standalone tool to pretty print information from supported replay files.

Note that s2protocol does not expose game balance information or provide any kind of high level analysis of replays; it's meant to be just the first tool in the chain for your data mining application.

Supported Versions

s2protocol supports all StarCraft II replay files that were written with retail versions of the game. The current plan is to support all future publicly released versions, including public betas.

Tracker Events

Some notes on tracker events:

• Tracker events are new in version 2.0.8, they do not exist in replays recorded with older versions of the game.
• Convert unit tag index, recycle pairs into unit tags (as seen in game events) with protocol.unit_tag(index, recycle)
• Interpret the NNet.Replay.Tracker.SUnitPositionsEvent events like this:

    unitIndex = event['m_firstUnitIndex']
    for i in range(0, len(event['m_items']), 3):
        unitIndex += event['m_items'][i + 0]
        x = event['m_items'][i + 1] * 4
        y = event['m_items'][i + 2] * 4
        # unit identified by unitIndex at the current event['_gameloop'] time is at approximate position (x, y)

• Only units that have inflicted or taken damage are mentioned in unit position events, and they occur periodically with a limit of 256 units mentioned per event.
• NNet.Replay.Tracker.SUnitInitEvent events appear for units under construction. When complete you'll see a NNet.Replay.Tracker.SUnitDoneEvent with the same unit tag.
• NNet.Replay.Tracker.SUnitBornEvent events appear for units that are created fully constructed.
• You may receive a NNet.Replay.Tracker.SUnitDiedEvent after either a UnitInit or UnitBorn event for the corresponding unit tag.
• In NNet.Replay.Tracker.SPlayerStatsEvent, m_scoreValueFoodUsed and m_scoreValueFoodMade are in fixed point (divide by 4096 for integer values). All other values are in integers.
• There's a known issue where revived units are not tracked, and placeholder units track death but not birth.

License

Copyright (c) 2013 Blizzard Entertainment

Open sourced under the MIT license. See the included LICENSE file for more information.

Acknowledgements

The standalone tool uses mpyq to read mopaq files.

Thanks to David Joerg and Graylin Kim of GGTracker for design feedback and beta-testing.

Ports and Related Projects

There are unofficial ports of s2protocol (and the required MPQ parser) available in other languages:

Go

This Go implementation is a standalone project for both the MPQ parser and the s2protocol implementation (also provide some higher level API):

Go MPQ parser: https://github.com/icza/mpq

Go s2protocol: https://github.com/icza/s2prot

Java

This Java implementation is part of the open source Scelight project (which is much more than just a replay parser, it also gives a high-level API):

Java MPQ parser: https://github.com/icza/scelight/tree/master/src-app-libs/hu/belicza/andras/mpq

Java s2protocol: https://github.com/icza/scelight/tree/master/src-app/hu/scelight/sc2/rep/s2prot

s2protocol's Issues

Dev community resources for working with SC2 replays?

I'm not really sure how to get a hold of you guys, so sorry if this is the wrong place for this.

In this reddit thread, there have been a few questions (mostly from me) about what sort of resources are going to be available moving forward. s2protocol is awesome, but having poked in a bit, the data is, well, complex.

I'm hoping that a lot of people get interested in data mining, but there are a lot of hurdles early on that I think we can work through together. Was Blizzard planning on putting together a community for everyone to collaborate around, or should we just go for it?

A first step in my mind might be to populate the wiki here in the github repo with more details.

Resources used innacuracies?

If I take the last NNet.Replay.Tracker.SPlayerStatsEvent from a replay file that matches the m_elapsedGameLoops and add most of the things up, I can never get the same value as displayed in the game client for resources collected when reviewing match history.

For example, SC2 shows total resources collected as 35549 for this player, based on the last stats entry in the replay file I'm adding the following fields:

         'm_scoreValueMineralsCurrent': 271,
         'm_scoreValueMineralsLostArmy': 13225,
         'm_scoreValueMineralsLostEconomy': 3100,
         'm_scoreValueMineralsLostTechnology': 224,
         'm_scoreValueMineralsUsedActiveForces': 925,
         'm_scoreValueMineralsUsedCurrentEconomy': 5200,
         'm_scoreValueMineralsUsedCurrentTechnology': 5400,
         'm_scoreValueMineralsUsedInProgressArmy': 0,
         'm_scoreValueMineralsUsedInProgressEconomy': 0,
         'm_scoreValueMineralsUsedInProgressTechnology': 0,
         'm_scoreValueVespeneCurrent': 1569,
         'm_scoreValueVespeneLostArmy': 5425,
         'm_scoreValueVespeneLostEconomy': 0,
         'm_scoreValueVespeneLostTechnology': 0,
         'm_scoreValueVespeneUsedActiveForces': 500,
         'm_scoreValueVespeneUsedCurrentEconomy': 0,
         'm_scoreValueVespeneUsedCurrentTechnology': 1950,
         'm_scoreValueVespeneUsedInProgressArmy': 0,
         'm_scoreValueVespeneUsedInProgressEconomy': 0,
         'm_scoreValueVespeneUsedInProgressTechnology': 0,

I'm skipping the *UsedCurrentArmy lines as that seems to already be incorporated in the *UsedActiveForces lines. Even if I subtract the original base + worker values from my totals, I'm still off from what SC2 client shows.

Any ideas? Should this match the client match history amounts?

Gametype?

How to identify if the Gametype is AutoMM, Custom or Singleplayer?

Some mmr values being returned as -36400

I have noticed that a bunch of replays are returning -36400 as the mmr value for players inside the m_syncLobbyState -> m_userInitialData->m_scaledRating

It is also incorrect in the metadata section.

Here are 3 example replays

Ladder Games:
http://sc2replaystats.com/download/5745952
http://sc2replaystats.com/download/5861805

Custom Game:
http://sc2replaystats.com/download/5835203

In the ladder games I do not recall if they where playing ranked or unranked.

This season I have seen this -36400 mmr value in 30% of the replays that have been uploaded (around 36,000 replays)

Missing Protocol FIle for 3.11.0.51149

Would love it if we could get back to where the protocol files where being released BEFORE the patch was live, saves me from having to back process some data.

'_gameloop' times being off?

Im converting my sc2Reply to json and for the last SPlayerStatsEvent I am getting

{
    "m_playerId": 1, 
    "_eventid": 0, 
    "_event": "NNet.Replay.Tracker.SPlayerStatsEvent", 
    "_bits": 1312, 
    "_gameloop": 38911, 
    "m_stats": {
        "m_scoreValueVespeneUsedCurrentTechnology": 2925, 
        "m_scoreValueVespeneFriendlyFireArmy": 0, 
        "m_scoreValueMineralsFriendlyFireTechnology": 0, 
        "m_scoreValueMineralsUsedCurrentEconomy": 12475, 
        "m_scoreValueVespeneLostEconomy": 483, 
        "m_scoreValueMineralsUsedCurrentArmy": 4700, 
        "m_scoreValueMineralsKilledArmy": 12200, 
        "m_scoreValueVespeneCollectionRate": 1478, 
        "m_scoreValueMineralsUsedActiveForces": 4700, 
        "m_scoreValueMineralsCollectionRate": 2525, 
        "m_scoreValueWorkersActiveCount": 72, 
        "m_scoreValueVespeneUsedCurrentArmy": 3925, 
        "m_scoreValueVespeneLostArmy": 1917, 
        "m_scoreValueMineralsKilledEconomy": 5700, 
        "m_scoreValueMineralsUsedCurrentTechnology": 8625, 
        "m_scoreValueVespeneUsedInProgressArmy": 0, 
        "m_scoreValueMineralsLostEconomy": 3563, 
        "m_scoreValueMineralsCurrent": 39269, 
        "m_scoreValueMineralsLostArmy": 3622, 
        "m_scoreValueVespeneKilledArmy": 7900, 
        "m_scoreValueVespeneKilledTechnology": 25, 
        "m_scoreValueVespeneKilledEconomy": 0, 
        "m_scoreValueMineralsUsedInProgressTechnology": 100, 
        "m_scoreValueMineralsUsedInProgressArmy": 0, 
        "m_scoreValueMineralsFriendlyFireArmy": 0, 
        "m_scoreValueVespeneUsedActiveForces": 3925, 
        "m_scoreValueVespeneCurrent": 21883, 
        "m_scoreValueMineralsLostTechnology": 2139, 
        "m_scoreValueMineralsUsedInProgressEconomy": 0, 
        "m_scoreValueMineralsFriendlyFireEconomy": 0, 
        "m_scoreValueVespeneUsedInProgressTechnology": 0, 
        "m_scoreValueFoodMade": 1134592, 
        "m_scoreValueMineralsKilledTechnology": 350, 
        "m_scoreValueVespeneLostTechnology": 100, 
        "m_scoreValueVespeneFriendlyFireEconomy": 0, 
        "m_scoreValueVespeneUsedInProgressEconomy": 0, 
        "m_scoreValueVespeneUsedCurrentEconomy": 0, 
        "m_scoreValueVespeneFriendlyFireTechnology": 0, 
        "m_scoreValueFoodUsed": 647168
    }

I know that ladder games are at a faster speed (x1.4) than real time. However, when I load the same sc2Reply into GGGreplays.com, they are telling me the total game time is 29minutes 50seconds. No matter how I do the math I cannot get my game times to line up with theirs - so am I completely looking at this wrong or is their math off?

Here is the replay in question -
Eastwatch LE (251).zip

Thanks for the support,

• Nef

Feature Request: Ranked/Unranked info for each Player

As per #10 it seems that it is not possible to determine if a player in a AMM game was playing as ranked or unranked. For tools that sort and organize replays for other players this information would be very useful.

People who would use this data, please leave a comment saying so.

Missing Protocol 62347 (patch 4.2.0.62347)

The protocol for the new patch didn't seem to get updated. I know this is an automated job which means its sadly has failed.

Can someone please look into getting the protocol updated, using the previous version "seems" to be working but it does not make me feel comfortable at all.

[Feature Request] Add the matchID or another unique identifier to the replay

Hey,

this is not really a request for the s2protocol, but for the contents of a replay. Currently is quite hard to say determine that two or more replays are from the same match; all from a different match participant (player, observer, etc).
There is no matchID in it, the matchtime is based on the users PC, gameloops can differ depending on when a player leaves a match (especially for team matches), etc...
There must be a matchID somewhere in the Battlenet-universe for a match. Is it possible to include this in the replay or some other unique hash, to identify the match the replay belongs to?

Thanks and greetings,

Andy!

Fix the automated bulid process to add a new version file in new location

Currently the automated build is wiping out the documentation and putting protocol versions in the root folder.

A new proposed layout is in #40.

How to get started?

This is quite frustrating! I have been scouring the internet for some sort of idea how to get started with this replay parser. I can get the "load programmatically" http://s2protocol.readthedocs.io/en/latest/tutorial.html#using-s2protocol-programmatically

`import mpyq

archive = mpyq.MPQArchive("C:/Users/Tim/Desktop/Replays/replay1.SC2Replay")
contents = archive.header['user_data_header']['content']

from s2protocol import versions
header = versions.latest().decode_replay_header(contents)`

I get the header object result but it seems it is just a bunch of game version, and bunch of not what I need beeswax.

What other parameters are there besides ['user_data_header'] and ['content']? What do I need to parse to get the game events? such as number of workers, or minerals mined or game time?

The documentation does no help it just says "Oh you would need to load the files programmatically", ok, then what? the example was useful to load the replay file but how do I read the bloody contents?

I am sorry, I am a complete python noob and would prefer to work in R for this but unfortunately the parser is written in python :(

[Question] Calculate the APM correctly

Hey there,

I'm now trying around with this topic since a few days and I'm not able to calculate the same APM you have in the game ("Current APM" and "Average APM"). I thought for the average at the game end it should be easy (just add all events together which calculate in the APM and divide by the duration), but also this is not possible for me to reconstruct, so I would be happy for some help here.

I think there are two questions:

• Which events count into the APM? I think only gameevents and my researches ended up in these: apmEvents = ['NNet.Game.SSelectionDeltaEvent', 'NNet.Game.SCmdEvent', 'NNet.Game.SControlGroupUpdateEvent']
  Is that correct?
• What's the formula? For example if I start a match and directly select a unit, SC2 says my APM is 12 or something :) So I'm wondering what the formula is.

Thanks for your help and greetings from Cologne!

Missing HotS Beta base builds 23925 and 24247

Early HotS beta replays cannot be parsed.

$ ~/projects/s2protocol$ python s2protocol.py --initdata ../sc2reader/test_replays/2.0.0.23925/Akilon\ Wastes.SC2Replay 
Unsupported base build: 23925
$ ~/projects/s2protocol$ python s2protocol.py --initdata ../sc2reader/test_replays/2.0.0.24247/molten.SC2Replay
Unsupported base build: 24247

Be able to tell if a replay is an Arcade Game

Not sure if there is a sure fire way to tell if a replay is an arcade game, if there is would love to know.

I somewhat lean on a few things like if the format ends up being 1v1, and there are more than 2 players I will reject it and also using a black list of things to just straight up reject based on map name.

If there is not something that can tell me for sure if a replay is an arcade game would love to see something. arcade games cause my site a lot of problems and would prefer to just straight up reject them.

Bad gameloop values in replays from loaded/saved games

If you save a game, and then load it and play it, the resulting replay file has events with bad _gameloop values (e.g. 4294970998). They are bad in that they are huge numbers with some very high-order bits set.

Example replay: https://dl.dropboxusercontent.com/u/556553/put_things_here/s2protocol_issue.SC2Replay

Demonstration of the problem: https://gist.github.com/dsjoerg/c75ae52ce8099b430ee5

Perhaps the solution is to simply mask out the higher-order bits of the gameloop? That's what I did in sc2reader: GraylinKim/sc2reader@c860d8e

missing modules on Linux

After cloning the repository and running
python setup.py install --user
on a Fedora 26 machine, issuing
s2_cli.py --versions
results in

Traceback (most recent call last):
File "/usr/bin/s2_cli.py", line 4, in
import('pkg_resources').run_script('s2protocol==3.19.1.58600.5', 's2_cli.py')
File "/usr/lib/python2.7/site-packages/pkg_resources/init.py", line 741, in run_script
self.require(requires)[0].run_script(script_name, ns)
File "/usr/lib/python2.7/site-packages/pkg_resources/init.py", line 1502, in run_script
exec(code, namespace, namespace)
File "/home/mic/.local/lib/python2.7/site-packages/s2protocol-3.19.1.58600.5-py2.7.egg/EGG-INFO/scripts/s2_cli.py", line 14, in
import attributes as _attr
ImportError: No module named attributes

On other occasions I saw "versions" reported missing, but I didn't take note what triggered it.

I then tried to run s2_cli.py in directory s2protocol like so:
./s2_cli.py --versions
resulting in:

Traceback (most recent call last):
File "./s2_cli.py", line 374, in
main()
File "./s2_cli.py", line 243, in main
files = versions.list_all()
AttributeError: 'module' object has no attribute 'list_all'

Looking for list_all revealed that it is used like this: ...versions.list_all() but there is no versions.py in the repository.

Any help regarding this would be much appreciated - I am trying to go through a million replays, but replaying them using the engine takes WAY too long.

For teams: any way of knowing the team leagues, and/or wether or not the team is arranged?

I know each each player has a highest_league, but that's only for their 1v1 ladder rank.

For teams games, though, I would like to know:

• Are the teams arranged or random?
• For random teams, which random league is each player? I'm looking for something that would give me 'random 3v3 bronze, random 3v3 silver and random 3v3 diamond'.
• For arranged teams, which league is each team?

Are these things currently available in the replays at all, or does one have to resort to scraping to get this information?

Export LotV Game Balance Data

It's great that you added protocol support for LotV beta replays. Thanks for that.

However many of the data extracted from replays with s2protocol is only meaningful with the balance data that can be exported from the map editor (Starcraft II Editor), as File -> Export Balance Data.

Unfortunately this can only be done for Wings of Liberty and Heart of the Swarm expansions. And the LotV beta installation does not include a map editor.

When can we expect Balance Data Export to be available for LotV?

Thanks.

Question: Does the s2protocol output if the replay is ranked vs unranked for each player ?

I'm not having any luck tracking down the flag that would tell if a player was playing a ranked game or an unranked game.

Any help would be appreciated.

HotS Build 34846

Would it be possible to get an updated protocol file for Heroes of the Storm build 34846?

It seems that there are some game events (and possibly other events) that aren't covered by the latest available protocol file (34835).

new protocol needed for 3.3.0 / 42932

Hi, some replay parsing is crashing / failing, can we get a new protocol file?

Thank you, —David

--metadata MMR static for unranked games, and missing for teams

Figured I would lump the two things I have noticed into one ticket. If you would prefer I can break them apart.

But I have implemented the metadata processing into my version of s2protocol and have been processing replays for about a week now with it. Looking at someones account that I know are unranked replays, his mmr is always 4190, win or lose. This might be expected, but I actually expected the mmr value to still change for an unranked game (just not displayed on the UI).

Example unranked replays.
http://sc2replaystats.com/download/4483632
http://sc2replaystats.com/download/4483619

For teams, it seems like 99% of the time an mmr value is not returned. Have been unable to see the pattern for why they return. But here is an example of a replay where i'm ranked as random teams (m3 I believe, dont know my mmr off hand)

http://sc2replaystats.com/download/4445995

In this example claptrap has an mmr value but breath and other do not (claptrap and breath queued together)

Export json protocol files

It has come to light that it might be possible to get the version protocol files in another format other than the python version.

It would be beneficial if the protocol files where exported in json, could stick them in the new proposed layout #40 except I would change the layout to have one more folder layer stating the format they are in (json, python, xml, ext).

Having the format in json would make it easier for others to recreate the s2protocol in another language.

Is there any documentation on these NNet.Game.*Event(s) ??

Hi, so i cloned the repo and got the data out of the replay just fine, really a great tool. I was wondering though if there was more documentation on these things?? I read the documentation on a project that uses this protocol (sc2reader) at https://sc2reader.readthedocs.io/en/latest/ and it was really useful, but i thouth blizzard might have all of these events documented somewhere? alot are self explanatory, but maybe not all of the nuances of the event. E.g. Tracker events we have a unitTypename called mineralfield750, so i guess some worker was rallied to this mineral patch, or maybe this event launches every single time a worker returns to the patch, which might be far fetched but without the concrete documentation of the events its harder to make out. Thanks in advance. and again, thanks for making this tool so easy to use and widely available.

Needs a setup.py module

There is no setup.py module here. mpyq can just be a dependency added into install_requires as long as mpyq is separated out into a new repository

How are PIDs assigned?

For basic XvX ladder games this is pretty straight forward but there are a number of alternate game scenarios that people are bound to run into:

This game is a 1v2 AI that seems to assign PIDs as follows:

Team 1:
    Player 1 - Tzuqris
Team 2:
    Player 3 - A.I. 2 (Very Easy)
    Player 4 - A.I. 3 (Very Easy)

This game is a 1v2 humans that seems to assign PIDs as follows:

Team 1:
    Player 1 - Brothus
Team 2:
   Player 2 - Collision
   Player 3 - goatsonfire

This game from 1.2.2 (didn't have a newer example on hand) is a 1v1 with 6 observers. Correctly assigning ids to observers is important for things like chat messages and is required for correctly mapping game events. The linked replay isn't a great example because there is no observer chat, maybe someone can find a better one.

Open source s2protocol (+mpq parser) implementation in Java and Go

Hello Everyone,

I'd like to announce that I have implemented / ported the s2protocol library to Java and Go languages. They are available as open-source projects on Github.

Java implementation is part of the open source Scelight project (which is much more than just a replay parser, it also gives a high-level api):

Java MPQ parser: https://github.com/icza/scelight/tree/master/src-app-libs/hu/belicza/andras/mpq
Java s2protocol: https://github.com/icza/scelight/tree/master/src-app/hu/scelight/sc2/rep/s2prot

Go implementation is a standalone project for both MPQ and s2protocol implementation:

Go MPQ parser: https://github.com/icza/mpq
Go s2protocol: https://github.com/icza/s2prot

The Go implementation is fairly new and will improve over time. As of May 22, 2017, s2prot is also available as a standalone, self-contained CLI app which parses a passed replay file, and outputs data from the replay in JSON format. The standalone s2prot app can be downloaded here: https://github.com/icza/s2prot/releases

Hope this helps others. Should you have any questions regarding these libraries, I'd be happy to answer them.

Have fun coding and parsing replays. Don't forget to star / watch if you like them.

Morphing an Archon from darktemplar does not have an NNet.Replay.Tracker.SUnitTypeChangeEvent

I would have expect there to be an event for for the darktemplar changing types into a Archon.

I see an NNet.Replay.Tracker.SUnitInitEvent for when the Archon was created, but i'm not seeing the NNet.Replay.Tracker.SUnitTypeChangeEvent for the Dark Templar

Code Examples

Can you give us some examples how this library works on the documentation the programmatic way. Like

• How to see the players actions.
• How to see the players and see the winner.
• How to get the chat log.
• How to get the JSON of something above.

Can be a fake example one. But a snippet of code helps a lot when you don't know nothing about a library. I know this can change by protocol changes, but it's give us a idea how this library should work.

Creating new sample issue to test email distro

Bad Player Team and Result values

In the 3v3 game below, 1 player on the winning team reports a loss and one player on the losing team reports a win. How is this possible?

Replay attached as a png (rename it):

(env)graylinkim@graylin-ubuntu:~/projects/s2protocol$ s2protocol --details example.SC2Replay
...
 'm_playerList': [
                  {'m_color': {'m_a': 255, 'm_b': 30, 'm_g': 20, 'm_r': 180},
                   'm_control': 2,
                   'm_handicap': 100,
                   'm_name': 'Boom',
                   'm_observe': 0,
                   'm_race': 'Terran',
                   'm_result': 1,
                   'm_teamId': 0,
                   'm_toon': {'m_id': 1694745,
                              'm_programId': '\x00\x00S2',
                              'm_realm': 1,
                              'm_region': 2}},
                  {'m_color': {'m_a': 255, 'm_b': 255, 'm_g': 66, 'm_r': 0},
                   'm_control': 2,
                   'm_handicap': 100,
                   'm_name': 'Aspirates',
                   'm_observe': 0,
                   'm_race': 'Terran',
                   'm_result': 1,
                   'm_teamId': 0,
                   'm_toon': {'m_id': 1404640,
                              'm_programId': '\x00\x00S2',
                              'm_realm': 1,
                              'm_region': 2}},
                  {'m_color': {'m_a': 255,
                               'm_b': 234,
                               'm_g': 167,
                               'm_r': 28},
                   'm_control': 2,
                   'm_handicap': 100,
                   'm_name': 'loropendejo',
                   'm_observe': 0,
                   'm_race': 'Terran',
                   'm_result': 1,
                   'm_teamId': 1,
                   'm_toon': {'m_id': 1840716,
                              'm_programId': '\x00\x00S2',
                              'm_realm': 1,
                              'm_region': 2}},
                  {'m_color': {'m_a': 255, 'm_b': 129, 'm_g': 0, 'm_r': 84},
                   'm_control': 2,
                   'm_handicap': 100,
                   'm_name': 'SNIPER',
                   'm_observe': 0,
                   'm_race': 'Terran',
                   'm_result': 2,
                   'm_teamId': 1,
                   'm_toon': {'m_id': 1890674,
                              'm_programId': '\x00\x00S2',
                              'm_realm': 1,
                              'm_region': 2}},
                  {'m_color': {'m_a': 255,
                               'm_b': 41,
                               'm_g': 225,
                               'm_r': 235},
                   'm_control': 2,
                   'm_handicap': 100,
                   'm_name': 'Gogeta',
                   'm_observe': 0,
                   'm_race': 'Terran',
                   'm_result': 2,
                   'm_teamId': 1,
                   'm_toon': {'m_id': 497421,
                              'm_programId': '\x00\x00S2',
                              'm_realm': 1,
                              'm_region': 2}},
                  {'m_color': {'m_a': 255,
                               'm_b': 14,
                               'm_g': 138,
                               'm_r': 254},
                   'm_control': 1,
                   'm_handicap': 100,
                   'm_name': 'Foco',
                   'm_observe': 1,
                   'm_race': 'Terran',
                   'm_result': 2,
                   'm_teamId': 0,
                   'm_toon': {'m_id': 1678160,
                              'm_programId': '\x00\x00S2',
                              'm_realm': 1,
                              'm_region': 2}}],
...
}

Tie interceptors to the carrier that built them

I'm not sure the best way to connect interceptors to the carrier that produced them in the replay file. Any suggestions would be appreciated.

If there is no good way, can we add a way ?

m_timeUTC

what format is the m_timeUTC is in from the details output in s2protocol-cli.

Missing Protocol 58400 for Patch 3.19

Does not look like the automated job for uploading them ran this patch. 3.19 is live on the NA servers.

Tracker events: Known issue where revived units are not tracked

From the readme: "There's a known issue where revived units are not tracked, ..."

This may not be that important for Starcraft 2, I'm not sure.

But it is crucial for tracking heroes in Heroes of the Storm - it basically means there are only tracker events for heroes until their first death in a match, which often happens in the first 2-3 minutes of a 20-30 minute game.

Could you add a new 'SUnitRevivedEvent' tracker event for this? Or even record more than one 'SUnitBornEvent' / 'SUnitDiedEvent' tracker events as revived units are born / die / revive / die?

Python 3.x

Hello,

is there any intention to make S2protocol be executable in a python 3.x enviroment?

Guess I can´t fix it. To unexperienced in programming.

Kay

protocol37117.py

Hi there,

Any plans to add a new file for the latest update ?

Looks like it's a fairly minor change : barrett777/Heroes.ReplayParser@2582e1f

Thanks :)

--attributeevents missing scopes section on resume from replay, replays

I have noticed that on replays that are resumed from replay that the scopes section that is returned from the --attributevents is missing.

Here is an example replay http://sc2replaystats.com/download/4442170

Here is a piece of the section that is missing from the above replay (sample is from another replay)
the section i'm talking about is this "scopes":{"16":{"4000":[{"attrid":4000,"namespace":999,"value":"Norm"}],"3009":[{"attrid":3009,"namespace":999,"value":"Amm"}],"3......

Let me know if you need any more info.

Heroes of the Storm events

Are there plans to add Heroes of the Storm events to this or to a new repo?

If there are no plans, can we at least get the debug bytecode for the protocol so that we can format the structs ourselves? As an example of "debug bytecode", here's the bnet protocol visible in a WoD Debug build: https://gist.github.com/Mischanix/8776b09b3489a6234ff4

Getting started error

Hi!

I'm looking to use s2protocol with an R wrapper, so I'm very new to Python. However, when I use the getting started code from the Docs (http://s2protocol.readthedocs.io/en/latest/tutorial.html) I am getting an error:

import mpyq
archive = mpyq.MPQArchive('path/to/my/bad/replay/Acolyte LE (9).SC2Replay')
contents = archive.header['user_data_header']['content']
from s2protocol import *

This results in the error:

ModuleNotFoundError: No module named 'versions'
---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
<ipython-input-5-08e71ddb17f1> in <module>()
----> 1 from s2protocol import *
C:\Anaconda3\lib\site-packages\s2protocol\diff.py in <module>()
      9 import pprint
     10 
---> 11 import versions
     12 
     13 def diff_things(typeinfo_index, thing_a, thing_b):
ModuleNotFoundError: No module named 'versions'

I have tried importing every which way: from s2protocol import versions or from s2protocol import __versions__ and no luck.

I even tried installing the "dev" branch because I saw there might be some commits there that reorganized things, but also no luck.

Any help?

I am running Python in Anaconda on Windows and I am trying to play around with the library from within the Rodeo IDE. So -- not an ideal development environment and maybe that is causing the issue? Installation via pip went very smoothly though, no errors, and importing the replay file works fine using the mpyq.MPQArchive() function.

What are these events?

I'm working with the TrackerEvents, and there are a few events that I wasn't able to quite identify. Could you explain what these correspond to?

1. haltech
2. BroodlingEscort
3. HighCapacityBarrels

recognizing co-op games

I ran this replay through s2protocol https://lotv.spawningtool.com/35674/download/ with --initdata and got the following result (some stuff removed just to get to the important snippet)

{
    "m_syncLobbyState": {
        "m_gameDescription": {
            "m_maxRaces": 6, 
            "m_maxTeams": 4, 
            "m_hasExtensionMod": false, 
            "m_maxColors": 16, 
            "m_isBlizzardMap": true, 
            "m_gameOptions": {
                "m_competitive": false, 
                "m_practice": false, 
                "m_lockTeams": true, 
                "m_amm": true, 
                "m_battleNet": true, 
                "m_fog": 0, 
                "m_noVictoryOrDefeat": false, 
                "m_heroDuplicatesAllowed": true, 
                "m_buildCoachEnabled": false, 
                "m_advancedSharedControl": false, 
                "m_cooperative": false, 
                "m_clientDebugFlags": 265, 
                "m_observers": 0, 
                "m_teamsTogether": false, 
                "m_randomRaces": false, 
                "m_userDifficulty": 1
            }, 
            "m_defaultDifficulty": 2, 
            "m_isCoopMode": false, 
            "m_mapFileName": "", 
            "m_defaultAIBuild": 0, 
            "m_gameType": 0, 
            "m_hasNonBlizzardExtensionMod": false, 
            "m_randomValue": 3559572045, 
            "m_maxObservers": 12, 
            "m_isRealtimeMode": false, 
            "m_maxUsers": 2, 
            "m_modFileSyncChecksum": 2822893348, 
            "m_mapSizeX": 208, 
            "m_maxPlayers": 4, 
        }
    }
}

Note that although, this game was a coop game, it has both

["m_syncLobbyState"]["m_gameDescription"]["m_gameOptions"]["m_cooperative"] === false
["m_syncLobbyState"]["m_gameDescription"]["m_isCoopMode"] === false

I'm not sure how those would have been read incorrectly from the replay, which would indicate that it's in the replay file itself. Am I misinterpreting what those field are meant for, or were those incorrectly encoded on the replays?

ImportError: No module named decoders

Since last big commit moving protocol files into versions, I can't use it programmatically anymore.
I tried using the pip module as well.

I tried sc2_cli.py and it works no problem but however when I do the basic example in the tutorial documentation

import mpyq

# Using mpyq, load the replay file.
archive = mpyq.MPQArchive('test.SC2Replay')
contents = archive.header['user_data_header']['content']

# Now parse the header information.
from s2protocol import versions
header = versions.latest().decode_replay_header(contents)

Full trace

$ python tester.py
Traceback (most recent call last):
  File "tester.py", line 15, in <module>
    header = versions.latest().decode_replay_header(contents)
  File "/Users/Florian/gitworkspace/s2protocol/s2protocol/versions/__init__.py", line 62, in latest
    return _import_protocol(base_path, module_name)
  File "/Users/Florian/gitworkspace/s2protocol/s2protocol/versions/__init__.py", line 27, in _import_protocol
    return imp.load_module(protocol_module_name, fp, pathname, description)
  File "/Users/Florian/gitworkspace/s2protocol/s2protocol/versions/protocol58400.py", line 21, in <module>
    from decoders import *
ImportError: No module named decoders

I tried putting from s2protocol.decoders import * instead of from decoders import * and I didn't get the error so probably something you'd want to modify in the autogeneration

Feature Request: Unit Killer/Location

I'm not sure what the best place for this is, so I'm posting here for now.

The unit death events would be much more useful if it was extended by an optional killing unit tag and location. Example:

Zergling [B1A0005] (16,20) death at game_loop 2120
killed by SeigeTank [E130002] (17,22) owned by Player 2

We could even drop the killing player since it can be derived from the killing unit.

This extra information would allow us to do much deeper engagement analysis!

Client API endpoint /game - more player information

In the SC2 Client API the end point for /game currently returns

{ "isReplay":false, "displayTime":100.0, "players":[ { "id":1, "name":"AccountName", "type":"user", "race":"Zerg", "result":"Defeat" }, { "id":2, "name":"Player 2", "type":"computer", "race":"random", "result":"Victory" } ] }

What would be useful is to add in some more information into the players object.

Needed Additions:
Character id, Realm Id

Possible Additions:
Server
MMR (before and after game ends values ?)

S2Protocol Asyncronous?

Greetings All,

I'm looking to invest some time into an RTS that requests actions in realtime (async). I've looked in the docs for reference and came up short.

My question is, if i started a game and sent no actions to the environment, will the game continue, or will it hang for an action.

Thanks!

Adding MMR and Tier to Replay File

Currently the MMR and Tier is not stored in the replay file. You can get it from the API, but for back processing replays it would be nice to have this information.

NNet.Replay.Tracker.SUnitDiedEvent Baneling kills missing m_killerUnitTagIndex

When a baneling kills a unit, it does not correctly link the m_killerUnitTagRecycle, and m_killerUnitTagIndex for the unit that died, the info is just blank. It shows the unit died, but does not correctly link back.

I have attached a sample replay where I only killed units with banelings and none of the NNet.Replay.Tracker.SUnitDiedEvent have the flags set correctly.

2016-06-04 - (Z)Breath VS (Z)A.I. 1 (Very Easy).zip

protocol file missing for base build 42253

Hey there,

any plans to add the protocol file for this update?

Thanks and greetings,

Andy!

Lotv Beta Patch 7-13-2015

With the most recent lotv beta patch there seems to be a bunch of changes to the protocol. If you would please upload the latest build protocol file that would be super helpful !

Thanks you