Package: sc2reader
What is sc2reader?sc2reader is a python library for extracting information from various different Starcraft II resources. These resources currently include Replays, Maps, and Game Summaries; we have plans to add support for Battle.net profiles and would gladly accept adapters to the more entrenched SCII sites such as sc2ranks.There is a pressing need in the SC2 community for better statistics, better analytics, better tools for organizing and searching replays. Better websites for sharing replays and hosting tournaments. These tools can’t be created without first being able to open up Starcraft II game files and analyze the data within. Our goal is to give anyone and everyone the power to construct their own tools, do their own analysis, and hack on their own Starcraft II projects under the open MIT license.Who Uses sc2reader?sc2reader is currently powering:Websites:gggreplays.com,gamereplays.org,spawningtool.comTools:The CoreExperiments:Midi ConversionIf you use sc2reader and you would like your tool, site, project, or implementation listed above, drop us a line on ourmailing list.Current Statussc2reader is production ready at release and under active development on Github. It is currently capable of parsing varying levels of information out of the three primary resource types listed below. For a more detailed and exact description of the information that can be extracted please consult thedocumentationhosted on ReadTheDocs.ReplaysReplays can be parsed for the following general types of information:Replay details (map, length, version, expansion, datetime, game type/speed, …)Player details (name, race, team, color, bnet url, win/loss, …)Message details (text, time, player, target, pings, …)Unit Selection and Hotkey (Control Group) events.Resource Transfers and Requests (but not collection rate or unspent totals!)Unfiltered Unit commands (attack, move, train, build, psi storm, etc)Camera Movements for all players and observers.Replays from release 2.0.8 onward make additional state information available:Unit states - creation time, positions, and deaths timesPlayer resource stats - collection rates/unspent totalsPlayer spending stats - resources spent and lostFurther game state information can be extracted from this raw information:All unit selections and hotkey values for every frame of the game.APM/EPM and its untold variations.Supply counts, expansion timings, build orders, etcWe have data dictionaries in place for standard games that make unit meta data
available.  Unit meta data is currently limited to:Costs - mineral, vespene, supplyClassification - army, building, workerAdditionally, abilities that create units/buildings have the built unit linked
with the build time in game seconds.Unfortunately this information IS NOT currently versioned and is only accurate
for the latest builds of Starcraft. Versioned meta data support will be added
in future releases.MapsMaps can be parsed for the following information:Minimap and Icon images (tga format)enUS localized Name, Author, Description, Website (if available)Map Dimensions, Camera Bounds, TilesetPlayer Slot data and Advanced Teams alliance/enemy data.There is a lot more in here to be had for the adventurous.Game SummariesGame Summary files are downloaded by the client in order to allow you to view the game summary from your match history. Prior to 2.0.8 they were the only way to get the information from the summary screen. Since the 2.0.8 release you have been able to compute this information yourself from the replay files.Thank you Prillan andTeam Liquidfor helping to decode this file.Lobby Properties (game speed, game type, …)Player Information (Race, Team, Result, bnet info, …)Player Graphs & Stats (Army Graph, Income Graph, Avg Unspent Resources, …)URLs to map localization files and imagesPlayer build orders up to 64 (real) actionsParsing on these files is now production ready for those that can get them. See theTeam Liquidthread for details on how to go about getting them.Again, these files are generally unnecessary after the 2.0.8 release.Basic Usage..note:For example scripts, checkout the docs and the `sc2reader.scripts`_ package on Github or in the source.Loading ReplaysFor many users, the most basic commands will handle all of their needs:import sc2reader
replay = sc2reader.load_replay('MyReplay', load_map=true)This will load all replay data and fix GameHeart games. In some cases, you don’t need the full extent of the replay data. You can use the load level option to limit replay loading and improve load times:# Release version and game length info. Nothing else
sc2reader.load_replay('MyReplay.SC2Replay', load_level=0)

# Also loads game details: map, speed, time played, etc
sc2reader.load_replay('MyReplay.SC2Replay', load_level=1)

# Also loads players and chat events:
sc2reader.load_replay('MyReplay.SC2Replay', load_level=2)

# Also loads tracker events:
sc2reader.load_replay('MyReplay.SC2Replay', load_level=3)

