Class NbtFile

Namespace

fNbt

Assembly

fNbt.dll

Represents a complete NBT file.

public sealed class NbtFile

Inheritance

object

NbtFile

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Constructors

NbtFile()

Creates an empty NbtFile with the current defaults (DefaultFlavor and the other NbtOptions defaults). RootTag will be set to an empty NbtCompound with a blank name ("").

public NbtFile()

NbtFile(string)

Loads NBT data from a file using the most common settings. Automatically detects compression, and reads with the current defaults (DefaultFlavor and the other NbtOptions defaults).

public NbtFile(string fileName)

Parameters

fileName string

Name of the file from which data will be loaded.

Exceptions

ArgumentNullException

fileName is null.

FileNotFoundException

If given file was not found.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

IOException

If an I/O error occurred while reading the file.

NbtFile(NbtCompound)

Creates a new NBT file with the given root tag.

public NbtFile(NbtCompound rootTag)

Parameters

rootTag NbtCompound

Compound tag to set as the root tag. May be null.

Exceptions

ArgumentException

If given rootTag is unnamed.

NbtFile(NbtCompound, NbtFlavor)

Creates a new NBT file with the given root tag and flavor, with the current default policy settings. The tag is used directly, not cloned. NbtFile is not a tag container, so a root tag may be shared between files: to re-save a loaded document under a different flavor, pass its RootTag here.

public NbtFile(NbtCompound rootTag, NbtFlavor flavor)

Parameters

rootTag NbtCompound

Compound tag to set as the root tag. May not be null.

flavor NbtFlavor

Encoding to read and write with.

Exceptions

ArgumentNullException

rootTag or flavor is null.

ArgumentException

If given rootTag is unnamed; or the flavor has no root name (use NbtCodec for those).

NbtFile(NbtCompound, NbtOptions)

Creates a new NBT file with the given root tag and options.

public NbtFile(NbtCompound rootTag, NbtOptions options)

Parameters

rootTag NbtCompound

Compound tag to set as the root tag. May not be null.

options NbtOptions

Settings to use, resolved here. May not be null.

Exceptions

ArgumentNullException

rootTag, options, or the options' Flavor is null.

ArgumentException

If given rootTag is unnamed; or if the options' flavor has no root name.

ArgumentOutOfRangeException

MaxAllocation is zero or negative.

NbtFile(NbtFlavor)

Creates an empty NbtFile for the given flavor, with the current default policy settings. RootTag will be set to an empty NbtCompound with a blank name ("").

public NbtFile(NbtFlavor flavor)

Parameters

flavor NbtFlavor

Encoding to read and write with.

Exceptions

ArgumentNullException

flavor is null.

ArgumentException

The flavor has no root name; use NbtCodec for those.

NbtFile(NbtOptions)

Creates an empty NbtFile with the given options. RootTag will be set to an empty NbtCompound with a blank name ("").

public NbtFile(NbtOptions options)

Parameters

options NbtOptions

Settings to use, resolved here. May not be null.

Exceptions

ArgumentNullException

options or its Flavor is null.

ArgumentException

The options' flavor has no root name; use NbtCodec for those.

ArgumentOutOfRangeException

MaxAllocation is zero or negative.

Properties

BigEndian

Whether this file's flavor is big-endian.

[Obsolete("Use Flavor instead. To change encodings, create a new NbtFile over the same RootTag with the target flavor.")]
public bool BigEndian { get; }

Property Value

bool

BigEndianByDefault

Whether the current DefaultFlavor is big-endian.

[Obsolete("Use NbtOptions.DefaultFlavor instead. NbtFlavor.Java is big-endian, NbtFlavor.Bedrock little-endian.")]
public static bool BigEndianByDefault { get; }

Property Value

bool

BufferSize

Gets or sets the size of internal buffer used for reading files and streams. Initialized to value of DefaultBufferSize property.

