Clarity: reading Dota 2 and Counter-Strike replays as structured data

Replay files as structured Java objects

Clarity is an open source parser for Dota 2, CSGO, CS2 and Deadlock replay files, written in Java. The repository description calls it a comically fast parser, and the README's own framing is that Clarity produces the data you might be interested in from a replay.

That framing matters because a replay file is not a documented format. It is a container of recorded network messages from a specific game version, and the work of turning it into anything useful is the work of understanding how the game encoded its state. A library that has done that and exposes it as typed Java objects saves a team from repeating the effort for every statistic they want.

The audience is therefore specific. A statistics pipeline, an analysis tool, a draft or highlight system and a tournament overlay are all things that need the same decode and none of them want to write it. The requirements are Java 21 and above and Gradle for building, and the library is consumed as an ordinary Maven or Gradle dependency, so it drops into an existing JVM build with no runtime of its own.

It is worth being clear about what a replay parser is not. It is not a game client and it is not a live telemetry feed. It reads recordings that already exist on disk.

Ten views onto the same match

The data Clarity can return is listed as a set of choices, and the list is more interesting than it looks because the views are not all the same kind of data.

The combat log is a detailed log of events that happened in the game. Entities are the in-game things, like heroes, players and creeps, and modifiers are the auras and effects on those entities.

Then the layer that is specific to how games are actually recorded. Temporary entities are the fire-and-forget things the game server tells the client about. User messages cover many different things, including spectator clicks, global chat messages, overhead events like last-hit gold, and particle systems. Game events are the lower-level messages, such as Dota TV control and directed camera commands.

The last three are the ones people forget a replay contains. Voice data is commentary in pro matches, sounds are the sounds that occur in the game, and the overview is the end of game summary, including players, the game winner, the match id, the duration, and often picks and bans.

The design consequence is that you choose your views rather than receiving everything. A tool that draws a timeline of gold events needs the combat log and the entities, a tool that plots the draft needs the overview, and a tool that maps voice activity needs the voice data, which is present but rarely wanted.

The unprocessed view and the protobuf underneath

One of the ten entries is the escape hatch: the unprocessed view, where data is provided as the original protobuf message object.

That single option tells you the shape of the whole library. The games encode their replay data as protobuf messages, and the higher level views are a typed interpretation of those messages. When a view does not model something you need, you can drop down to the message itself and read the fields the game actually wrote, rather than asking the library to grow a new view first.

For an analysis tool this is the difference between a hard stop and an inconvenience. It also means the views are a convenience layer over a stable underlying representation rather than a closed schema, and that the cost of a missing feature is your own parsing code rather than a blocked dependency.

The trade is that working in the unprocessed view means working with protobuf message types, and that is a different programming experience from the typed views. The README is honest that this is a choice the user makes, and the ordering of the list, with the unprocessed view last, suggests it is the fallback rather than the default path.

Adding Clarity to a Maven or Gradle build

The library is published under the com.skadistats group with the artifact name clarity, and the README shows the dependency at version 5.0.1 for both build systems.

In Maven it is the usual block:

<dependency>
	<groupId>com.skadistats</groupId>
	<artifactId>clarity</artifactId>
	<version>5.0.1</version>
</dependency>

In Gradle with the Groovy syntax:

    implementation group: 'com.skadistats', name: 'clarity', version: '5.0.1'

And in Gradle with the Kotlin syntax:

    implementation("com.skadistats:clarity:5.0.1")

For example code, the README points to a separate project, clarity-examples, rather than keeping samples in this repository, which is a sensible split for a library whose API surface is large.

The repository itself is a Gradle project with build.gradle.kts and settings.gradle.kts at the root, a gradle.properties, the wrapper scripts for Unix and Windows, and the sources under src/. There is also a CLAUDE.md and an openspec/ directory, which suggests the project keeps a specification of its own behaviour alongside the code, and a PARSER-COMPARISON.md document.

The gap between the tags and the published artifact

There is a discrepancy in the release history that a team adopting this should notice rather than gloss over.

The most recent tagged releases listed are 2.1 from 2016-08-25, 2.0 and 1.3 both from 2015-08-01. The dependency snippets in the README, on the other hand, all point at version 5.0.1.

So the tags in the repository are a decade behind the version the documentation tells you to depend on. The most likely explanation is that the project stopped tagging releases and now publishes to Maven Central from the main branch or from an internal pipeline, and the README points to the changelog for recent project activity. That is a plausible reading, and it is also exactly the kind of thing to confirm rather than assume, because a library whose artifact version and its tags disagree is a library where you need to know which commit your dependency corresponds to.

The practical check is the CHANGELOG.md file in the repository root, which the README points to, and the changelog link. If a specific published version corresponds to a specific commit, pin it in your build, because the alternative is that a patch release changes the parser underneath you with no tag to compare against.

Where Clarity is the wrong tool

Three cases point elsewhere.

The first is live data. A replay parser reads recordings. If you need to know what is happening in a match as it happens, or to build a service that reacts to a running game, this is the wrong shape of library and the README does not describe any live interface.

The second is a game Clarity does not list. The supported set is Dota 2, CSGO, CS2 and Deadlock, and the internals of each of these formats are different enough that a parser for one is not a parser for another. The PARSER-COMPARISON.md file in the repository root is the document to read if you are deciding between parsers, and it is the place to look before assuming that another title would parse with the same code.

The third is a non-JVM stack. The library is Java, published for Maven and Gradle, so using it from Python, Go or Rust means either a service boundary or a port of its own, and the data objects are Java types rather than a neutral format.

There is also a point about the performance claim. The description calls the parser comically fast, which is a good sign, but the README publishes no numbers, and no comparison against another parser. For a batch pipeline over a few thousand replays that does not matter. For something interactive that parses a match while a spectator is watching, it does, and the only way to settle it is to measure on your own files.

Editorial conclusion

Adopt Clarity if you are building a Dota 2 or Counter-Strike analysis tool and want the replay decoded into typed Java objects rather than raw protobuf, and you are working in a JVM stack already. Do not adopt it for live telemetry, for a game it does not list, or as a performance critical path, since the README calls it fast without publishing numbers to compare against. Verify three things first: the artifact version you actually resolve, because the install instructions show 5.0.1 while the most recent tags listed are 2.1 from 2016 and 2.0 from 2015; which of the ten output views your analysis needs, since the cost of parsing is paid in the views you request; and the Java floor, which is 21 and above. The licence is BSD-3-Clause, the last push was on 2026-10-05, and the repository has no GitHub releases, so the changelog and the CHANGELOG.md file are where change is recorded.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. Releases
5. skadistats/clarity on GitHub