amulet-team / amulet-nbt

A Python and Cython library for reading and writing binary NBT and stringified NBT.

Amulet-NBT

Amulet-NBT is a Python 3 library, written in Cython and C++, for reading and writing both binary NBT and SNBT.

SNBT (or Stringified-NBT) is the JSON like format used in Java commands.

Installing

Run this command to install from PyPi.

pip install amulet-nbt~=3.0

Documentation

See our readthedocs site for the full documentation of this library.

Development

To develop the library you will need to download the source and run this command from the root directory.

pip install -e .[dev]

This will build the library in-place and expose it to python. Since this code is compiled you will need to run it again each time you change cython or C++ code.

Links

• Documentation - https://amulet-nbt.readthedocs.io
• Github - https://github.com/Amulet-Team/Amulet-NBT
• Website - https://www.amuletmc.com/

amulet-nbt's Issues

Fails to pickup system-wide numpy installation

I have numpy 1.18.4 installed system-wide, but when running python3 setup.py build to make a distribution package for Amulet-NBT, it still tries to download numpy from pip. Because this build system blocks network access for builds, this obviously fails.

Cython however is picked up from the system.

Loading Minecraft region (*.mca) files

Minecraft region files aren't entirely NBT so you can't load them directly with Amulet-NBT. This helper function should be able to extract and load the chunks.

from struct import iter_unpack, unpack
import amulet_nbt as nbt
import zlib
import io

def load_mca(filename):
    chunks = []
    with open(filename, 'rb') as f:
        for (pointer,) in iter_unpack('>I', f.read(4096)):
            if pointer == 0:
                continue
            offset = ((pointer >> 8) & 0xffffff) * 4096
            f.seek(offset, io.SEEK_SET)
            size = unpack('>I', f.read(4))[0]
            offset += 5
            f.seek(offset, io.SEEK_SET)
            tags = f.read(size)
            tags = zlib.decompress(tags)
            tags = nbt.load(tags, compressed=False)
            chunks.append(tags)
    return chunks

snbt conversion error

When converting NBT from an empty Byte array, it returns [B;B] when it should return [B;] < this may also happen with other arrays.

Modify level.dat fields

I'm currently trying to find a way to programmatically edit individual fields in a Bedrock (1.17) level.dat file.

Using the getting started example, I've got as far as being able to load in the level.dat file, but not much further in actually reading and writing the individual fields.
A quick example running through reading/writing would be super helpful.
I'm also not sure if I should be using Amulet-NBT or Amulet-Core? I've taken a look at using Amulet-Core as well with the below code with no luck.

import amulet.libs.leveldb
level = amulet.libs.leveldb.LevelDB("world_folder_name")
for item in level.iterate(): # A blank iterator
   print(item) 
print(a.get("allowmobs".encode())) # Errors with KeyError: "Key b'allowmobs' not found in database."

Any advice or suggestions would be greatly appreciated!

Undefined symbol: PyMemoryview_Check

When trying to run Amulet Map Editor this error is thrown from Amulet-NBT module:

ImportError: /home/yogsot/.pyenv/versions/3.7.16/lib/python3.7/site-packages/amulet_nbt/_load_nbt.cpython-37m-x86_64-linux-gnu.so: undefined symbol: PyMemoryview_Check

After searching I found Python documentation where "view" is capitalized.Is this a case of typo in code?
https://docs.python.org/3.7/c-api/memoryview.html

Release Python 3.11 wheels on PyPI

Currently in order to install the module on Python 3.11 you have to have C++ build tools installed. I think it would be helpful for some people if they could just install it without it.

Error deep copying an nbt object with the python version

  File "D:\Data\GitHub\Amulet-Map-Editor\venv\lib\site-packages\amulet\api\block.py", line 172, in properties
    return copy.deepcopy(self._properties)
  File "C:\Users\james_000\AppData\Local\Programs\Python\Python37\lib\copy.py", line 150, in deepcopy
    y = copier(x, memo)
  File "C:\Users\james_000\AppData\Local\Programs\Python\Python37\lib\copy.py", line 241, in _deepcopy_dict
    y[deepcopy(key, memo)] = deepcopy(value, memo)
  File "C:\Users\james_000\AppData\Local\Programs\Python\Python37\lib\copy.py", line 161, in deepcopy
    y = copier(memo)
  File "D:\Data\GitHub\Amulet-Map-Editor\venv\lib\site-packages\amulet_nbt\amulet_py_nbt.py", line 312, in __deepcopy__
    return self.__class__(self.value.__deepcopy__(memo or {}))
AttributeError: 'int' object has no attribute '__deepcopy__'