public int BufferSize { get; set; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

value is negative.

DefaultBufferSize

Gets or sets the default value of BufferSize property. Default is 8192. Set to 0 to disable buffering by default.

public static int DefaultBufferSize { get; set; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

value is negative.

FileCompression

Gets the compression method used for most recent loading/saving of this file. Defaults to AutoDetect.

public NbtCompression FileCompression { get; }

Property Value

NbtCompression

FileName

Gets the file name used for most recent loading/saving of this file. May be null, if this NbtFile instance has not been loaded from, or saved to, a file.

public string? FileName { get; }

Property Value

string

Flavor

The flavor this file reads and writes with, fixed at construction. To re-save a document under a different flavor, create a new NbtFile over the same RootTag: both files then share one tree.

public NbtFlavor Flavor { get; }

Property Value

NbtFlavor

RootTag

Root tag of this file. Must be a named CompoundTag. Defaults to an empty-named tag.

public NbtCompound RootTag { get; set; }

Property Value

NbtCompound

Remarks

The assigned tag may already belong to another compound or list: NbtFile is not a container and does not set or clear Parent. Saving then writes only this subtree, as a standalone document.

Exceptions

ArgumentException

If given tag is unnamed.

ArgumentNullException

If value is null.

Methods

LoadFromBuffer(byte[], int, int, NbtCompression)

Loads NBT data from a byte array. Existing RootTag will be replaced. FileName will be set to null.

public long LoadFromBuffer(byte[] buffer, int index, int length, NbtCompression compression)

Parameters

buffer byte[]

Byte array from which data will be loaded.

index int

The index into buffer at which the stream begins. Must not be negative.

length int

Maximum number of bytes to read from the given buffer. Must not be negative. An EndOfStreamException is thrown if NBT stream is longer than the given length.

compression NbtCompression

Compression method to use for loading/saving this file.

Returns

long

Number of bytes read from the buffer.

Exceptions

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression; if index or length is less than zero; if the sum of index and length is greater than the length of buffer.

EndOfStreamException

If NBT stream extends beyond the given length.

InvalidDataException

If file compression could not be detected or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

LoadFromBuffer(byte[], int, int, NbtCompression, TagSelector?)

Loads NBT data from a byte array. Existing RootTag will be replaced. FileName will be set to null.

public long LoadFromBuffer(byte[] buffer, int index, int length, NbtCompression compression, TagSelector? selector)

Parameters

buffer byte[]

Byte array from which data will be loaded.

index int

The index into buffer at which the stream begins. Must not be negative.

length int

Maximum number of bytes to read from the given buffer. Must not be negative. An EndOfStreamException is thrown if NBT stream is longer than the given length.

compression NbtCompression

Compression method to use for loading/saving this file.

selector TagSelector

Optional callback to select which tags to load into memory. Root may not be skipped. No reference is stored to this callback after loading (don't worry about implicitly captured closures). May be null.

Returns

long

Number of bytes read from the buffer.

Exceptions

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression; if index or length is less than zero; if the sum of index and length is greater than the length of buffer.

EndOfStreamException

If NBT stream extends beyond the given length.

InvalidDataException

If file compression could not be detected or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

LoadFromFile(string)

Loads NBT data from a file. Existing RootTag will be replaced. Compression will be auto-detected.

public long LoadFromFile(string fileName)

Parameters

fileName string

Name of the file from which data will be loaded.

Returns

long

Number of bytes read from the file.

Exceptions

ArgumentNullException

fileName is null.

FileNotFoundException

If given file was not found.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

IOException

If an I/O error occurred while reading the file.

LoadFromFile(string, NbtCompression, TagSelector?)

Loads NBT data from a file. Existing RootTag will be replaced.

public long LoadFromFile(string fileName, NbtCompression compression, TagSelector? selector)

Parameters

fileName string

Name of the file from which data will be loaded.

compression NbtCompression

Compression method to use for loading/saving this file.

selector TagSelector

Optional callback to select which tags to load into memory. Root may not be skipped. No reference is stored to this callback after loading (don't worry about implicitly captured closures). May be null.

Returns

long

Number of bytes read from the file.

Exceptions

ArgumentNullException

fileName is null.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

FileNotFoundException

If given file was not found.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

IOException

If an I/O error occurred while reading the file.

LoadFromStream(Stream, NbtCompression)

Loads NBT data from a stream. Existing RootTag will be replaced

public long LoadFromStream(Stream stream, NbtCompression compression)

Parameters

stream Stream

Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.

compression NbtCompression

Compression method to use for loading/saving this file.

Returns

long

Number of bytes read from the stream.

Exceptions

ArgumentNullException

stream is null.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

NotSupportedException

If compression is set to AutoDetect, but the stream is not seekable.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

LoadFromStream(Stream, NbtCompression, TagSelector?)

Loads NBT data from a stream. Existing RootTag will be replaced

public long LoadFromStream(Stream stream, NbtCompression compression, TagSelector? selector)

Parameters

stream Stream

Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.

compression NbtCompression

Compression method to use for loading/saving this file.

selector TagSelector

Optional callback to select which tags to load into memory. Root may not be skipped. No reference is stored to this callback after loading (don't worry about implicitly captured closures). May be null.

Returns

long

Number of bytes read from the stream.

Remarks

Compressed loads verify the container checksum on every kind of stream. On .NET 6 and later, a document cut off inside its trailer may still load without error. Seekable streams are left at their end, so the returned byte count is deterministic; non-seekable streams stay wherever decompression stopped, which can be past the document, since decompressors read ahead. Concatenated GZip members decompress as one document only on .NET Core and later and only from a seekable stream; otherwise the load reads the first member. Uncompressed loads stop exactly at the end of the document, leaving any trailing bytes in place.

Exceptions

ArgumentNullException

stream is null.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

NotSupportedException

If compression is set to AutoDetect, but the stream is not seekable.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

ReadRootTagName(Stream, NbtCompression, bool, int)

Reads the root name from the given stream of NBT data.

[Obsolete("Use ReadRootTagName(Stream, NbtCompression, NbtFlavor) instead. true corresponds to NbtFlavor.Java, false to NbtFlavor.Bedrock.")]
public static string ReadRootTagName(Stream stream, NbtCompression compression, bool bigEndian, int bufferSize)

Parameters

stream Stream

Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.

compression NbtCompression

Compression method to use for loading this stream.

bigEndian bool

Whether the stream uses big-endian (default) or little-endian encoding.

bufferSize int

No longer used.

Returns

string

Name of the root tag in the given stream.

Exceptions

ArgumentNullException

stream is null.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

NotSupportedException

If compression is set to AutoDetect, but the stream is not seekable.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

ReadRootTagName(Stream, NbtCompression, NbtFlavor)

Reads the root name from the given stream of NBT data. Root names longer than 65,535 bytes fail with NbtFormatException.

public static string ReadRootTagName(Stream stream, NbtCompression compression, NbtFlavor flavor)

Parameters

stream Stream

Stream from which data will be loaded. If compression is set to AutoDetect, this stream must support seeking.

compression NbtCompression

Compression method to use for loading this stream.

flavor NbtFlavor

Encoding to read with.

Returns

string

Name of the root tag in the given stream.

Exceptions

ArgumentNullException

stream or flavor is null.

ArgumentException

The flavor has no root name; use NbtCodec for those.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

NotSupportedException

If compression is set to AutoDetect, but the stream is not seekable.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

ReadRootTagName(string)

Reads the root name from the given NBT file. Automatically detects compression, and reads with DefaultFlavor.

public static string ReadRootTagName(string fileName)

Parameters

fileName string

Name of the file from which first tag will be read.

Returns

string

Name of the root tag in the given NBT file.

Exceptions

ArgumentNullException

fileName is null.

FileNotFoundException

If given file was not found.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

IOException

If an I/O error occurred while reading the file.

ReadRootTagName(string, NbtCompression, bool, int)

Reads the root name from the given NBT file.

[Obsolete("Use ReadRootTagName(string, NbtCompression, NbtFlavor) instead. true corresponds to NbtFlavor.Java, false to NbtFlavor.Bedrock.")]
public static string ReadRootTagName(string fileName, NbtCompression compression, bool bigEndian, int bufferSize)

Parameters

fileName string

Name of the file from which data will be loaded.

compression NbtCompression

Format in which the given file is compressed.

bigEndian bool

Whether the file uses big-endian (default) or little-endian encoding.

bufferSize int

No longer used.

Returns

string

Name of the root tag in the given NBT file.

Exceptions

ArgumentNullException

fileName is null.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

FileNotFoundException

If given file was not found.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

IOException

If an I/O error occurred while reading the file.

ReadRootTagName(string, NbtCompression, NbtFlavor)

Reads the root name from the given NBT file. Root names longer than 65,535 bytes fail with NbtFormatException.

public static string ReadRootTagName(string fileName, NbtCompression compression, NbtFlavor flavor)

Parameters

fileName string

Name of the file from which data will be loaded.

compression NbtCompression

Format in which the given file is compressed.

flavor NbtFlavor

Encoding to read with.

Returns

string

Name of the root tag in the given NBT file.

Exceptions

ArgumentNullException

fileName or flavor is null.

ArgumentException

The flavor has no root name; use NbtCodec for those.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

FileNotFoundException

If given file was not found.

EndOfStreamException

If file ended earlier than expected.

InvalidDataException

If file compression could not be detected, or decompressing failed.

NbtFormatException

If an error occurred while parsing data in NBT format.

IOException

If an I/O error occurred while reading the file.

SaveToBuffer(byte[], int, NbtCompression)

Saves this NBT file to a buffer.

public long SaveToBuffer(byte[] buffer, int index, NbtCompression compression)

Parameters

buffer byte[]

Buffer to write data to. May not be null.

index int

The index into buffer at which the stream should begin.

compression NbtCompression

Compression mode to use for saving. May not be AutoDetect.

Returns

long

Number of bytes written to the buffer.

Exceptions

ArgumentNullException

buffer is null.

ArgumentException

If AutoDetect was given as the compression mode.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression; if index is less than zero; or if index is greater than the length of buffer.

NbtFormatException

If one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements; or if a string is longer than the flavor's limit (65,535 bytes for the Java flavors); or if enabled validation rejects a tag type or string length for the flavor; or if tags are nested more than 512 levels deep.

SaveToBuffer(NbtCompression)

Saves this NBT file to a new byte array.

public byte[] SaveToBuffer(NbtCompression compression)

Parameters

compression NbtCompression

Compression mode to use for saving. May not be AutoDetect.

Returns

byte[]

Byte array containing the serialized NBT data.

Exceptions

ArgumentException

If AutoDetect was given as the compression mode.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

NotSupportedException

If the serialized document does not fit in a single array.

NbtFormatException

If one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements; or if a string is longer than the flavor's limit (65,535 bytes for the Java flavors); or if enabled validation rejects a tag type or string length for the flavor; or if tags are nested more than 512 levels deep.

SaveToFile(string, NbtCompression)

Saves this NBT file to a file.

public long SaveToFile(string fileName, NbtCompression compression)

Parameters

fileName string

File to write data to. May not be null.

compression NbtCompression

Compression mode to use for saving. May not be AutoDetect.

Returns

long

Number of bytes written to the file.

Remarks

The file is created or truncated up front, so a failed save can leave it partially written. If you are overwriting an existing file, write to a temp file first then use File.Replace to swap it with the original.

Exceptions

ArgumentNullException

fileName is null.

ArgumentException

If AutoDetect was given as the compression mode.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

IOException

If an I/O error occurred while creating the file.

UnauthorizedAccessException

Specified file is read-only, or a permission issue occurred.

NbtFormatException

If one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements; or if a string is longer than the flavor's limit (65,535 bytes for the Java flavors); or if enabled validation rejects a tag type or string length for the flavor; or if tags are nested more than 512 levels deep.

SaveToStream(Stream, NbtCompression)

Saves this NBT file to a stream.

public long SaveToStream(Stream stream, NbtCompression compression)

Parameters

stream Stream

Stream to write data to. May not be null.

compression NbtCompression

Compression mode to use for saving. May not be AutoDetect.

Returns

long

Number of bytes written to the stream.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

If AutoDetect was given as the compression mode; or if stream does not support writing.

ArgumentOutOfRangeException

If an unrecognized/unsupported value was given for compression.

NbtFormatException

If RootTag is unnamed; or if one of the NbtCompound tags contained unnamed tags; or if an NbtList tag had Unknown list type and no elements; or if a string is longer than the flavor's limit (65,535 bytes for the Java flavors); or if enabled validation rejects a tag type or string length for the flavor; or if tags are nested more than 512 levels deep.

ToString()

Prints contents of the root tag, and any child tags, to a string.

public override string ToString()

Returns

string

ToString(string)

Prints contents of the root tag, and any child tags, to a string. Indents the string using multiples of the given indentation string.

public string ToString(string indentString)

Parameters

indentString string

String to be used for indentation.

Returns

string

A string representing contents of this tag, and all child tags (if any).

Exceptions

ArgumentNullException

indentString is null.