Table of Contents

Class NbtTag

Namespace
fNbt
Assembly
fNbt.dll

Base class for different kinds of named binary tags.

public abstract class NbtTag : ICloneable
Inheritance
NbtTag
Implements
Derived
Inherited Members

Properties

ByteArrayValue

Returns the value of this tag, cast as a byte array. Only supported by NbtByteArray tags.

public byte[] ByteArrayValue { get; }

Property Value

byte[]

Exceptions

InvalidCastException

When used on a tag other than NbtByteArray.

ByteValue

Returns the value of this tag, cast as a byte. Only supported by NbtByte tags.

public byte ByteValue { get; }

Property Value

byte

Exceptions

InvalidCastException

When used on a tag other than NbtByte.

DefaultIndentString

String to use for indentation in ToString() and ToString() by default.

public static string DefaultIndentString { get; set; }

Property Value

string

Exceptions

ArgumentNullException

value is null.

DoubleValue

Returns the value of this tag, cast as a double (double-precision floating point number). Only supported by NbtFloat, NbtDouble, and, with loss of precision, by NbtByte, NbtShort, NbtInt, and NbtLong.

public double DoubleValue { get; }

Property Value

double

Exceptions

InvalidCastException

When used on an unsupported tag.

FloatValue

Returns the value of this tag, cast as a float (single-precision floating point number). Only supported by NbtFloat and, with loss of precision, by NbtDouble, NbtByte, NbtShort, NbtInt, and NbtLong.

public float FloatValue { get; }

Property Value

float

Exceptions

InvalidCastException

When used on an unsupported tag.

HasValue

Returns true if tags of this type have a value attached. All tags except Compound, List, and End have values.

public bool HasValue { get; }

Property Value

bool

IntArrayValue

Returns the value of this tag, cast as an int array. Only supported by NbtIntArray tags.

public int[] IntArrayValue { get; }

Property Value

int[]

Exceptions

InvalidCastException

When used on a tag other than NbtIntArray.

IntValue

Returns the value of this tag, cast as an int (32-bit signed integer). Only supported by NbtByte, NbtShort, and NbtInt.

public int IntValue { get; }

Property Value

int

Exceptions

InvalidCastException

When used on an unsupported tag.

this[int]

Gets or sets the tag at the specified index.

public virtual NbtTag this[int tagIndex] { get; set; }

Parameters

tagIndex int

The zero-based index of the tag to get or set.

Property Value

NbtTag

The tag at the specified index.

Remarks

ONLY APPLICABLE TO NbtList OBJECTS! The array tags hide this indexer with their own, so those work only through their own type. Included in NbtTag base class for programmers' convenience, to avoid extra type casts.

Exceptions

ArgumentOutOfRangeException

tagIndex is not a valid index in this tag.

ArgumentNullException

Given tag is null.

ArgumentException

Given tag's type does not match ListType.

InvalidOperationException

If used on a tag that is not NbtList.

this[string]

Gets or sets the tag with the specified name. May return null.

public virtual NbtTag? this[string tagName] { get; set; }

Parameters

tagName string

The name of the tag to get or set. Must match tag's actual name.

Property Value

NbtTag

The tag with the specified key. Null if tag with the given name was not found.

Remarks

ONLY APPLICABLE TO NbtCompound OBJECTS! Included in NbtTag base class for programmers' convenience, to avoid extra type casts.

Exceptions

InvalidOperationException

If used on a tag that is not NbtCompound.

LongArrayValue

Returns the value of this tag, cast as a long array. Only supported by NbtLongArray tags.

public long[] LongArrayValue { get; }

Property Value

long[]

Exceptions

InvalidCastException

When used on a tag other than NbtLongArray.

LongValue

Returns the value of this tag, cast as a long (64-bit signed integer). Only supported by NbtByte, NbtShort, NbtInt, and NbtLong.

public long LongValue { get; }

Property Value

long

Exceptions

InvalidCastException

When used on an unsupported tag.

Name

Name of this tag. May be null. Renaming a tag that resides in an NbtCompound re-keys it in that compound.

public string? Name { get; set; }

Property Value

string

Exceptions

ArgumentNullException

If value is null, and Parent tag is an NbtCompound. Name of tags inside an NbtCompound may not be null.

ArgumentException

If this tag resides in an NbtCompound, and a sibling tag with the name already exists.

InvalidOperationException

If this tag's parent compound no longer contains it, which most likely indicates unsynchronized modification from multiple threads.

Parent

Parent compound tag, either NbtList or NbtCompound, if any. May be null for detached tags.

public NbtTag? Parent { get; }

Property Value

NbtTag

Path

Gets the full name of this tag, including all parent tag names, separated by dots. Unnamed tags show up as empty strings.

public string Path { get; }

Property Value

string

ShortValue

Returns the value of this tag, cast as a short (16-bit signed integer). Only supported by NbtByte and NbtShort.

public short ShortValue { get; }

Property Value

short

Exceptions

InvalidCastException

When used on an unsupported tag.

StringValue

Returns the value of this tag, cast as a string. Returns exact value for NbtString, and stringified (using InvariantCulture) value for NbtByte, NbtDouble, NbtFloat, NbtInt, NbtLong, and NbtShort. Not supported by NbtCompound, NbtList, NbtByteArray, NbtIntArray, or NbtLongArray.

