fNbt 1.0.0

.NET Standard 2.0

dotnet add package fNbt --version 1.0.0

NuGet\Install-Package fNbt -Version 1.0.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="fNbt" Version="1.0.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="fNbt" Version="1.0.0" />
                    

                            Directory.Packages.props

<PackageReference Include="fNbt" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add fNbt --version 1.0.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: fNbt, 1.0.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package fNbt@1.0.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=fNbt&version=1.0.0
                    

                            Install as a Cake Addin

#tool nuget:?package=fNbt&version=1.0.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Named Binary Tag (NBT) is a structured binary file format used by Minecraft. fNbt is a small library, written in C#. It provides functionality to create, load, traverse, modify, and save NBT files and streams. The library provides a choice of convenient high-level APIs (NbtFile/NbtTag) that present an object model, or lower-level higher-performance APIs (NbtReader/NbtWriter) that read/write data directly to/from streams.

Current released version is 1.0.0 (3 July 2025).

fNbt is based in part on Erik Davidson's (aphistic's) original LibNbt library, now completely rewritten by Matvei Stefarov (fragmer).

FEATURES

Load and save uncompressed, GZip-, and ZLib-compressed files/streams.
Easily create, traverse, and modify NBT documents.
Simple indexer-based syntax for accessing compound, list, and nested tags.
Shortcut properties to access tags' values without unnecessary type casts.
Compound tags implement ICollection<T> and List tags implement IList<T>, for easy traversal and LINQ integration.
Good performance and low memory overhead.
Built-in pretty-printing of individual tags or whole files.
Every class and method are fully documented, annotated, and unit-tested.
Can work with both big-endian and little-endian NBT data and systems.
Optional high-performance reader/writer for working with streams directly.

DOWNLOAD

Latest version of fNbt targets .NET Standard 2.0, which means it can be used in .NET Framework 4.6.1+, .NET Core 2.0+, Mono 5.4+, and more.

Package @ NuGet: https://www.nuget.org/packages/fNbt/
Compiled binaries and single-source-file amalgamations: https://github.com/mstefarov/fNbt/releases

EXAMPLES

Loading a gzipped file

    var myFile = new NbtFile();
    myFile.LoadFromFile("somefile.nbt.gz");
    var myCompoundTag = myFile.RootTag;

Accessing tags (long/strongly-typed style)

    int intVal = myCompoundTag.Get<NbtInt>("intTagsName").Value;
    string listItem = myStringList.Get<NbtString>(0).Value;
    byte nestedVal = myCompTag.Get<NbtCompound>("nestedTag")
                              .Get<NbtByte>("someByteTag")
                              .Value;

Accessing tags (shortcut style)

    int intVal = myCompoundTag["intTagsName"].IntValue;
    string listItem = myStringList[0].StringValue;
    byte nestedVal = myCompTag["nestedTag"]["someByteTag"].ByteValue;

Iterating over all tags in a compound/list

    foreach( NbtTag tag in myCompoundTag.Values ){
        Console.WriteLine( tag.Name + " = " + tag.TagType );
    }
    foreach( string tagName in myCompoundTag.Names ){
        Console.WriteLine( tagName );
    }
    for( int i = 0; i < myListTag.Count; i++ ){
        Console.WriteLine( myListTag[i] );
    }
    foreach( NbtInt intItem in myIntList.ToArray<NbtInt>() ){
        Console.WriteLine( intItem.Value );
    }

Constructing a new document

    var serverInfo = new NbtCompound("Server");
    serverInfo.Add( new NbtString("Name", "BestServerEver") );
    serverInfo.Add( new NbtInt("Players", 15) );
    serverInfo.Add( new NbtInt("MaxPlayers", 20) );
    var serverFile = new NbtFile(serverInfo);
    serverFile.SaveToFile( "server.nbt", NbtCompression.None );

Writing to stream directly using NbtWriter

using (var fileStream = File.Create("foo.nbt", bufferSize: 4 * 1024)) {
    var writer = new NbtWriter(fileStream, "Server");
    writer.WriteString("Name", "BestServerEver");
    writer.WriteInt("Players", 15);
    writer.WriteInt("MaxPlayers", 20);
    writer.EndCompound();
    writer.Finish();
}

