Crate evtclib

Expand description

evtclib is a crate aiming to provide utility functions to parse and work with .evtc reports generated by arcdps.

About evtc Files

evtc files are files generated by the (inofficial) arcdps addon to Guild Wars 2. They contain metadata about a fight in the game, such as the boss’s name (if it was a raid or fractal boss), the participants, and a stripped-down log of the complete fight.

There are other programs (such as GW2-Elite-Insights-Parser) and websites (such as dps.report) which allow you to generate reports from evtc files.

A common way to store and distribute evtc files is to zip them to either a .evtc.zip (old way) or a .zevtc (new way). evtclib uses zip to read them, prodiving the raw::parse_zip convenience function.

Crate Structure

The crate consists of two main parts: The raw parser, which is used to read structured data from binary input streams, and the higher-level abstractions provided in the root and event submodules.

Additionally, there are some defintions (such as IDs for various game items) in the gamedata module.

The main structs that you should be dealing with are the Log and its components, such as Event and Agent.

Workflow

evtclib provides two convenience functions to obtain a Log:

If you have a stream (that is, something that is Read + Seek), you can use process_stream to obtain a Log by reading from the stream.

If your evtc is saved in a file, you can use process_file to obtain a Log from it. This will also ensure that the buffering is set up correctly, to avoid unnecessary system calls.

Both of those functions require the reader to be seekable, as that is what we need for zip archive support. If you cannot provide that, or if you need finer grained control for other reasons, you can use either raw::parse_file or raw::parse_zip to obtain the low-level Evtc structure, and then turn it into a Log by using process:

use evtclib::{Compression, Log};
use std::fs::File;
// Preferred:
let log: Log = evtclib::process_file("my_log.evtc", Compression::None)?;

// If you have a stream:
let file = File::open("my_log.evtc")?;
let log: Log = evtclib::process_stream(file, Compression::None)?;

// If you really need to do it manually:
// Open a file for processing
let file = File::open("my_log.evtc")?;
// Parse the raw content of the file
let raw_log = evtclib::raw::parse_file(file)?;
// Process the file to do the nitty-gritty low-level stuff done
let log: Log = evtclib::process(&raw_log)?;

// In all cases, you can now do work with the log
for player in log.players() {
    println!("Player {} participated!", player.account_name());
}

Make sure to take a look at the note on “Buffering” in the parser module in order to increase the speed of your application.

Writing evtc Files

Currently, evtclib does not provide a way to output or modify evtc files. This is for two reasons:

The only sensible source for logs is the arcdps addon itself, most applications only consume them.
The library was needed for reading support, and writing support has never been a priority.

While there are legitimate use cases for writing/modification support, they are currently not implemented (but might be in a future version).