faf-replay-parser 0.3.0

Supreme Commander Forged Alliance replay parser
Documentation

FAF Replay Parser

A Supreme Commander: Forged Alliance replay parser based on https://github.com/FAForever/faf-scfa-replay-parser.

This project aims to provide a fast parser for the Supreme Commander Forged Alliance (SCFA) replay data format. These replay files are relatively small by today's standards, however, performance still matters when you need to parse a large number of replays.

This repository includes the parser implementation as a Rust crate, as well as command line utility and Python3 bindings.

Usage

The easiest way to use the parser is through the Python module. Note that pre-compiled binaries are only distributed for Linux. If you need to compile for a different operating system, the Building section may be helpful.

Install using pip:

$ pip install faf-replay-parser

Parse replays through the Parser class:

from datetime import timedelta
from fafreplay import Parser, commands

parser = Parser(
    # Skip all commands except the ones defined here
    commands=[
        commands.Advance,                   # For the tick counter
        commands.VerifyChecksum,            # For desync detection
    ],
    # Throw away commands right after we parse them. Setting this to `True` will
    # significantly increase the parse time.
    save_commands=False
)
# Or create a parser with default arguments (turn off save_commands though)
# parser = Parser(save_commands=False)

# Read replay to a `bytes` object
with open("12345.scfareplay", "rb") as f:
    data = f.read()

# Parse to a python dictionary. Data must by exactly of type `bytes`
replay = parser.parse(data)
print("Game time:", timedelta(milliseconds=replay["body"]["sim"]["tick"]*100))
if replay["body"]["sim"]["desync_ticks"]:
    print("Replay desynced!")

The Command Line Utility

Disclaimer: The cli is a work in progress, and some parts of it may currently print out excess amounts of debug information.

Installing

You can get the cli by cloning this repository and building it with:

$ cargo build --release --features cli

This will produce an executable in target/release/. Copy this to some location in your $PATH, for instance ~/.local/bin/.

Alternatively, a Linux binary is available in the GitLab CI build artifacts of every tagged release.

Functionality

The cli currently performs 3 main functions. Printing a summary of the replay (mostly header information), inspecting the contents of the command stream, and converting fafreplay files into scfareplay files. For detailed information on the cli parameters use the --help command.

Building

To build the command line utility:

$ cargo build --release --features cli

To build the Python extension module:

$ cargo +nightly build --lib --features python --release

Note: If you forget the --lib flag you may end up with some linker errors, however, the dynamic library should still have been compiled correctly.

Development

For developing the python bindings it may be useful to simlink the compiled library to the root project directory.

$ ln -s target/release/libfafreplay.so ./fafreplay.so

Python will then be able to find the module fafreplay when the interpreter is run from the project root.

Related Projects

Looking for a parser in a different language? Check out these other replay parser implementations: