Class NbtCodec

Namespace

fNbt

Assembly

fNbt.dll

Reads and writes single NBT documents ("blobs") with a fixed set of NbtOptions, resolved once at construction. Create one per context and reuse it; instances are immutable and safe to share between threads.

public sealed class NbtCodec

Inheritance

object

NbtCodec

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Blobs carry no file-level framing and are never compressed at this layer: network packet payloads, LevelDB values, and NBT embedded inside other formats. Reads stop exactly at the end of one document, leaving trailing bytes in place, and accept any root tag type unless ValidateOnRead is set. Writes enforce the flavor's root rules, and its conformance rules when ValidateOnWrite is set. For one-off use with the current default options, For(NbtFlavor) returns a cached per-flavor instance. The .NET 8 build also reads from ReadOnlySpan<byte> and writes to IBufferWriter<byte>, for pooled buffers and pipelines.

Constructors

NbtCodec(NbtFlavor)

Creates a codec for the given flavor with the current default policy settings.

public NbtCodec(NbtFlavor flavor)

Parameters

flavor NbtFlavor

Encoding to read and write.

Exceptions

ArgumentNullException

flavor is null.

NbtCodec(NbtOptions)

Creates a codec with the given options.

public NbtCodec(NbtOptions options)

Parameters

options NbtOptions

Settings to use, snapshotted here. Later changes to the instance do not affect this codec.

Exceptions

ArgumentNullException

options or its Flavor is null.

ArgumentOutOfRangeException

MaxAllocation is zero or negative.

Properties

Flavor

The flavor this codec reads and writes, fixed at construction.

public NbtFlavor Flavor { get; }

Property Value

NbtFlavor

Methods

For(NbtFlavor)

Returns a cached codec with the current default policy settings for the given flavor, for one-off use: NbtCodec.For(NbtFlavor.Bedrock).ReadTag(stream). A returned codec never changes; after a policy default changes, a later call returns a fresh instance built from the new defaults.

public static NbtCodec For(NbtFlavor flavor)

Parameters

flavor NbtFlavor

Encoding to read and write.

Returns

NbtCodec

Exceptions

ArgumentNullException

flavor is null.

ReadConcatenatedTags(Stream)

Lazily reads back-to-back NBT documents from the given stream until it ends, e.g. a Bedrock LevelDB value holding several roots. Enumeration ends cleanly when the stream runs out exactly on a document boundary; a partially-present document throws.

public IEnumerable<NbtTag> ReadConcatenatedTags(Stream stream)

Parameters

stream Stream

Stream to read from. Does not need to be seekable.

Returns

IEnumerable<NbtTag>

A lazy sequence of root tags. The stream is read as the sequence is enumerated.

Exceptions

ArgumentNullException

stream is null.

EndOfStreamException

If the stream ends partway through a document.

NbtFormatException

If a document is malformed, nested more than 512 levels deep, exceeds a configured limit, fails enabled validation, or consists of a lone TAG_End byte.

ReadTag(byte[], int, int, out int)

Reads one NBT document from the given buffer.

public NbtTag ReadTag(byte[] buffer, int index, int length, out int bytesConsumed)

Parameters

buffer byte[]

Buffer to read from.

index int

Index in buffer at which the document begins.

length int

Maximum number of bytes the document may occupy. Trailing bytes past the document's actual end are ignored.

bytesConsumed int

Set to the exact number of bytes the document occupied.

Returns

NbtTag

The root tag. Its Name is null for flavors without root names.

Exceptions

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

index or length do not describe a valid range within buffer.

EndOfStreamException

If the document extends past the given length.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, fails enabled validation, or consists of a lone TAG_End byte.

ReadTag(byte[], int, int, NbtTagType, out int)

Reads one NBT document from the given buffer, requiring a specific root tag type.

public NbtTag ReadTag(byte[] buffer, int index, int length, NbtTagType expectedRootType, out int bytesConsumed)

Parameters

buffer byte[]

Buffer to read from.

index int

Index in buffer at which the document begins.

length int

Maximum number of bytes the document may occupy. Trailing bytes past the document's actual end are ignored.

expectedRootType NbtTagType

Root tag type that the document must have.

bytesConsumed int

Set to the exact number of bytes the document occupied.

Returns

NbtTag

The root tag. Its Name is null for flavors without root names.

Exceptions

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

index or length do not describe a valid range within buffer; or expectedRootType is not a concrete tag type.

EndOfStreamException

If the document extends past the given length.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, fails enabled validation, or its root tag type does not match expectedRootType.

ReadTag(Stream)

Reads one NBT document from the given stream. The stream is left positioned exactly past the end of the document.

public NbtTag ReadTag(Stream stream)

Parameters

stream Stream

Stream to read from. Does not need to be seekable.

