ShadeNBT Version 1.1

Released: 2018-08

Description: ShadeNBT is a modification on the standard Named Binary Tag Specification, created for the Game Minecraft. The format is used to protection against corrupt game files, as well as to ensure Binary Version Compatibility. The format contains a 6-byte header, which declares that the file is a ShadeNBT File, followed by a well-formed uncompressed NBT File, that contains a single, nameless compound tag.

A Variation of this Specification, known as CryptoShade, provides Strong, Password-based Encryption of the enclosed NBT File and MAY additionally be supported by conforming implementations.

Changes from Version 1.0

Version 1.1 makes no major changes to the specification from 1.0. The sole change in 1.1 is the addition of the Long Array Tag.

References

This document references a modification of the Named Binary Tag Specification, created by Markus Perrson for the Game Minecraft. An up to date version of the NBT Specification can be found here.

All Binary Datatypes are written and read according to [LCS4 - Binary IO].

The terms “MUST”, “SHALL”, “SHOULD”, “MAY”, “MUST NOT”, “SHALL NOT”, “SHOULD NOT”, “REQUIRED”, “RECOMMENDED”, and “OPTIONAL”, when in all caps, are to be interpreted according to [RFC 2119] and [RFC 8174]. When the terms MUST, SHALL, MUST NOT, SHALL NOT, or REQUIRED are used in terms of a requirement on a file produced by this specification, the implementation MUST NOT produce a file that violates the requirement, and MUST reject any file that violates the requirement.

Rejecting Files

For various reasons implementations MUST, SHOULD, or MAY reject a ShadeNBT File. If a user attempts to load a file which is rejected, an error MUST be reported to the user. A rejected file MUST NOT be loaded. Implementations MUST NOT create a ShadeNBT File that it would reject.

Structure of a Shade Save File

Header

Each Shade file shall contain a header, which is defined by the following structure:

shade_head{
	Byte magic[4];
	Version ver;
}

magic MUST be exactly the bytes [AD 4E 42 54], or the file MUST be rejected.

ver encodes the version of the ShadeNBT Specification which the file was created in. This is encoded in the LCLib Versioning format, where the major value indicates the major version-1, and the minor value indicates the minor version. The current version of the specification is 1.1, and therefore the version for a file created in this version is [00 01].

Conforming Implementations MUST Document at least 1 supported version, and support all versions with the same major version number and a lesser or equal minor version number as each of those supported versions.

Conforming Implementations SHOULD support the latest version of the Specification released at the time the Implementation was created or updated.

Implementations MUST reject any file that indicates an unsupported version, or any version that has not been released.

NBT Data

NBT Data Tags are encoded using LCLib Binary Data IO Format, in Big Endian. There are various tags which indicate the type of data stored.

NBT_Tag{
	Byte tag;
	String name;
	union TAG_Payload{
		Byte tag_byte;
		Short tag_short;
		Int tag_int;
		Long tag_long;
		Float tag_float;
		Double tag_double;
		ByteArray{
			Int len;
			Byte payload[len];
		} tag_byte_array;
		string tag_string;
		List{
			Byte listTagType;
			Int len;
			TAG_Payload[len];
		} tag_list;
		Compound{
			NBT_Tag tags[];
			Byte endTagType;
		} tag_compound;
		IntArray{
			Int len;
			Int payload[len];
		}tag_int_array;
		LongArray{
			Int len;
			Long payload[len];
		}tag_long_array;
	}payload;
}

Where tag determines the payload, and shall be either 0x01 (tag_byte), 0x02 (tag_short), 0x03 (tag_int), 0x04 (tag_long), 0x05 (tag_float), 0x06 (tag_double), 0x07 (tag_byte_array), 0x08 (tag_string), 0x09 (tag_list), 0x0a (tag_compound), or 0x0b (tag_int_array).

If any other tag is read, except for tag 0 inside of a tag_compound, the file MUST be rejected. If the tag is 0x0c and the version indicated is 1.0, then the file MUST be rejected.

In Compound tags shall continue until the tag read is 0x00.

In List, listTagType shall be any valid value for tag, or 0x00 if len is 0.

Every ShadeNBT File shall contain a Compound Payload following the header. This Compound must contain a single nameless NBT Tag which is a tag_compound. This Compound is referred to as the Top Level Compound.

There may be any number of zero bytes following the Compound Payload in a ShadeNBT File.

Limits of the Implementation

Implementations may impose various limits upon Read ShadeNBT Files, including number of nested compound and list tags, and number of tags in a compound. Specifically, Implementions MUST support at least:

• 2^24 Tags in a list, array, or compound
• 128 Total Nested list and compound tags, excluding the top level compound.
• All UTF-8 Encoded Characters, which are require 3 bytes or less and no surrogate pairs.
• Total of 2^32 bytes in the file.

Implementations MAY choose to reject any file which violates any of those above limits.