1# Import the nbt library
2# Option 1 - import the package then refer to attributes on the package
3import amulet_nbt
4
5# Option 2 - import attributes from the package
6from amulet_nbt import (
7 ByteTag,
8 ShortTag,
9 IntTag,
10 LongTag,
11 FloatTag,
12 DoubleTag,
13 StringTag,
14 ListTag,
15 CompoundTag,
16 ByteArrayTag,
17 IntArrayTag,
18 LongArrayTag,
19 NamedTag,
20 utf8_decoder,
21 utf8_encoder,
22 utf8_escape_decoder,
23 utf8_escape_encoder,
24)
25
26from mutf8 import decode_modified_utf8, encode_modified_utf8
27
28# These classes are also available under their old names
29# from amulet_nbt import (
30# TAG_Byte,
31# TAG_Short,
32# TAG_Int,
33# TAG_Long,
34# TAG_Float,
35# TAG_Double,
36# TAG_String,
37# TAG_List,
38# TAG_Compound,
39# TAG_Byte_Array,
40# TAG_Int_Array,
41# TAG_Long_Array
42# )
43
44named_tag: NamedTag
45java_named_tag: NamedTag
46bedrock_named_tag: NamedTag
47
48# Load binary NBT
49named_tag = amulet_nbt.load(
50 "the/path/to/your/binary/nbt/file",
51 compressed=True, # These inputs must be specified as keyword inputs like this.
52 little_endian=False, # If you do not define them they will default to these values
53 string_decoder=utf8_decoder
54) # from a file
55named_tag = amulet_nbt.load(b'<nbt file bytes>') # from a bytes object
56
57# Note that Java Edition usually uses compressed modified UTF-8.
58java_named_tag = amulet_nbt.load(
59 "the/path/to/your/binary/java/nbt/file",
60 string_decoder=decode_modified_utf8
61)
62
63# Bedrock edition data is stored in little endian format and uses non-compressed UTF-8 but can also have arbitrary bytes.
64bedrock_named_tag = amulet_nbt.load(
65 "the/path/to/your/binary/bedrock/nbt/file",
66 compressed=False,
67 little_endian=True,
68 string_decoder=utf8_escape_decoder # This decoder will escape all invalid bytes to the string ␛xHH
69)
70
71# Save the data back to a file
72named_tag.save_to(
73 "the/path/to/write/to",
74 compressed=True, # These inputs must be specified as keyword inputs like this.
75 little_endian=False, # If you do not define them they will default to these values
76 string_encoder=utf8_encoder
77)
78
79# save_to can also be given a file object to write to.
80with open('filepath', 'wb') as f:
81 named_tag.save_to(f)
82
83# Like earlier you will need to give the correct options for the platform you are using.
84# Java
85java_named_tag.save_to(
86 "the/path/to/write/to",
87 string_encoder=encode_modified_utf8
88)
89
90# Bedrock
91bedrock_named_tag.save_to(
92 "the/path/to/write/to",
93 compressed=False,
94 little_endian=True,
95 string_encoder=utf8_escape_encoder
96)
97
98
99# You can also parse the stringified NBT format used in Java commands.
100tag = amulet_nbt.from_snbt('{key1: "value", key2: 0b, key3: 0.0f}')
101# tag should look like this
102# TAG_Compound(
103# key1: TAG_String("value"),
104# key2: TAG_Byte(0)
105# key3: TAG_Float(0.0)
106# )
107
108# Tags can be saved like the NamedTag class but they do not have a name.
109tag.save_to(
110 'filepath',
111 # see the NBTFile save_to documentation above for other options.
112 name="" # Tag classes do not store their name so you can define it here.
113)
114tag.to_snbt() # convert back to SNBT
115
116# The classes can also be constructed manually like this
117tag = CompoundTag({
118 "key1": ByteTag(0), # if no input value is given it will automatically fill these defaults
119 "key2": ShortTag(0),
120 "key3": IntTag(0),
121 "key4": LongTag(0),
122 "key5": FloatTag(0.0),
123 "key6": DoubleTag(0.0),
124 "key7": ByteArrayTag([]),
125 "key8": StringTag(""),
126 "key9": ListTag([]),
127 "key10": CompoundTag({}),
128 "key11": IntArrayTag([]),
129 "key12": LongArrayTag([])
130})
131
132named_tag = NamedTag(
133 tag,
134 name="" # Optional name input.
135)