Constructing using collection initializer notation

    var compound = new NbtCompound("root"){
        new NbtInt("someInt", 123),
        new NbtList("byteList") {
            new NbtByte(1),
            new NbtByte(2),
            new NbtByte(3)
        },
        new NbtCompound("nestedCompound") {
            new NbtDouble("pi", 3.14)
        }
    };

Pretty-printing file structure

    Console.WriteLine( myFile.ToString("\t") ); // tabs
    Console.WriteLine( myRandomTag.ToString("    ") ); // spaces

Check out unit tests in fNbt.Test for more examples.

API REFERENCE

Online reference can be found at http://www.fcraft.net/fnbt/v1.0.0/

LICENSING

fNbt v0.5.0+ is licensed under 3-Clause BSD license; see docs/LICENSE.txt. LibNbt2012 up to and including v0.4.1 kept LibNbt's original license (LGPLv3).

VERSION HISTORY

See docs/Changelog.md

Product	Compatible and additional computed target framework versions.
.NET	net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.
.NET Core	netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.0 is compatible. netstandard2.1 was computed.
.NET Framework	net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen40 was computed. tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETStandard 2.0
- No dependencies.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on fNbt:

Package	Downloads
GemBlocks A .NET standard library for easy saving/loading/generating of minecraft worlds.	4.1K
fNBT.Serialization Serialization Part of fNBT	2.2K
MCSharp A minecraft network library to make it esier to create minecraft network apps like proxies, oder custom clients	2.2K
YAMNL Yet Another Minecraft Networking Library	266

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on fNbt:

Repository	Stars
Zarbuz/FileToVox Tool for convert files into Magicavoxel file	471

Version	Downloads	Last Updated
1.0.0	172	7/3/2025
0.6.4	26,225	7/6/2018
0.6.3	621,500	4/12/2015
0.6.2	24,551	11/18/2014

## 1.0.0 (fNbt)
- Library now targets .NET Standard 2.0 instead of .NET Framework, which
   allows fNbt to be used in more types of projects (e.g. .NET 8 or UWP).
- Support TAG_Long_Array.
- Fix some edge-cases related to reading corrupted NBT files.
- Switch from JetBrains' annotations to .NET's built-in annotations.