Error decoding NBT data from my bedrock world.

I am getting a UnicodeDecodeError exception when parsing nbt from my vanilla bedrock world. Am I doing something wrong, is there a problem with my world data, or is there a bug in the library?

from leveldb import LevelDB
from struct import pack
import amulet_nbt

x = 1
z = 0
tag = b'\x31'
key = pack('iic', x, z, tag)
print("Key-\n", key)

db = LevelDB("/home/ubuntu/tmp/SpringbeanFarm/db", False)
value = db.get(key)
print("Value-\n", value)
nbt = amulet_nbt.load_array(value, count = -1, little_endian=True)

The NBT is 99754 bytes, so I can't post the output here. I have it at this pastebin.

Installed, can't launch.

When I do python -m pip install amulet-map-editor==0.8.2 --upgrade I'm getting

Requirement already up-to-date: amulet-map-editor==0.8.2 in ./.local/lib/python3.8/site-packages (0.8.2)
Requirement already satisfied, skipping upgrade: numpy in /usr/lib/python3/dist-packages (from amulet-map-editor==0.8.2) (1.18.4)
Requirement already satisfied, skipping upgrade: amulet-nbt~=1.0.3 in ./.local/lib/python3.8/site-packages (from amulet-map-editor==0.8.2) (1.0.3.8)
Requirement already satisfied, skipping upgrade: pyopengl in /usr/lib/python3/dist-packages (from amulet-map-editor==0.8.2) (3.1.5)
Requirement already satisfied, skipping upgrade: minecraft-resource-pack~=1.2.0 in ./.local/lib/python3.8/site-packages (from amulet-map-editor==0.8.2) (1.2.1)
Requirement already satisfied, skipping upgrade: pymctranslate~=1.0.0 in ./.local/lib/python3.8/site-packages (from amulet-map-editor==0.8.2) (1.0.2)
Requirement already satisfied, skipping upgrade: amulet-core~=1.2.1 in ./.local/lib/python3.8/site-packages (from amulet-map-editor==0.8.2) (1.2.3)
Requirement already satisfied, skipping upgrade: cython>=0.29.13 in ./.local/lib/python3.8/site-packages (from amulet-nbt~=1.0.3->amulet-map-editor==0.8.2) (0.29.22)
Requirement already satisfied, skipping upgrade: Pillow>=7.1.0 in /usr/lib/python3/dist-packages (from minecraft-resource-pack~=1.2.0->amulet-map-editor==0.8.2) (7.2.0)

but when I try to launch python amulet_map_editor - python: can't open file 'amulet_map_editor': [Errno 2] No such file or directory.

UTF-8 Decode error

I am not entirely sure what the issue is here.
In Bedrock if you paste this command /kill @e[name=§9§lDiscord Kit] into a command block and run it then close the world and try and open in Amulet the NBT library will give an error.
The error will look something like this

  File "amulet_nbt\amulet_cy_nbt.pyx", line 1073, in amulet_nbt.amulet_cy_nbt.load
  File "amulet_nbt\amulet_cy_nbt.pyx", line 1136, in amulet_nbt.amulet_cy_nbt.load_compound_tag
  File "amulet_nbt\amulet_cy_nbt.pyx", line 136, in amulet_nbt.amulet_cy_nbt.load_named
  File "amulet_nbt\amulet_cy_nbt.pyx", line 165, in amulet_nbt.amulet_cy_nbt.load_tag
  File "amulet_nbt\amulet_cy_nbt.pyx", line 1188, in amulet_nbt.amulet_cy_nbt.load_list
  File "amulet_nbt\amulet_cy_nbt.pyx", line 162, in amulet_nbt.amulet_cy_nbt.load_tag
  File "amulet_nbt\amulet_cy_nbt.pyx", line 1145, in amulet_nbt.amulet_cy_nbt.load_string
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa7 in position 0: invalid start byte

The cause is this string b"\xa7lDiscord " appearing in the metadata which the NBT library fails to load.
The correct UTF-8 encoded version of that string would be b"\xc2\xa7lDiscord ".
I am not sure if the encoding they are using is slightly different to the normal UTF-8 or if the string is actually invalid and the game is somehow silently handling it.
The actual command string is encoded as /kill @e[name=\xc2\xa79\xc2\xa7lDiscord Kit] which is correct UTF-8
The game could just be showing the last 10 "characters" of the full string and has cut it around the bytes rather than the real string leading to the encoding error.
Either way I don't know what the solution is here

Add license

I'm looking into packaging this and the rest of Amulet for Alpine Linux, but to do the package requires a (approved by FSF and OSI) license. So far I couldn't find any license to this particular project, please add it.