Loadout formats

Osmium supports most of the commonly used formats for importing and exporting loadouts. This page acts as a reference for other developers wanting to implement these formats in their own programs.

Note: some formats are poorly specified. Unless stated otherwise, all the information below is not authoritative.

Note: if you think this page is incomplete or has inconsistencies, or if you found a problem in Osmium regarding importing or exporting, please contact the developers.

Common Loadout Format (CLF)

This is the recommended format for general use: storage, program interoperability, etc. It has been designed to be resilient, easy to parse, unambiguous and extendable. The format is clearly specified.

Non-standard extensions

The properties below are not standard, but not Osmium specific. Other programs are encouraged to support them when applicable.

Osmium-specific extensions

The properties below are not standard and are Osmium specific. They are described here for documentation purposes. In most cases, they are not included by default when exporting, but are used internally for client-server communication.

gzCLF

gzCLF is a variant of CLF. It only contains "regular" characters (as it is Base64-encoded) so it is safe for email transmission, or for embedding in other formats which allow arbitrary text. There are two variants of gzCLF: armored and raw. The only difference is in the formatting.

Raw gzCLF

Raw gzCLF is a Base64-encoded, ZLIB-compressed (RFC 1950), optionally minified CLF string.

    $raw_gzclf = base64_encode(gzcompress($clf)); /* For encoding */
    $clf = gzuncompress(base64_decode($gzclf)); /* For decoding */

Armored gzCLF

Armored gzCLF is raw gzCLF with added delimiters to make identification and parsing easier. It follows the following ABNF grammar:

    armored-gzclf = "BEGIN gzCLF BLOCK" raw-gzclf "END gzCLF BLOCK"
    raw-gzclf     = *( ALPHA / DIGIT / "+" / "/" / whitespace )
    whitespace    = SP / HTAB / CR / LF

Since Base64-decoding will ignore whitespace, the raw gzCLF string can be neatly indented and formatted in fixed-width lines. Osmium will do so by default.

Ship DNA

The ship DNA format has the advantages of being compact and understood by the game client. Unfortunately it is very poorly documented.

Strict DNA

This is the format used and understood by the game client, and most programs. It uses the following ABNF grammar:

    dna-string     = typeid *( ":" typeid ";" quantity ) "::"
    typeid         = non-zero-digit *( digit )
    quantity       = 1*( digit )
    non-zero-digit = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
    digit          = "0" / non-zero-digit

The first type ID must be a ship type ID, and will be used as such. The following type IDs are modules, charges or drones IDs with a mandatory quantity.

When exporting DNA, Osmium will generate strict DNA. When importing DNA, Osmium will parse it as augmented DNA (the algorithm is documented below).

When viewing a fitting from a DNA string, Osmium will mangle the supplied DNA (mostly convert it to augmented DNA) and issue redirect. For more details, see the API page.

Augmented DNA

This is an improved DNA variant, used by Osmium. It is retrocompatible with strict DNA if it is well-formed. It uses the following ABNF grammar:

    augmented-dna-string = 1*( typeid *( ";" quantity ) ":" ) 1*( ":" )
    typeid               = non-zero-digit *( digit )
    quantity             = 1*( digit )
    non-zero-digit       = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
    digit                = "0" / non-zero-digit

In many ways, this format is more resilient to errors, more compact (quantities are optional) and more flexible (no particular order is imposed) than strict DNA. Here is how the format is parsed:

Remote format

Technically not a real format, the remote format is used by Osmium to describe remote fittings (used to define fleet boosters, or remote projected fittings).

When exporting a fitting to the remote format, Osmium will preferably use augmented DNA, unless:

If either of these conditions are verified, Osmium will use the gzclf:// form to avoid losing information.

When importing a fitting from the remote format, Osmium will proceed as follows:

Finally, the resulting fitting will be stripped of its non-selected presets and of its metadata.