How skadistats/clarity works
Project type and purpose
• Clarity is an open‑source Java library (not a web service or UI app) whose sole purpose is to parse and decode game replay files (Dota 2, CS:GO, CS2, Deadlock).
• The README confirms it produces structured data (combat logs, entities, modifiers, etc.) from raw replay files.
File structure
• src/main/java/skadistats/clarity is the root package. Everything under it is part of the library.
• Major top‑level subpackages (i.e., components) are:
• clarity (the API entry point, exceptions, event annotations)
• clarity.source (input sources: files, mapped memory, live stream)
• clarity.io (bitstream/decoder factories, version‑specific readers for S1/S2)
• clarity.model (in‑memory model of entities, game events, combat log entries, etc.)
• clarity.processor (annotation‑driven event dispatch pipeline: reader → packet → entities → gameevents → modifiers → sendtables → stringtables → tempentities)
• clarity.processor.runner (runnable controllers: FileRunner, RealtimeRunner, loop, context)
• clarity.platform (buffer abstractions, reflection helper)
• clarity.logger (logging interface and implementation)
• clarity.util (misc utilities: hashing, LZSS, difference evaluator, iterators, text table)
• There are no “frontend” vs. “backend” directories; this is a library with a layered, pipeline‑style architecture.
README for additional insights
• Confirms core functionality (parsing replays into domain data).
1. Input Sources
• FileSource/MappedFileSource
• InputStreamSource
• LiveSource
2. IO/Decoding Layer
• BitStream (32/64)
• FieldReader
• DecoderFactory(s) for S1/S2 versions
3. Processor Pipeline
• Reader stage (PacketInstanceReader)
• Packet stage (OnFullPacket, OnMessage)
• Entity stage (OnEntityCreated, OnEntityUpdated)
• GameEvent stage (OnGameEvent, OnCombatLogEntry)
• Modifier stage, SendTable stage, StringTable stage, TempEntity stage
4. Model Store
• EntityRegistry, BaselineRegistry, GameEventDescriptor, CombatLogEntry
5. Runner/Controller
• AbstractRunner, FileRunner, RealtimeRunner, LoopController
6. Event API
• Clarity (main entry), annotation interfaces: @Initializer, @InsertEvent, @EventListener
7. Logging & Platform Abstraction
• PrintfLogger, Buffer abstractions (UnsafeBuffer/CompatibleBuffer)
8. Utilities
• LZSS, MurmurHash, StateDifferenceEvaluator, TextTable, etc.
• Clarity → RunnerController (chooses FileRunner or RealtimeRunner)
• RunnerController → Source (pulls raw bytes)
• Source → IO/Decoding (BitStream → FieldReader → DecoderFactory)
• Decoding → ProcessorPipeline (PacketInstance → OnMessage events)
• Processor stages feed into Model Store and emit @EventListener callbacks
• Event API → User application (clients register listeners via Clarity)
• Throughout, Logger writes to console or file via PrintfLogger
c. Architectural patterns & design principles:
• Layered pipeline: each processor stage registers for specific annotation‑driven events.
• Inversion of Control: clients provide annotated listeners, Clarity dispatches.
• Version modularity: S1 vs. S2 decoder factories.
• Separation of concerns: IO, decoding, model-storage, processing, and control are distinct.
• Extensibility: annotation points for new event types or custom processors.
d. Key technologies & frameworks:
• Java 17+
• Gradle (build)
• No external frameworks: pure‑Java, uses reflection for annotation processing.