PHP library for working with the NBT (Named Binary Tag) data storage format, as designed by Mojang.
LGPL-3.0 License
Bot releases are visible (Hide)
BaseNbtSerializer->readHeadless()
and BaseNbtSerializer->writeHeadless()
. These are needed for one specific place in the Bedrock protocol and are otherwise not usually seen.Despite the version bump to 1.0.0, this isn't a huge release. Staying on 0.x for so long was a mistake that needed to be corrected.
Published by dktapps over 1 year ago
NbtDataException
is now thrown in these cases.Published by dktapps over 2 years ago
JsonNbtParser
no longer throws InvalidArgumentException
when attempting to create tags with out-of-bounds values (e.g. TAG_Byte with value larger than a byte) - NbtDataException
is now thrown instead.JsonNbtParser
no longer throws TypeError
when attempting to create TAG_List
with mixed value types - NbtDataException
is now thrown instead.Published by dktapps almost 3 years ago
TAG_Compound
s containing repeated keys in binary data is no longer treated as a corruption case. While it technically is corruption, it's problematic to throw on it due to inability to recover the data using this library.Published by dktapps almost 3 years ago
TAG_Compound
s containing repeated keys in binary data is no longer treated as a corruption case. While it technically is corruption, it's problematic due to inability to recover the data using this library.Published by dktapps almost 3 years ago
UnexpectedValueException
being thrown instead of NbtDataException
when encountering a non-empty list of TAG_End
.Published by dktapps over 3 years ago
This is a major release featuring significant API changes. It is not API-compatible with 0.2.x.
NbtDataException
to be thrown, instead of a generic \UnexpectedValueException
.BinaryStream
provided by pocketmine/binaryutils
to decode data, instead of an in-house implementation.ext-zlib
. Instead, decompressing of compressed NBT is left to the user, which allows more freedom of usage of the library, as well as enabling the usage of faster compressors such as ext-libdeflate
.__toString()
on tags has been revamped for improved readability.
ByteArrayTag
s are now printed as base64 to prevent console breakage.NBTStream
has been renamed to BaseNbtSerializer
.LittleEndianNBTStream
has been renamed to LittleEndianNbtSerializer
.BigEndianNBTStream
has been renamed to BigEndianNbtSerializer
.NamedTag
has been renamed to Tag
(although all of the functionality that made it Named
has been removed - see below).NetworkLittleEndianNBTStream
has been removed. Since the format of this type of NBT is dependent on the current Minecraft protocol, and not standard, it's too volatile for inclusion in this library.
NetworkNbtSerializer
serves as the replacement.BaseNbtSerializer
(previously NBTStream
) has the following changes:
write()
now accepts a TreeRoot
instead of a NamedTag
. Since tags don't contain names anymore, this allows the root tag to be named if desired.write()
no longer accepts an array of tags.writeMultiple()
has been added.read()
now returns a TreeRoot
instead of a NamedTag
.read()
no longer accepts a $doMultiple
parameter.readMultiple()
method has been added.read()
and readMultiple()
now throw NbtDataException
on data errors, instead of \UnexpectedValueException
.toArray()
and fromArray()
were removed. This functionality had no clear purpose and was heavily broken for several years.readCompressed()
and writeCompressed()
were removed. The user is now responsible for decompressing before decoding, and compressing after encoding (if necessary).JsonNbtParser
has the following changes:
parseJson()
now always returns CompoundTag
. If an error occurs during deserialization, an exception will be thrown.parseJson()
now throws NbtDataException
instead of \UnexpectedValueException
on bad data.Tag
s no longer contain names. Since names are keys for TAG_Compound
, it didn't make sense for the tags themselves to contain them.
Tag
constructors have had the $name
argument removed. They now only accept values.TAG_Compound
, a TreeRoot
class has been added.getName()
and setName()
have been removed.Tag
s with the same values will now compare as equal, regardless of their positions in lists or keys in compounds.Tag->read()
has been made static. This allows simple tag types to be immutable, which significantly improves performance during cloning.Tag
implementations are now final
.ListTag
has the following changes:
ArrayAccess
interfaces. Since ListTag
is strictly expected to behave like a list, it was too ambiguous what array access was supposed to do.IteratorAggregate
instead of Iterator
. This allows by-value modification of the ListTag
while iterating over it, similar to how an array works.CompoundTag
has the following changes:
ArrayAccess
is no longer supported. Its magical behaviour was impossible to statically analyse, and it was unclear what its behaviour was in some circumstances.IteratorAggregate
is now implemented instead of Iterator
. This allows by-value modification during iteration without breaking iteration, similar to how array copy-on-write works.getTagValue()
is no longer exposed to the public API.hasTag()
has been removed. It can be replaced by a statement like if(($tag = $compound->getTag("name")) instanceof SomeTag)
instead, which is faster and more static-analysis-friendly.getTag()
no longer accepts an $expectedTagType
parameter (see previous point).setTag()
now requires a $name
argument before the $tag
.setByte()
, setShort()
, setInt()
etc. now all require a $name
argument in addition to the $value
argument.setByte()
, setShort()
, setInt()
etc. have had the $force
argument removed.setByte()
, setShort()
, setInt()
etc. are now fluent.getByte()
, getShort()
, getInt()
etc. have had the $badTagDefault
argument removed.getByte()
, getShort()
, getInt()
etc. may now throw UnexpectedTagTypeException
or NoSuchTagException
when encountering incompatible data, instead of \UnexpectedValueException
.setTag()
no longer throws an exception when overwriting a tag of a different type. Since NBT should usually be built from scratch on save anyway, this check didn't make much sense.Published by dktapps over 3 years ago
Published by dktapps over 3 years ago
FloatTag
incorrectly comparing as not-equal after encode/decode with values such as 0.3
(stored with higher precision in memory (64-bit) than possible to represent (32-bit)).Published by dktapps almost 4 years ago
Published by dktapps about 4 years ago
NBTStream->read()
now throws UnexpectedValueException
instead of InvalidArgumentException
when encountering a TAG_End
at the beginning of a NBT buffer.NBTStream->readCompressed()
now throws UnexpectedValueException()
on decompression failures instead of passing false
to read()
and exploding things.NBTStream::fromArray()
and NBTStream::toArray()
mishandling IntArrayTag
s.CompoundTag
and ListTag
now throw OutOfBoundsException
when calling current()
or key()
when their iterators are invalid.Published by dktapps over 4 years ago
TAG_Compound
.TAG_Compound
during decoding.Published by dktapps almost 5 years ago
NBTStream->read()
and NBTStream->write()
with non-compound root tags. These had never been seen before Minecraft Bedrock 1.13.Published by dktapps almost 5 years ago
NBTStream->get()
now throws BinaryDataException
when there are not enough bytes left to read.CompoundTag->getTag()
.Published by dktapps about 5 years ago
Published by dktapps about 5 years ago
pocketmine/binaryutils
^0.1.9
is now required.Published by dktapps about 5 years ago
Published by dktapps about 5 years ago
NBTStream->read()
now supports an optional $maxDepth
parameter.Published by dktapps over 5 years ago
JsonNbtParser
now throws more specific exceptions.NBTStream->read()
now accepts a reference $offset
parameter which can be used to start reading from a specific point in a string payload.Published by dktapps over 5 years ago