## 0.6.4 (fNbt)
- Fixed a case where NbtBinaryReader.ReadString read too many bytes (#26).
- Fixed NbtList.Contains(null) throwing exception instead of returning false.
- Reduced NbtBinaryReader's maximum chunk size to 4 MB. This reduces peak
   memory use when reading huge files without affecting performance.

## 0.6.3 (fNbt)
- Empty NbtLists now allow "TAG_End" as its ListType (#12).

## 0.6.2 (fNbt)
- NbtTags now implement ICloneable and provide copy constructors (#10).
- fNbt is now compatible with /checked compiler option.
- Fixed an OverflowException in .NET 4.0+ when writing arrays of size 1 GiB
(or larger) to a BufferedStream.
- Fixed a few edge cases in NbtReader when reading corrupt files.
- Minor optimizations and documentation fixes.

## 0.6.1 (fNbt)
- NbtReader now supports non-seekable streams.
- Fixed issues loading from/saving to non-seekable steams in NbtFile.
- NbtFile.LoadFromStream/SaveToStream now accurately report bytes read/written
   for NBT data over 2 GiB in size.
- API change:
   All NbtFile loading/saving methods now return long instead of int.

## 0.6.0 (fNbt)
- Raised .NET framework requirements from 2.0+ to 3.5+
- Added NbtWriter, for linearly writing NBT streams, similarly to XmlWriter.
   It enables high-performance writing, without creating temp NbtTag objects.
- Fixed handling of lists-of-lists and lists-of-compound-tags in NbtReader.
- Fixed being able to add an NbtList to itself.
- API changes:
   Removed NbtCompound.ToArray(), use NbtCompound.Tags.ToArray() instead.
   Removed NbtCompound.ToNameArray(), use NbtCompound.Names.ToArray() instead.
- Improved tag reading and writing performance.
- Expanded unit test coverage.

## 0.5.1 (fNbt)
- Fixed ToString() methods of NbtReader and some NbtTags not respecting the
   NbtTag.DefaultIndentString setting.
- Fixed being able to add a Compound tag to itself.
- Fixed NbtString value defaulting to null, instead of an empty string.
- Fixed a number of bugs in NbtReader.ReadListAsArray<T>().
- API additions:
   New NbtReader property:     bool IsAtStreamEnd
   New NbtReader overload:     string ToString(bool,string)
- Expanded unit test coverage.

## 0.5.0 (fNbt)
- Added NbtReader, for linearly reading NBT streams, similarly to XmlReader.
- API additions:
   New NbtCompound method:     bool TryGet(string,out NbtTag)
   New NbtCompound overload:   NbtTag Get(string)
   New NbtTag property:        bool HasValue
- License changed from LGPL to to 3-Clause BSD, since none of the original
   libnbt source code remains.

## 0.4.1 (LibNbt2012)
- Added a way to set up default indent for NbtTag.ToString() methods, using
   NbtTag.DefaultIndentString static property.
- Added a way to control/disable buffering when reading tags, using properties
   NbtFile.DefaultBufferSize (static) and "nbtFile.BufferSize" (instance).
- Simplified renaming tags. Instead of using NbtFile.RenameRootTag or
   NbtCompound.RenameTag, you can now set tag's Name property directly. It
   will check parent tag automatically, and throw ArgumentException or
   ArgumentNullException is renaming is not possible.
- NbtFile() constructor now initializes RootTag to an empty NbtCompound("").
- Added LoadFro* overloads that do not require a TagSelector parameter.

## 0.4.0 (LibNbt2012)
- Changed the way NbtFiles are constructed. Data is not loaded in the
   constructor itself any more, use LoadFrom* method.
- Added a way to load NBT data directly from byte arrays, and to save them to
   byte arrays.
- All LoadFrom-/SaveTo- methods now return an int, indicating the number of
   bytes read/written.
- Updated NbtFile to override ToString.
- Added a way to control endianness when reading/writing NBT files.

## 0.3.4 (LibNbt2012)
- Added a way to rename tags inside NbtCompound and NbtFile.

## 0.3.3 (LibNbt2012)
- Added a way to skip certain tags at load-time, using a TagSelector callback.

## 0.3.2 (LibNbt2012)
- Added a way to easily identify files, using static NbtFile.ReadRootTagName.
- Added NbtTag.Parent (automatically set/reset by NbtList and NbtCompound).
- Added NbtTag.Path (which includes parents' names, and list indices).
- Added NbtCompound.Names and NbtCompound.Values enumerators.

## 0.3.1 (LibNbt2012)
- Added indexers to NbtTag base class, to make nested compound/list tags easier
   to work with.
- Added shortcut properties for getting tag values.
- Added a ToArray<T>() overload to NbtList, to automate casting to a specific
   tag type.
- Improved .ToString() pretty-printing, now with consistent and configurable
   indentation.

## 0.3.0 (LibNbt2012)
- Auto-detection of NBT file compression.
- Loading and saving of ZLib (RFC-1950) compresessed NBT files.
- Reduced loading/saving CPU use by 15%, and memory use by 40%
- Full support for TAG_Int_Array
- NbtCompound now implements ICollection and ICollection<NbtTag>
- NbtList now implements IList and IList<NbtTag>
- More constraint checks to tag loading, modification, and saving.
- Replaced getter/setter methods with properties, wherever possible.
- Expanded unit test coverage.
- Fully documented everything.
- Made tag names immutable.
- Removed tag queries.

## 0.2.0 (libnbt)
- Implemented tag queries.
- Created unit tests for the larger portions of the code.
- Marked tag constructors that take only tag values as obsolete, use the
   constructor that has name and value instead.

## 0.1.2 (libnbt)
- Added a GetTagType() function to the tag classes.
- Fixed saving NbtList tags.

## 0.1.1 (libnbt)
- Initial release.
- Modified the tag constructors to be consistant with each other.
- Changed NbtFile to allow some functions to be overridden.