public string StringValue { get; }

Property Value

string

Exceptions

InvalidCastException

When used on an unsupported tag.

TagType

Type of this tag.

public abstract NbtTagType TagType { get; }

Property Value

NbtTagType

Methods

Clone()

Creates a deep copy of this tag.

public object Clone()

Returns

object

A new NbtTag object that is a deep copy of this instance.

Exceptions

NbtFormatException

This tag is nested deeper than 512 levels.

GetCanonicalTagName(NbtTagType)

Returns a canonical (Notchy) name for the given NbtTagType, e.g. "TAG_Byte_Array" for ByteArray

public static string? GetCanonicalTagName(NbtTagType type)

Parameters

type NbtTagType

NbtTagType to name.

Returns

string

String representing the canonical name of a tag, or null of given TagType does not have a canonical name (e.g. Unknown).

ParseSnbt(string)

Parses one SNBT (stringified NBT) value, which must be the whole text apart from surrounding whitespace. Returns an unnamed tag of any type.

public static NbtTag ParseSnbt(string text)

Parameters

text string

The SNBT text.

Returns

NbtTag

The parsed tag, unnamed.

Remarks

Reads the old (1.12 to 1.21.4) and the modern Minecraft Java syntax plus what common NBT tools write, as their union: the 1.21.5 grammar (hex, binary and underscored numbers, signedness suffixes, the full escape set, bool() and uuid(), lists of mixed types, one trailing comma) with the old parser's readings wherever the modern one refuses (a token such as 1st, 007 or 300b is a string, an overflowing float is an infinity). NaNf, Infinityd and the like read as the numbers they name, a quoted empty key is allowed, array prefixes and operation names are accepted in either case, and a byte literal from 128b to 255b, which no Minecraft version reads as a number, is the unsigned byte Value holds (-1b and 255b are the same byte). A list of mixed types becomes a list of compounds in which every element that is not a plain compound sits under an empty key, the form Minecraft 1.21.5 and later store on disk and CreateMixed(params NbtTag[]) builds; UnwrapMixed() reads through it. An empty list has the End element type. A byte order mark at the start of the text is skipped. \N{name} escapes are not supported.

Exceptions

ArgumentNullException

text is null.

SnbtParseException

The text is not SNBT, has anything but whitespace after the value, or nests deeper than 512 levels. The exception gives the position.

ParseSnbt(string, int, out int)

Parses one SNBT (stringified NBT) value starting at the given index, stops after it, and reports how many characters it consumed. Text after the value is left alone, for pulling a value out of a longer command line. See ParseSnbt(string) for what is accepted.

public static NbtTag ParseSnbt(string text, int index, out int charsConsumed)

Parameters

text string

Text containing the SNBT value.

index int

Position at which the value starts; leading whitespace is skipped.

charsConsumed int

Number of characters from index to the end of the value, so that index plus this count is the position right after the value. Whitespace before the value is counted; whitespace after it is not consumed.

Returns

NbtTag

The parsed tag, unnamed.

Exceptions

ArgumentNullException

text is null.

ArgumentOutOfRangeException

index is negative or past the end of the text.

SnbtParseException

No value starts at the index, or the value nests deeper than 512 levels. Index is the position within text.

ToSnbt()

Prints this tag and its children as SNBT (stringified NBT), the text notation Minecraft Java uses in commands and .snbt files, in the layout given by DefaultWriteLayout. The tag's Name is not written: SNBT has no root name, and tags inside a compound are written with their keys already.

public string ToSnbt()

Returns

string

The SNBT text.

Remarks

The text keeps to what the old Minecraft Java parser (1.12 to 1.21.4) reads wherever it can: strings are always in double quotes, the only delimiter Minecraft 1.12 and 1.13 read, with just the quote and backslashes escaped; keys are bare when they consist of letters, digits and .+-, start with a letter, . or , and are not true or false; numbers carry Java's suffixes and spelling (1b, 1s, 1L, 1.0f, 1.0E7d), with bytes signed the way Minecraft stores them (a Value of 255 prints as -1b, its SignedValue); compounds keep insertion order. Three things fall outside that. Inside a list of compounds, a one-entry compound whose key is empty prints as its value, the form Minecraft 1.21.5 and later store on disk for lists of mixed types (UnwrapMixed() reads the same way), so a list holding one needs Minecraft Java 1.21.5 or a tool that reads mixed lists. NaN and infinities print as NaNf or Infinityd, the way Minecraft prints them, and an empty key prints as ""; no Minecraft version reads either back as the same value. ParseSnbt(string) reads all three.

Exceptions

NbtFormatException

This tag is nested deeper than 512 levels.

ToSnbt(SnbtOptions)

Prints this tag and its children as SNBT (stringified NBT) with the given options. See ToSnbt() for what is written.

public string ToSnbt(SnbtOptions options)

Parameters

options SnbtOptions

Settings to use, read when the call starts.

Returns

string

The SNBT text.

Exceptions

ArgumentNullException

options is null.

NbtFormatException

This tag is nested deeper than 512 levels.

ToString()

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

public override string ToString()

Returns

string

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

Exceptions

NbtFormatException

This tag is nested deeper than 512 levels.

ToString(string)

Prints contents of this 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.

NbtFormatException

This tag is nested deeper than 512 levels.