Wild Container Format

WildContainerFormat.md

🦊 Wild Container Format

The "Wild Container Format" is a binary container format developed and designed by Wild Heart Studios for the purpose of storing structured, format-agnostic video game save data.

This document follows the key words defined in IETF RFC 2119 to reduce ambiguity where it may be needed.

Conventions

These OPTIONAL conventions are used by Wild Heart Studios in the creation and processing of wild container files:

• The file extension for wild container files is .wild.
• The data contained by wild container files is in the MessagePack format.

Definitions

The following types and syntax are used in the definition of this format's low-level structures:

• u8 = an unsigned 8-bit integer
• u32 = an unsigned 32-bit integer
• u64 = an unsigned 64-bit integer
• (...) = a tuple, an anonymous structure; MUST have the same layout as its component types
• [T; N] = an array, a sequence of T with a preceding, REQUIRED N field that MUST declare the length of the array
• T& = an address of another section of the file; MUST have the same layout as T
• const T = V = a constant, a T that MUST have the value V

It should be assumed that the file's structures use Little Endian byte ordering. The contained data may follow its own byte ordering.

Format

Container

struct Container {
    header   = Header;
    sections = [Section; u8];
}

Represents the top-level view of the wild container file.

• header MUST start at offset 0 of the file.
• sections does not have a required sort.

Header

struct Header {
    identifier = const u32 = 0x57494C44;
    sections   = [(u8, u64& Section); u8];
}

Represents the wild container file's header. Provides basic file type verification as well as addresses to the file's sections by ID.

Parsers MUST discover sections through the sections dictionary due to the lack of a section length prefix or delimiter. Additionally, extensions of the format MAY place additional fields after sections.

Section

struct Section {
    flags    = u32;        // - arbitrary flags used for marking this section
    checksum = u32;        // - the CRC-32 checksum of this section's body
    body     = [u8; u64];  // - the contents of this section
}

Represents a section of the save file.