You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Some of the important concepts in sc2reader in no particular order.
5
+
6
+
7
+
Factories
8
+
--------------
9
+
10
+
All resources are loaded through a factory. There are four kinds:
11
+
12
+
* SC2Factory - Basic factory. Loads resources.
13
+
* DictCachedSC2Factory - Caches remote resources in memory. When loading remote resources, the dict cache is checked first.
14
+
* FileCachedSC2Factory - Caches remote resources on the file system. When loading remote resources, the file system is checked first.
15
+
* DoubleCachedSC2Factory - Caches remote resource in memory and on the file system.
16
+
17
+
A default factory is automatically configured and attached to the ``sc2reader`` module when the library is imported. Calling any factory method on the sc2reader module will use this default factory::
The default factory can be configured with the following environment variables:
23
+
24
+
* SC2READER_CACHE_DIR - Enables caching to file at the specified directory.
25
+
* SC2READER_CACHE_MAX_SIZE - Enables memory caching of resources with a maximum number of entries (not based on memory imprint!)
26
+
27
+
28
+
Resources
29
+
----------------
30
+
31
+
A Starcraft II resource is any Starcraft II game file. This primarily refers to :class:`~sc2reader.resources.Replay` and :class:`~sc2reader.resources.Map` resources but also includes less common resources such as :class:`~sc2reader.resources.GameSummary`, :class:`~sc2reader.resources.Localization`, and SC2Mods.
32
+
33
+
34
+
Player vs User
35
+
-----------------
36
+
37
+
All entities in a replay fall into one of two overlapping buckets:
38
+
39
+
* User: A human entity, only users have game and message events.
40
+
* Player: A entity that actively plays in the game, only players have tracker events.
41
+
42
+
As such the following statements are true:
43
+
44
+
* A Participant is a Player **and** a User
45
+
* An Observer is a User **and not** a Player
46
+
* An Computer is a Player **and not** a User
47
+
48
+
49
+
Game vs Real
50
+
----------------
51
+
52
+
Many attributes in sc2reader are prefixed with ``game_`` and ``real_``. Game refers to the value encoded in the replay. Real refers to the real life value, as best as we can tell. For instance, ``game_type`` might be 2v2 but by looking at the teams we know that ``real_type`` is 1v1.
53
+
54
+
55
+
GameEngine
56
+
----------------
57
+
58
+
The game engine is used to process replay events and augument the replay with new statistics and game state. It implements a plugin system that allows developers
59
+
to inject their own logic into the game loop. It also allows plugins to ``yield`` new
60
+
events to the event stream. This allows for basic message passing between plugins.
61
+
62
+
A default engine is automatically configured and attached to the ``sc2reader.engine`` module when the library is imported. Calling any game engine method on the engine module will use this default factory::
63
+
64
+
sc2reader.engine.register_plugin(MyPlugin())
65
+
sc2reader.engine.run(replay)
66
+
67
+
68
+
Datapack
69
+
-----------------
70
+
71
+
A datapack is a collection of :class:`~sc2reader.data.Unit` and :class:`~sc2reader.data.Ability` classes that represent the game meta data for a given replay. Because this information is not stored in a replay, sc2reader ships with a datapack for standard ladder games from each Starcraft patch.
72
+
73
+
For non-standard maps, this datapack will be both wrong and incomplete and the Unit/Ability data should not be trusted. If you want to add a datapack for your map, see the article on :doc:`addingnewdatapacks`.
A SC2Replay file is an archive, just like a like zip or tar file. Inside there are several files, each with a specific purpose. The important ones can be split into three categories.
6
+
7
+
8
+
Initial State:
9
+
----------------
10
+
11
+
These first three files describe the initial state of the game before any events occur.
12
+
13
+
* replay.initData - Records game client information and lobby slot data.
14
+
* replay.details - Records basic player and game data.
15
+
* replay.attributes.events - Records assorted player and game attributes from the lobby.
16
+
17
+
The Starcraft II game client can be thought of as a deterministic state machine. Given an initial state and a list of events, the end state can be exactly replicated.
18
+
19
+
20
+
Input Events:
21
+
----------------
22
+
23
+
The next two files provide a feed of player actions in the game.
24
+
25
+
* replay.message.events - Records chat messages and pings.
26
+
* replay.game.events - Records every action of every person in the game.
27
+
28
+
When you watch a replay the game just reads from these feeds. When you take over from a replay, the game client cuts the feeds and switches over to live mouse/keyboard input. Because the AI is deterministic the replay never contains message/game events for them.
29
+
30
+
31
+
Output Events:
32
+
----------------
33
+
34
+
The last file provides a record of important events from the game.
35
+
36
+
* replay.tracker.events - Records important game events and game state updates.
37
+
38
+
This file was introduced in 2.0.4 and is unncessary for the Starcraft II to reproduce the game. Instead, it records interesting game events and game state for community developers to use when analyzing replays.
39
+
40
+
41
+
What isn't in a replay?
42
+
--------------------------
43
+
44
+
Replays are specifically designed to only include data essential to recreate the game. Game state is not recorded because the game engine can recreate it based off the other information. That means no player resource counts, colleciton rates, supply values, vision, unit positions, unit deaths, etc. Information that you are super interested in probably is not directly recorded. Fortunately since 2.0.4 tracker events now record some of this information; prior to that patch we had to run our own simulations to guess at most of the data.
45
+
46
+
47
+
The other important aspect of this is that instead of completely describing all of the game data (unit data, ability data, map info, etc), replays maintain a list of dependencies. These dependencies might look like this:
48
+
49
+
* Core.SC2Mod
50
+
* Liberty (multi).SC2Mod
51
+
* Swarm (multi).SC2Mod
52
+
* Teams2.SC2Mod
53
+
* Current Patch.SC2mod
54
+
* GameHeart.SC2Mod
55
+
* Map.SC2Map
56
+
57
+
As part of the replay pre-load process, each of these dependencies is fetched and all of their associated data is loaded into memory. When Battle.net tells you it is "Fetching Files", it can often be referring to dependencies like this.
58
+
59
+
sc2reader has attempted to mitigate this serious deficiency by packaging its own game data files. Basic cost, build time, and race information has been packaged. For many people this will be enough. Future versions of sc2reader will provide support for game data exports from the World Editor (introduced in patch 2.0.10). These exports should provide a much more robust dataset to work with.
**sc2reader** is an open source, MIT licensed, python library for extracting game play information from Starcraft II replay and map files. It is production ready, actively maintained, and hosted publicly on Github [`source`_].
29
+
30
+
Features:
31
+
32
+
* Fully parses and extracts all available data from all replay files (arcade included) from every official release (plus the HotS Beta).
33
+
* Automatically retrieves maps; extracts basic map data and images. Maps unit type and ability link ids to unit/ability game data.
34
+
* Processes replay data into an interlinked set of Team, Player, and Unit objects for easy data manipulation
35
+
36
+
Plugins:
37
+
38
+
* Selection Tracking: See every player's current selection and hotkeys at every frame of the game.
39
+
* APM Tracking: Provides basic APM information for each player by minute and as game averages.
40
+
* GameHeartNormalizer: Fixes teams, races, times, and other oddities typical of GameHeart games.
41
+
42
+
Scripts:
43
+
44
+
* sc2printer: Print basic replay information to the terminal.
45
+
* sc2json: Render basic replay information to json for use in other languages.
46
+
* sc2replayer: Play back a replay one event at a time with detailed printouts.
47
+
48
+
I am actively looking for community members to assist in documenting the replay data and in creating plugins that enhance functionality. Contact me!
The best way to learn how to pick sc2Reader up and get started is probably by example. With that in mind, we've written up a series of tutorials on getting various simple tasks done with sc2reader; hopefully they can serve as a quick on ramp for you.
70
+
The best way to pick sc2reader up and get started is probably by example. With that in mind, we've written up a series of tutorials on getting various simple tasks done with sc2reader; hopefully they can serve as a quick on ramp for you.
31
71
32
72
* :doc:`tutorials/prettyprinter` (10-15 minutes)
33
73
34
74
35
75
Reference Pages
36
76
-----------------------
37
77
38
-
The following reference pages were put together to help you quickly find the information you need.
78
+
Don't forget to check the :doc:`faq` if you can't find the answer you are looking for!
39
79
40
80
.. toctree::
41
81
42
-
faq
43
82
sc2reader
44
83
mainobjects
45
84
supportobjects
@@ -66,5 +105,6 @@ The following reference pages were put together to help you quickly find the inf
0 commit comments