Returns

NbtTag

The root tag. Its Name is null for flavors without root names.

Exceptions

ArgumentNullException

stream is null.

EndOfStreamException

If the stream ends before the document does.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, fails enabled validation, or consists of a lone TAG_End byte (use TryReadTag(Stream, out NbtTag?) to accept absent documents).

ReadTag(Stream, NbtTagType)

Reads one NBT document from the given stream, requiring a specific root tag type.

public NbtTag ReadTag(Stream stream, NbtTagType expectedRootType)

Parameters

stream Stream

Stream to read from. Does not need to be seekable.

expectedRootType NbtTagType

Root tag type that the document must have.

Returns

NbtTag

The root tag. Its Name is null for flavors without root names.

Exceptions

ArgumentNullException

stream is null.

ArgumentOutOfRangeException

expectedRootType is not a concrete tag type.

EndOfStreamException

If the stream ends before the document does.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, fails enabled validation, or its root tag type does not match expectedRootType.

ReadTag(ReadOnlySpan<byte>, out int)

Reads one NBT document from the given span. The span is touched only during the call, so pooled or stack memory is fine: the returned tags hold copies of their data.

public NbtTag ReadTag(ReadOnlySpan<byte> buffer, out int bytesConsumed)

Parameters

buffer ReadOnlySpan<byte>

Bytes to read from. Trailing bytes past the document's actual end are ignored.

bytesConsumed int

Set to the exact number of bytes the document occupied.

Returns

NbtTag

The root tag. Its Name is null for flavors without root names.

Remarks

Only the .NET 8 build has this overload.

Exceptions

EndOfStreamException

If the document extends past the end of buffer.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, fails enabled validation, or consists of a lone TAG_End byte (use TryReadTag(ReadOnlySpan<byte>, out NbtTag?, out int) to accept absent documents).

ReadTag(ReadOnlySpan<byte>, NbtTagType, out int)

Reads one NBT document from the given span, requiring a specific root tag type.

public NbtTag ReadTag(ReadOnlySpan<byte> buffer, NbtTagType expectedRootType, out int bytesConsumed)

Parameters

buffer ReadOnlySpan<byte>

Bytes to read from. Trailing bytes past the document's actual end are ignored.

expectedRootType NbtTagType

Root tag type that the document must have.

bytesConsumed int

Set to the exact number of bytes the document occupied.

Returns

NbtTag

The root tag. Its Name is null for flavors without root names.

Remarks

Only the .NET 8 build has this overload.

Exceptions

ArgumentOutOfRangeException

expectedRootType is not a concrete tag type.

EndOfStreamException

If the document extends past the end of buffer.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, fails enabled validation, or its root tag type does not match expectedRootType.

TryReadTag(byte[], int, int, out NbtTag?, out int)

Attempts to read one NBT document from the given buffer. Returns false when length is zero, or (for flavors that allow non-compound roots) when the document is a lone TAG_End byte meaning "absent".

public bool TryReadTag(byte[] buffer, int index, int length, out NbtTag? tag, out int bytesConsumed)

Parameters

buffer byte[]

Buffer to read from.

index int

Index in buffer at which the document begins.

length int

Maximum number of bytes the document may occupy.

tag NbtTag

Set to the root tag, or null if no tag was present.

bytesConsumed int

Set to the exact number of bytes consumed.

Returns

bool

Whether a tag was read.

Exceptions

ArgumentNullException

buffer is null.

ArgumentOutOfRangeException

index or length do not describe a valid range within buffer.

EndOfStreamException

If the document extends past the given length.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, or fails enabled validation.

TryReadTag(Stream, out NbtTag?)

Attempts to read one NBT document from the given stream. Returns false when the stream is already at its end, or (for flavors that allow non-compound roots) when the document is a lone TAG_End byte meaning "absent". Anything else is parsed as a complete document, and a partial one still throws.

public bool TryReadTag(Stream stream, out NbtTag? tag)

Parameters

stream Stream

Stream to read from. Does not need to be seekable.

tag NbtTag

Set to the root tag, or null if no tag was present.

Returns

bool

Whether a tag was read.

Exceptions

ArgumentNullException

stream is null.

EndOfStreamException

If the stream ends partway through a document.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, or fails enabled validation.

TryReadTag(ReadOnlySpan<byte>, out NbtTag?, out int)

Attempts to read one NBT document from the given span. Returns false when the span is empty, or (for flavors that allow non-compound roots) when the document is a lone TAG_End byte meaning "absent".

public bool TryReadTag(ReadOnlySpan<byte> buffer, out NbtTag? tag, out int bytesConsumed)

Parameters

buffer ReadOnlySpan<byte>

Bytes to read from. Trailing bytes past the document's actual end are ignored.

tag NbtTag

