NSR - themeldingwars/Documentation GitHub Wiki

The Network Stream Replay (NSR) files are better known as replay files since they hold the streaming data which allows to replay in-game recordings.

The NSR format uses the little endian byte order, as such all the numbers are found "reversed" in the hex dump.

The streaming format inside the packets changes rather often, so a replay is only meaningful to a client that speaks the same streaming protocol version. That version is recorded in the description header, see Protocol version. The container itself (the sections described below) has been stable across the builds we have looked at.

• nsr.bt

• Reader and Writer have been implemented in FauFau: Nsr.cs
• NSRViewer parses the same structures in NSR/
• nsrinfo is a minimal C++ reader for the header and metadata

• NSRViewer - View Firefall Network Stream Relay (NSR) files
• nsrinfo - C++ CLI tool to extract basic NSR info

The NSR file is compressed with gzip and can for example get unpacked with 7zip. It's however important to use the gzip and not the normal zip algorithm for compressing the unpacked file again.

7z a -tgzip name.nsr name

Everything below describes the file after it has been decompressed. An uncompressed NSR starts with NSRD, a compressed one with the gzip magic (1F 8B 08, read as the little endian uint 559903 if you want to test for it cheaply).

NSRD description   48 bytes, at offset 0
NSRI index         variable, starts right after the description
Meta               variable
Packets            until end of file

The description holds the offsets of the other three sections, so nothing has to be guessed, but in practice the sections always appear in this order and back to back.

Always 48 bytes.

nsrinfo calls metaOffset the header size and NSRViewer calls it the header length, which is the same number seen from the other side: the meta section begins where the header ends.

Everything the client shows about a recording before you play it, plus the position the recording was made from. Strings are null terminated and not length prefixed.

The last 31 bytes are read as one opaque block by FauFau. The split into 18 / double / 5 comes from the 010 template and has not been cross checked.

Packets run back to back from dataOffset to the end of the file.

NSRViewer reads timestamp as two uint16 "keyframe order" values instead. Both readings consume the same four bytes.

data starts with the 8 byte entity id the message applies to. The low byte of that id is the entity type, which for networked entities is the controller or view type. That is what lets a tool sort a replay by view without decoding the message bodies:

The gaps are ids we have not seen in a replay. The authoritative list for a given build is the view enum dumped from the client, for example the 1962 dump in Sift.

protocolVersion in the description is the GSS protocol version, not the build number. It is the same opaque uint16 value the client and server agree on for the GSS channels, stored here in a uint32. 19551 is the version used by the 1962 client, which is what AeroMessages currently targets. The raw values are not ordered chronologically, so the only way to map one to a build is a lookup table such as the one Aero generates from the Sift protocol dumps.

FauFau can generate a file from scratch, which is the shortest description of what a minimal valid replay needs:

1. Write 48 bytes of nothing, the description gets filled in last.
2. Write the index at offset 48, remembering the offset as indexOffset.
3. Write the meta section, remembering its offset and length.
4. Remember the current offset as dataOffset and write the packets.
5. Seek back to 0 and write the description now that all four values are known.
6. gzip the whole thing.