The awpy package provides data parsing, analytics and visualization capabilities for Counter-Strike: Global Offensive (CSGO) data. In this repository, you will find the source code, issue tracker and other useful awpy information. Please join our Discord for discussion around the library and esports analytics. You may visit the documentation here.
awpy requires Python >= 3.11 and Golang >= 1.18. Python acts as a wrapper for the Go code which parses demofiles.
To install awpy, you can run
pip install awpy
To update the library, just run pip install --upgrade awpy. For more help, you can visit the installation channel in our Discord.
Do you work in Google Colab? No problem, the awpy Python library runs there, too! Check out how to setup awpy Python library in Google Colab.
Using the awpy package is straightforward. Just grab a demofile and have output in a JSON or Pandas DataFrame in a few seconds. Use the example below to get started.
from awpy import DemoParser
from awpy.analytics.stats import player_stats
# Set the parse_rate equal to the tick rate at which you would like to parse the frames of the demo.
# This parameter only matters if parse_frames=True ()
# For reference, MM demos are usually 64 ticks, and pro/FACEIT demos are usually 128 ticks.
demo_parser = DemoParser(demofile="og-vs-natus-vincere-m1-dust2.dem", demo_id="og-vs-natus-vincere", parse_rate=128)
# Parse the demofile, output results to dictionary with df name as key
data = demo_parser.parse()
# There are a variety of top level keys
# You can view game rounds and events in 'gameRounds']
data["matchID"]
data["clientName"]
data["mapName"]
data["tickRate"]
data["playbackTicks"]
data["playbackFramesCount"]
data["parsedToFrameIdx"]
data["parserParameters"]
data["serverVars"]
data["matchPhases"]
data["matchmakingRanks"]
data["playerConnections"]
data["gameRounds"] # From this value, you can extract player events via: data['gameRounds'][i]['kills'], etc.
player_stats(data["gameRounds"]) # You can create a dictionary of player stats over a list of rounds
# You can also parse the data into dataframes using
data_df = demo_parser.parse(return_type="df")
# The parser also writes a JSON file of the output named demo_id.jsonPlease note that the parser parses everything in the demo. This means that you may have rounds from the warmup (denoted with the isWarmup flag), rounds that may have ended in a draw, and other odd-looking rounds. Try using the DemoParser.clean_rounds() method to clean up. Note that this is not going to be 100 percent perfect.
If you need help with the parser, join our Discord. CSGO demos are oftentimes imperfect, but if you ask on Discord, we can try to figure out what is the problem. Please remember to post the error and demo if you can! You can also check the open issues or visit visit our documentation.
Take a look at the following Jupyter notebooks provided in our examples/ directory. These will help you get started parsing and analyzing CSGO data.
- Parsing a CSGO demofile
- Basic CSGO analysis
- Basic CSGO visualization
- Working with navigation meshes
- Advanced navigation functionality
If you use the parser for any analysis on Twitter, we kindly ask you to link to this repository, so that others may know how you parsed your data. If you have a paper or project that uses the parser, please let us know in Discord so we can add it!
We welcome any contributions from the community. You can visit the issue page to see what issues are still open, or you can message on Discord. We will always have a need for writing tests, quality assurance and expanding functionality. We also seek contributors to produce interesting content (such as tweets, analyses, papers, etc.) -- you can see more examples of community content here.
When contributing code, be sure to lint your code using black, run the tests using pytest, and add any documentation (main modules are automatically covered, just make sure you write the documentation in the function).
awpy is structured as follows:
.
├── awpy
│ ├── analytics # Code for CSGO analytics
│ ├── data # Code for dealing with CSGO map and nav data
│ ├── parser # Code for CSGO demo parser
│ └── visualization # Code for CSGO visualization
├── doc # Contains documentation files
├── examples # Contains Jupyter Notebooks showing example code
└── tests # Contains tests for the awpy package
This project is made possible by the amazing work done in the demoinfocs-golang.
Big shoutout to SimpleRadar for allowing use of their map images.
Special thanks to arjun-22 for his work on the initial stats module, expanding test coverage, and quality assurance checks.
Thanks to Jan-Eric for his contributions extending the navigation functionality, greatly expanding test coverage and fixing bugs.
Additional thanks to those of you in the Discord community who file bug reports and test awpy thoroughly.