Set to the root tag, or null if no tag was present.

bytesConsumed int

Set to the exact number of bytes consumed.

Returns

bool

Whether a tag was read.

Remarks

Only the .NET 8 build has this overload.

Exceptions

EndOfStreamException

If the document extends past the end of buffer.

NbtFormatException

If the document is malformed, nested more than 512 levels deep, exceeds a configured limit, or fails enabled validation.

WriteConcatenatedTags(IEnumerable<NbtTag>, IBufferWriter<byte>)

Writes back-to-back NBT documents to the given buffer writer. Behaves like WriteConcatenatedTags(IEnumerable<NbtTag>, Stream).

public void WriteConcatenatedTags(IEnumerable<NbtTag> tags, IBufferWriter<byte> output)

Parameters

tags IEnumerable<NbtTag>

Root tags to write, one document each. May not contain null.

output IBufferWriter<byte>

Buffer writer to write to.

Remarks

Only the .NET 8 build has this overload.

Exceptions

ArgumentNullException

tags or output is null.

ArgumentException

tags contains a null tag. Documents before it are already written when this throws.

NbtFormatException

If a tag is not a compound and the flavor requires one; if enabled validation rejects a tag type or string length; if a compound contains unnamed tags; if a list has Unknown list type and no elements; if a string is too long; or if tags are nested more than 512 levels deep. Documents before the offending one are already written when this throws.

WriteConcatenatedTags(IEnumerable<NbtTag>, Stream)

Writes back-to-back NBT documents to the given stream, e.g. a Bedrock LevelDB value holding several roots. Mirrors ReadConcatenatedTags(Stream), and is cheaper than repeated WriteTag(NbtTag?, Stream) calls when documents are many.

public void WriteConcatenatedTags(IEnumerable<NbtTag> tags, Stream stream)

Parameters

tags IEnumerable<NbtTag>

Root tags to write, one document each. May not contain null: absent documents cannot appear in a concatenated stream.

stream Stream

Stream to write to.

Exceptions

ArgumentNullException

tags or stream is null.

ArgumentException

tags contains a null tag. Documents before it are already written when this throws.

NbtFormatException

If a tag is not a compound and the flavor requires one; if enabled validation rejects a tag type or string length; if a compound contains unnamed tags; if a list has Unknown list type and no elements; if a string is too long; or if tags are nested more than 512 levels deep. Documents before the offending one are already written when this throws.

WriteTag(NbtTag?)

Writes one NBT document to a new byte array of exactly the right size.

public byte[] WriteTag(NbtTag? tag)

Parameters

tag NbtTag

Root tag to write. For flavors that allow non-compound roots, null writes an absent document (a lone TAG_End byte); other flavors require an NbtCompound. A null root name is written as an empty string.

Returns

byte[]

Byte array containing the serialized document.

Exceptions

ArgumentNullException

tag is null and the flavor requires a compound root.

NotSupportedException

The document does not fit in a single array.

NbtFormatException

If tag is not a compound and the flavor requires one; if enabled validation rejects a tag type or string length; if a compound contains unnamed tags; if a list has Unknown list type and no elements; if a string is too long; or if tags are nested more than 512 levels deep.

WriteTag(NbtTag?, IBufferWriter<byte>)

Writes one NBT document to the given buffer writer, such as a pipe or an ArrayBufferWriter.

public void WriteTag(NbtTag? tag, IBufferWriter<byte> output)

Parameters

tag NbtTag

Root tag to write. For flavors that allow non-compound roots, null writes an absent document (a lone TAG_End byte); other flavors require an NbtCompound. A null root name is written as an empty string.

output IBufferWriter<byte>

Buffer writer to write to.

Remarks

Only the .NET 8 build has this overload.

Exceptions

ArgumentNullException

output is null; or tag is null and the flavor requires a compound root.

NbtFormatException

If tag is not a compound and the flavor requires one; if enabled validation rejects a tag type or string length; if a compound contains unnamed tags; if a list has Unknown list type and no elements; if a string is too long; or if tags are nested more than 512 levels deep.

WriteTag(NbtTag?, Stream)

Writes one NBT document to the given stream.

public void WriteTag(NbtTag? tag, Stream stream)

Parameters

tag NbtTag

Root tag to write. For flavors that allow non-compound roots, null writes an absent document (a lone TAG_End byte); other flavors require an NbtCompound. A null root name is written as an empty string.

stream Stream

Stream to write to.

Exceptions

ArgumentNullException

stream is null; or tag is null and the flavor requires a compound root.

NbtFormatException

If tag is not a compound and the flavor requires one; if enabled validation rejects a tag type or string length; if a compound contains unnamed tags; if a list has Unknown list type and no elements; if a string is too long; or if tags are nested more than 512 levels deep.