How legitatx/fortnite-replay-parser works
Project Type and Purpose
• This is a Python library (“fortnite-replay-parser”) whose sole purpose is parsing Fortnite replay files (binary .replay files) into Python objects (header, metadata, events) for downstream processing or analysis. It is not a full-stack app but a domain-specific parser library.
Main Architectural Components
a. Input Layer
• Replay File: Binary .replay file on disk
• FortniteReplayReader (reader.py): Entry point; opens file, manages context, orchestrates parsing
b. Parsing Core
• Low-Level Reader/Deserializer (models/reader.py): Reads binary chunks, respects protocol versions
• Event Parser (events/parser.py): Dispatches raw event payloads to specific event handlers
• Event Handlers (events/match.py, events/player.py, …): Each module extracts fields from the binary stream
c. Data Model Layer
• Pydantic Models (models/events.py, models/fortnite.py): Strongly typed classes for header, metadata, events
• Reader Model (models/reader.py): Represents binary structures, endianness, offsets
d. Infrastructure & Utilities
• Exceptions (exceptions.py): Centralized custom exceptions for parse errors
• Logger (logger.py): Configurable logger for debugging/tracing parsing steps
• Utils (utils.py): Common functions (e.g., byte conversions, version checks)
e. Output/Consumer Layer
• The consumer calls reader.events to get a list of Pydantic event objects; they are then serialized or processed further
f. Test Harness
• Tests Directory: Contains sample .replay files and test suites verifying correct event extraction
Dependencies & External Services
• Pydantic for data validation & serialization
• Python standard library (struct, io, contextlib, logging)
• No external network or database—purely local file parsing
Architectural Patterns & Principles
• Layered Architecture: Clear separation between Input, Parsing, Modeling, and Output
• Strategy/Dispatcher Pattern: events/parser.py dynamically picks the right handler based on event type
• Model-Driven Design: Binary structures are mirrored in Pydantic models for type safety and clarity
• Single Responsibility: Each module does one thing—reading raw bytes, parsing a specific event, modeling data, or logging
• Parsing Core (Low-Level Reader, Event Parser, Event Handlers)
• Data Model Layer (Pydantic Models)
• Infrastructure (Exceptions, Logger, Utils)
• Output/Consumer (your application script or JSON serializer)
• Test Harness (with sample files)
• From Replay File → FortniteReplayReader → Low-Level Reader → Event Parser → Event Handlers → Pydantic Models → Consumer
• Test Harness reads from sample files and invokes reader in a similar flow
• Another for “Data Models” (Pydantic classes)
• A third for “Infrastructure” (utils, exceptions, logger)
• A separate style for “External Entities” (Replay File, Consumer, Tests)
d. Labels & Callouts:
• Call out protocol version handling in the Low-Level Reader
• That the Parser uses a dynamic lookup (Strategy pattern) to pick handlers