awpy

Awpy

Counter-Strike 2 Demo Parsing, Analytics and Visualization in Python

• :computer: Parse Counter-Strike demos in Python or with a command-line interface
• :skull: Access tick-level player and event data, like kills, damages and more
• :chart: Calculate popular statistics, such as ADR, KAST and Rating
• :mag_right: Determine player visibility in microseconds
• :earth_americas: Parse navigation meshes (.nav) and calculate distance metrics
• 🎞️ Visualize Counter-Strike data, including animated round gifs and heatmaps
• :speaker: Active Discord community

Installation

To install Awpy, you can run

pip install awpy

[!NOTE] Awpy requires Python >= 3.11. To update the library, just run pip install --upgrade awpy. To check your current Awpy version, run pip show awpy. If you want to see what data is available for download, run awpy get --help.

[!TIP] Don't worry if you get stuck, visit our Discord for help.

Example Code

Using Awpy is easy. Just find a demo you want to analyze and use the example below to get started. You can easily find demos on HLTV, FACEIT or CS2Stats.

from awpy import Demo

# Create and parse demo
dem = Demo("g2-vs-navi.dem")
dem.parse()

# Access various dictionaries & dataframes
dem.header
dem.rounds
dem.grenades
dem.kills
dem.damages
dem.bomb
dem.smokes
dem.infernos
dem.shots
dem.footsteps
dem.ticks

# The dataframes are Polars dataframes
# to transform to Pandas, just do .to_pandas()
dem.ticks.to_pandas()

[!TIP] Want to learn more about the parser output? Visit the parser primer in our documentation!

Help! The parser doesn't work or returns weird data

Counter-Strike demos can be a bit troublesome. It is likely you'll see increased error rates in POV demos. To help us address parsing issues, please open a bug report in our Github issues. Additionally, you can reach out in our Discord. We're appreciate any help in identifying bugs. We use LaihoE's demoparser as a backend, so you may also check there for any open issues.

Examples and Projects

Take a look at the following Jupyter notebooks provided in our examples/ directory. These will help you get started parsing and analyzing Counter-Strike data.

• Parsing a CS2 demofile
• Parsing a CS2 demofile through command-line
• Calculating ADR, KAST% and Rating
• Plotting CS2 demos
• Calculating visibility from CS2 demos
• Parsing CS2 .nav files

If you use the parser for any public analysis, we kindly ask you to link to the Awpy repository, so that others may know how you parsed, analyzed or visualized your data. If you have a paper or project that uses the parser, please let us know in Discord so we can add it to our growing list!

[!IMPORTANT] If you use Awpy, we'd love if you could link back to our repo!

Contributing

We welcome any contributions from the community, no matter the skill-level. You can visit our issue page to see what issues are still open, the Awpy project for a different view of project priorities, or you can message us on Discord. Some examples of where you can make a difference are in documentation, quality assurance, developing new features, or creating unique content with Awpy. You can see more examples of community content here. If you are interested in contributing to Awpy, learn more here.

[!TIP] We are happy to walk through those that want to contribute, no matter your skill level. There are a diverse set of ways one can contribute to Awpy. We welcome first-time contributors!

Acknowledgments

The name "Awpy" is due to Nick Wan -- we recommend his stream for sports data analytics enthusiasts.

Awpy was first built on the amazing work done in the demoinfocs-golang Golang library. We now rely on demoparser2 for parsing, which is another fantastic parsing project, built specifically for Python.

Awpy's team includes JanEric, adi and hojlund, who you can find in the Awpy Discord. Their work, among others, is crucial to Awpy's continued success! To contribute to Awpy, please visit CONTRIBUTING.