# Also loads game events:
sc2reader.load_replay('MyReplay.SC2Replay', load_level=4)If you want to load a collection of replays, you can use the plural form. Loading resources in this way returns a replay generator:replays = sc2reader.load_replays('path/to/replay/directory')Loading MapsIf you have a replay and want the map file as well, sc2reader can download the corresponding map file and load it in one of two ways:replay = sc2reader.load_replay('MyReplay.SC2Replay', load_map=true)
replay.load_map()If you are looking to only handle maps you can use the map specific load methods:map = sc2reader.load_map('MyMap.SC2Map')
map = sc2reader.load_maps('path/to/maps/directory')Using the CacheIf you are loading a lot of remote resources, you’ll want to enable caching for sc2reader. Caching can be configured with the following environment variables:SC2READER_CACHE_DIR - Enables caching to file at the specified directory.SC2READER_CACHE_MAX_SIZE - Enables memory caching of resources with a maximum number of entries; not based on memory imprint!You can set these from inside your script with the following codeBEFOREimporting the sc2reader module:os.environ['SC2READER_CACHE_DIR'] = "path/to/local/cache"
os.environ['SC2READER_CACHE_MAX_SIZE'] = 100

# if you have imported sc2reader anywhere already this won't work
import sc2readerUsing PluginsThere are a growing number of community generated plugins that you can take advantage of in your project. See the article onCreating GameEngine Pluginsfor details on creating your own. To use these plugins you need to customize the game engine:from sc2reader.engine.plugins import SelectionTracker, APMTracker
sc2reader.engine.register_plugin(SelectionTracker())
sc2reader.engine.register_plugin(APMTracker())The new GameHeartNormalizerplugin is registered by default.Installationsc2reader runs on any system with Python 2.6+, 3.2+, or PyPy installed.From PyPI (stable)Install from the latest release on PyPI with pip:pip install sc2readeror easy_install:easy_install sc2readeror with setuptools (specify a valid x.x.x):wget http://pypi.python.org/packages/source/s/sc2reader/sc2reader-x.x.x.tar.gz
tar -xzf sc2reader-x.x.x.tar.gz
cd sc2reader-x.x.x
python setup.py installReleases to PyPi can be very delayed (sorry!), for the latest and greatest you are encouraged to install from Github upstream.From GithubGithub upstream is generally stable with development branches more unstable.We usecircle-cito provide a record of ourcontinuous testing. Please verify that tests are passing before installing development versions.Install from the latest source on Github with pip:pip install -e git+git://github.com/ggtracker/sc2reader#egg=sc2readeror with setuptools:wget -O sc2reader-upstream.tar.gz https://github.com/ggtracker/sc2reader/tarball/upstream
tar -xzf sc2reader-upstream.tar.gz
cd sc2reader-upstream
python setup.py installFor ContributorsContributors should install from an active git repository using setuptools indevelopmode. This will install links to the live code so that local edits are available to external modules automatically:git clone https://github.com/ggtracker/sc2reader.git
cd sc2reader
python setup.py developPlease review theCONTRIBUTING.mdfile and get in touch with us before doing too much work. It’ll make everyone happier in the long run.TestingWe usepytestfor testing. If you don’t have it justpip install pytest.To run the tests, just do:pytestWhen repeatedly running tests it can be very helpful to make sure you’ve set a local cache directory to prevent long fetch times from battle.net.
So make some local cache folder:mkdir cacheAnd then run the tests like this:SC2READER_CACHE_DIR=./cache pytestTo run just one test:SC2READER_CACHE_DIR=./cache pytest test_replays/test_replays.py::TestReplays::test_38749If you’d like to see which are the 10 slowest tests (to find performance issues maybe):pytest --durations=10If you wantpytestto stop after the first failing test:pytest -xHave a look at the very finepytestdocs for more information.Good luck, have fun!Communitysc2reader has a small but growing community of people looking to make tools and websites with Starcraft II data. If that sounds like something you’d like to be a part of please join our underusedmailing listand start a conversation or stop by #sc2reader on FreeNode and say ‘Hi’. We have members from all over Europe, Australia, and the United States currently, so regardless of the time, you can probably find someone to talk to.Issues and SupportWe have anissue trackeron Github that all bug reports and feature requests should be directed to. We have amailing listwith Google Groups that you can use to reach out for support. We are generally on FreeNode in the #sc2reader and can generally provide live support and address issues there as well.AcknowledgementsThanks to all the awesome developers in the SC2 community that helped out
and kept this project going.Special thanks to the people of the awesome (but abandoned!)phpsc2replayproject whose public documentation and source code made starting this library
possible.Thanks tosc2replay-csharpfor setting us straight on game events parsing
and assisting with our v1.5 upgrade.Thanks toggtracker.comfor sponsoring further development and providing
the thousands of test files used while adding s2gs and HotS support.Thanks to Blizzard for supporting development of 3rd party tools and releasing
theirs2protocolfull reference implementation.CHANGELOG1.8.0 - May 4, 2022Fix various typos in docs #146Fix various URLs for blizzard resources #151 #154 #156Fix Ravager data #161Add CommandManagerStateEvent #162Fix participant state from gameheart #1711.7.0 - May 17, 2021Add DOI to the README #128Add various missing attributes for co-op replays #129Add support for python 3.8, 3.9 #132 #136Fix owner on an event with no unit #133Add support for ResourceTradeEvent #135Fix depot URL template #1391.6.0 - July 30, 2020Add support for protocol 80949 (StarCraft 5.0) #122Fix toJson script #1181.5.0 - January 18, 2020Add support for protocol 77379 #106 #107Workaround for missing data #102 #1041.4.0 - August 19, 2019Add support for protocol 75689 #951.3.2 - August 9, 2019Allow pytest #84Format code with black #87Fix UnitTypeChangeEvent.__str__ #92Add Stetmann #931.3.1 - November 29, 2018Parse backup if data is missing #691.3.0 - November 16, 2018Added support for protocol 70154 (StarCraft 4.7.0)Added support for ZeratulUpdated CircleCI build for Python 3.7Fixed a bug with printing TrackerEvent1.2.0 - October 7, 2018Added support for TychusVerified that StarCraft 4.6.1 replays work1.1.0 - June 26, 2018Added support for protocol 65895 (StarCraft 4.4.0)1.0.0 - May 18, 2018Added support for protocol 48258 through 64469Update game data and scripts for generating game dataFix ggtracker/sc2reader CircleCI build for python 3Added support for parsing Co-op replays0.8.0 - December 16, 2016Merged into ggtracker/sc2reader, which mostly means that we have a bunch of parsing fixes.  Thanks @StoicLoofah!0.7.0 -Deprecated unit.killed_by in favor of unit.killing_playerAdded unit.killed_unitsAdded unit.killing_unitAdded UnitDiedEvent.killing_playerAdded UnitDiedEvent.killing_unitDeprecated UnitDiedEvent.killer_pid in favor of UnitDiedEvent.killing_player_idDeprecated UnitDiedEvent.killer in favor of UnitDiedEvent.killing_playerUse generic UnitType and Ability classes for data. This means no more unit._type_class.__class__.__name__. But hopefully people were not doing that anyway.Now a CorruptTrackerFileError is raised when the tracker file is corrupted (generally only older resume_from_replay replays)Removed the defunct replay.player_names attribute.Removed the defunct replay.events_by_type attribute.Removed the defunct replay.other_people attribute.Replays can now be pickled and stored for later consumption.All references to the gateway attribute have been replaced in favor of region; e.g. replay.regionUse generic UnitType and Ability classes for data. This means no more unit._type_class.__class__.__name__. But hopefully people were not doing that anyway.Now a CorruptTrackerFileError is raised when the tracker file is corrupted (generally only older resume_from_replay replays)Added replay.resume_from_replay flag. See replay.resume_user_info for additional info.PacketEvent is now ProgressEvent.SetToHotkeyEvent is now SetControlGroupEvent.AddToHotkeyEvent is now AddToControlGroupEvent.GetFromHotkeyEvent is now GetControlGroupEvent.PlayerAbilityEvent is no longer part of the event hierarchy.AbilityEvent doubled as both an abstract and concrete class (very bad, see #160). Now split into:AbilityEvent is now CommandEventAbilityEvent is now BasicCommandEventTargetAbilityEvent is now TargetUnitCommandEventLocationAbilityEvent is now TargetPointCommandEventSelfAbilityEvent is now DataCommandEventRemoved the defunct replay.player_names attribute.Removed the defunct replay.events_by_type attribute.Removed the defunct replay.other_people attribute.event.name is no longer a class property; it can only be accessed from an event instance.PingEvents now have new attributes:event.to_all - true if ping seen by allevent.to_allies - true if ping seen by alliesevent.to_observers - true if ping seen by observersevent.location - tuple of (event.x, event.y)0.6.4 - September 22nd 2013Fix bug in code for logging errors.Fix siege tank supply count.Small improvements to message.events parsing.0.6.3 - September 15th 2013Properly mark hallucinated units.0.6.2 - September 5th 2013Fix rare bug where TargetedAbility events could overwrite unit types.Substantial performance boost (20% in local testing)Fixed serious bug with FileCaching that affected Python3 users.Plugins can now yield PluginExit events to broadcast their shutdown.0.6.1 - August 13th 2013Fix bug in event ordering that caused game events to process before tracker events.Fix APMTracker to count APM for all humans, not just players.0.6.0 - August 12th 2013New Stuff:Adds python 3.2+ supportAdds support for patch 2.0.10.Adds experimental SC2Map.MapInfo parsing support.Implements new replay GameEngine and plugin support.Added a sc2json script contributed by @ChrisLundquistAdds plugin GameHeartNormalizer plugin by @StoicLoofahHooked up coveralls.io for coverage reporting:https://coveralls.io/r/GraylinKim/sc2readerHooked up travis-ci for continuous testing:https://travis-ci.org/GraylinKim/sc2readerSwitched to built in python unittest module for testing.Changed Stuff (non-backwards compatible!):Summary.teams is now summary.team; summary.team is now summary.teams. To conform with replay name conventionsFixed #136, unit types from tracker events are used when available.Deprecated player.gateway for player.regionReorganized the person/player/observer hierarchy. Top level classes are now Computer, Participant, and Observer. Participant and Computer are both children of player so any isinstance code should still work fine.Player.uid now means something completely different! Use player.toon_id insteadPlayer.uid is now the user id of the player (was player.cid)PersonDict can no longer be constructed from a player list and new players cannot be added by string (name). Only integer keys accepted for setting.Log a warning instead of throwing an exception when using an unknown colors.An unknown hex value will use the hex value as the name.An unknown color name will use 0x000000 as the color.Finally straighten out all these replay player list/dictshuman/humans -> human entities, indexed by uidcomputer/computers -> computer entities, indexed by pidplayer/players -> actually playing in the game, indexed by pidobserver/observers -> observing the game, indexed by uidentities -> players + observers || humans + computers, indexed by pidclient/clients - (deprecated) same as human/humanspeople/person - (deprecated) same as entity/entities0.5.1 - June 1, 2013Fixes several game event parsing issues for older replays.Properly maps ability ids for armory vehicle & ship armor upgrades.Uses the US depot for SEA battle.net depot dependencies.PlayerStatEvent.food_usedandfood_madeare now properly divided by 4096AbilityEvent.flagsare now processed into a dictionary mapping flag name to True/False (AbilityEvent.flag)Fixed error preventing UnitOwnerChangeEvents from being processedFixed the toJSON plugin and adds new fieldsFixed error preventing parsing of MapHeader (s2mh) filesAPMTracker now properly calculates average APM to the last second played by each player instead of using the number of replay minutes in the denominator.0.5.0 - May 7, 2013Support for all replays (arcade replays now parse!) from all versionsSupport for the new replay.tracker.events added in 2.0.8Units now have birth frame, death frame, and owner informationNew events for (roughly) tracking unit positionsNew events for tracking player resource stockpiles and collection ratesMore!Much more comprehensive documentation.New unit modelSiegeTank and SiegeTankSieged (and others with different forms) are no longer separate units.Units that can transform maintain a full type history.Units are correctly and uniquely identified by unit_id alone.Updated unit meta data:Mineral CostVespene CostSupply CostFlags for is_worker, is_army, is_buildingAdded ability meta data:is_build flag marking abilities that create unitsbuild_unit indicating the unit type that is builtbuild_time indicating the build time for the ability