diff --git a/mappings/net/minecraft/nbt/AbstractNbtList.mapping b/mappings/net/minecraft/nbt/AbstractNbtList.mapping index 1d2787c87b..7d163e35f9 100644 --- a/mappings/net/minecraft/nbt/AbstractNbtList.mapping +++ b/mappings/net/minecraft/nbt/AbstractNbtList.mapping @@ -4,9 +4,17 @@ CLASS net/minecraft/class_2483 net/minecraft/nbt/AbstractNbtList ARG 1 index ARG 2 value METHOD method_10533 addElement (ILnet/minecraft/class_2520;)Z + COMMENT Inserts {@code element} at {@code index}. Does nothing if the + COMMENT types were incompatible. + COMMENT + COMMENT @return whether the element was actually added ARG 1 index ARG 2 element METHOD method_10535 setElement (ILnet/minecraft/class_2520;)Z + COMMENT Sets the element at {@code index} to {@code element}. Does nothing if + COMMENT the types were incompatible. + COMMENT + COMMENT @return whether the element was actually set ARG 1 index ARG 2 element METHOD method_10601 getHeldType ()B diff --git a/mappings/net/minecraft/nbt/NbtByte.mapping b/mappings/net/minecraft/nbt/NbtByte.mapping index b644c47912..007a14713a 100644 --- a/mappings/net/minecraft/nbt/NbtByte.mapping +++ b/mappings/net/minecraft/nbt/NbtByte.mapping @@ -1,17 +1,28 @@ CLASS net/minecraft/class_2481 net/minecraft/nbt/NbtByte - COMMENT Represents an NBT byte. + COMMENT Represents an NBT byte. Its type is {@value NbtElement#BYTE_TYPE}. + COMMENT Instances are immutable. FIELD field_11498 value B FIELD field_21025 TYPE Lnet/minecraft/class_4614; FIELD field_21026 ZERO Lnet/minecraft/class_2481; + COMMENT The NBT byte representing {@code 0}. + COMMENT + COMMENT @apiNote This is often used to indicate a false boolean value. FIELD field_21027 ONE Lnet/minecraft/class_2481; + COMMENT The NBT byte representing {@code 1}. + COMMENT + COMMENT @apiNote This is often used to indicate a true boolean value. FIELD field_33189 SIZE I METHOD (B)V ARG 1 value METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_23233 of (B)Lnet/minecraft/class_2481; + COMMENT {@return the NBT byte from {@code value}} + COMMENT + COMMENT @implNote This returns the value from the cache. ARG 0 value METHOD method_23234 of (Z)Lnet/minecraft/class_2481; + COMMENT {@return the NBT byte representing the boolean {@code value}} ARG 0 value CLASS class_4610 Cache FIELD field_21028 VALUES [Lnet/minecraft/class_2481; diff --git a/mappings/net/minecraft/nbt/NbtByteArray.mapping b/mappings/net/minecraft/nbt/NbtByteArray.mapping index 9266061986..8ec33732a2 100644 --- a/mappings/net/minecraft/nbt/NbtByteArray.mapping +++ b/mappings/net/minecraft/nbt/NbtByteArray.mapping @@ -1,5 +1,8 @@ CLASS net/minecraft/class_2479 net/minecraft/nbt/NbtByteArray - COMMENT Represents an NBT byte array. + COMMENT Represents an NBT byte array. This object is mutable and backed by {@code byte[]}. + COMMENT Its type is {@value NbtElement#BYTE_ARRAY_TYPE}. Like Java arrays, accessing + COMMENT indices that are out of bounds will throw {@link ArrayIndexOutOfBoundsException}. + COMMENT The backing array can be obtained via {@link #getByteArray()}. FIELD field_11493 value [B FIELD field_21024 TYPE Lnet/minecraft/class_4614; FIELD field_33188 SIZE I @@ -12,5 +15,9 @@ CLASS net/minecraft/class_2479 net/minecraft/nbt/NbtByteArray METHOD get (I)Ljava/lang/Object; ARG 1 index METHOD method_10521 getByteArray ()[B + COMMENT {@return the underlying byte array} + COMMENT + COMMENT @apiNote This does not copy the array, so modifications to the returned array + COMMENT also apply to this NBT byte array. METHOD method_10522 toArray (Ljava/util/List;)[B ARG 0 list diff --git a/mappings/net/minecraft/nbt/NbtCompound.mapping b/mappings/net/minecraft/nbt/NbtCompound.mapping index baada838a5..877b3562aa 100644 --- a/mappings/net/minecraft/nbt/NbtCompound.mapping +++ b/mappings/net/minecraft/nbt/NbtCompound.mapping @@ -1,5 +1,19 @@ CLASS net/minecraft/class_2487 net/minecraft/nbt/NbtCompound - COMMENT Represents an NBT compound object which holds unordered key-value pairs with distinct case-sensitive string keys. + COMMENT Represents an NBT compound object. This mutable object holds unordered key-value pairs + COMMENT with distinct case-sensitive string keys. This can effectively be used like a + COMMENT {@code HashMap}. Note that this does not implement + COMMENT {@link java.util.Map}. Its type is {@value NbtElement#COMPOUND_TYPE}. To get the compound + COMMENT as a map, use {@link #toMap()}. + COMMENT + COMMENT

There are two ways to use this compound; one is to create NBT instances yourself and use + COMMENT {@link #get(String)} or {@link #put(String, NbtElement)}. Manual casting is required in + COMMENT this case. The other, easier way is to use methods with type names, such as + COMMENT {@link #getInt(String)} or {@link #putInt(String, int)}. Where applicable, these methods + COMMENT return and accept Java types (e.g. {@code int}, {@code long[]}) instead of {@link NbtElement} + COMMENT subclasses. Note that there is no {@code putCompound} method, since you can just use the + COMMENT put method. These getters also have the advantage of providing type safety, because if + COMMENT type mismatch occurs or there is no such element in the compound, it returns the default + COMMENT value for that type instead of throwing or returning {@code null}. FIELD field_11515 entries Ljava/util/Map; FIELD field_21029 TYPE Lnet/minecraft/class_4614; FIELD field_25128 CODEC Lcom/mojang/serialization/Codec; @@ -9,11 +23,26 @@ CLASS net/minecraft/class_2487 net/minecraft/nbt/NbtCompound METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_10537 getLong (Ljava/lang/String;)J + COMMENT {@return the {@code long} associated with {@code key}, or {@code 0L} if there is no number + COMMENT stored with the key} + COMMENT + COMMENT

If a non-long numeric value is stored, this will cast the value. + COMMENT + COMMENT @see #putLong(String, long) + COMMENT @see AbstractNbtNumber#longValue() ARG 1 key METHOD method_10538 putLongArray (Ljava/lang/String;Ljava/util/List;)V + COMMENT Puts a list of longs to this compound. This copies the list. + COMMENT + COMMENT @see #getLongArray(String) + COMMENT @see #putLongArray(String, long[]) ARG 1 key ARG 2 value METHOD method_10539 putIntArray (Ljava/lang/String;[I)V + COMMENT Puts an int array to this compound. This does not copy the array. + COMMENT + COMMENT @see #getIntArray(String) + COMMENT @see #putIntArray(String, List) ARG 1 key ARG 2 value METHOD method_10540 getType (Ljava/lang/String;)B @@ -22,12 +51,21 @@ CLASS net/minecraft/class_2487 net/minecraft/nbt/NbtCompound COMMENT @return the element NBT type, or {@link NbtElement#END_TYPE} if it does not exist ARG 1 key METHOD method_10541 getKeys ()Ljava/util/Set; + COMMENT {@return the set of keys in this compound} METHOD method_10542 readByte (Ljava/io/DataInput;Lnet/minecraft/class_2505;)B ARG 0 input ARG 1 tracker METHOD method_10543 copyFrom (Lnet/minecraft/class_2487;)Lnet/minecraft/class_2487; + COMMENT Merges the entries of {@code source} to this compound. The passed compound will not + COMMENT be modified. If both compounds contain a compound with the same key, they will be + COMMENT merged; otherwise the values of this compound will be overwritten. + COMMENT + COMMENT @return this compound with entries merged ARG 1 source METHOD method_10544 putLong (Ljava/lang/String;J)V + COMMENT Puts a {@code long} to this compound. + COMMENT + COMMENT @see #getLong(String) ARG 1 key ARG 2 value METHOD method_10545 contains (Ljava/lang/String;)Z @@ -36,63 +74,152 @@ CLASS net/minecraft/class_2487 net/minecraft/nbt/NbtCompound COMMENT @return {@code true} if the key exists, else {@code false} ARG 1 key METHOD method_10546 getSize ()I + COMMENT {@return the size of this compound} METHOD method_10547 getByteArray (Ljava/lang/String;)[B + COMMENT {@return the byte array associated with {@code key}, or an empty byte array if there is no + COMMENT byte array stored with the key} + COMMENT + COMMENT @apiNote Modifying the returned array also modifies the NBT byte array. + COMMENT + COMMENT @see #putByteArray(String, byte[]) + COMMENT @see NbtByteArray#getByteArray() ARG 1 key METHOD method_10548 putFloat (Ljava/lang/String;F)V + COMMENT Puts a {@code float} to this compound. + COMMENT + COMMENT @see #getFloat(String) ARG 1 key ARG 2 value METHOD method_10549 putDouble (Ljava/lang/String;D)V + COMMENT Puts a {@code double} to this compound. + COMMENT + COMMENT @see #getDouble(String) ARG 1 key ARG 2 value METHOD method_10550 getInt (Ljava/lang/String;)I + COMMENT {@return the {@code int} associated with {@code key}, or {@code 0} if there is no number + COMMENT stored with the key} + COMMENT + COMMENT

If a non-integer numeric value is stored, this will cast the value. + COMMENT + COMMENT @see #putInt(String, int) + COMMENT @see AbstractNbtNumber#intValue() ARG 1 key METHOD method_10551 remove (Ljava/lang/String;)V + COMMENT Removes the entry with the specified {@code key}. Does nothing if there is none. ARG 1 key METHOD method_10552 readString (Ljava/io/DataInput;Lnet/minecraft/class_2505;)Ljava/lang/String; ARG 0 input ARG 1 tracker METHOD method_10554 getList (Ljava/lang/String;I)Lnet/minecraft/class_2499; + COMMENT {@return the list associated with {@code key}, or an empty list if there is no + COMMENT list stored with the key and the type} + COMMENT + COMMENT @see #put(String, NbtElement) ARG 1 key ARG 2 type + COMMENT the expected held type of the list METHOD method_10555 write (Ljava/lang/String;Lnet/minecraft/class_2520;Ljava/io/DataOutput;)V ARG 0 key ARG 1 element ARG 2 output METHOD method_10556 putBoolean (Ljava/lang/String;Z)V + COMMENT Puts a {@code boolean} to this compound. The value is stored as {@link NbtByte}. + COMMENT + COMMENT @see #getBoolean(String) ARG 1 key ARG 2 value METHOD method_10558 getString (Ljava/lang/String;)Ljava/lang/String; + COMMENT {@return the {@link String} associated with {@code key}, or an empty string if there is no + COMMENT string stored with the key} + COMMENT + COMMENT @see #putString(String, String) + COMMENT @see NbtElement#asString() ARG 1 key METHOD method_10559 createCrashReport (Ljava/lang/String;Lnet/minecraft/class_4614;Ljava/lang/ClassCastException;)Lnet/minecraft/class_128; ARG 1 key ARG 2 reader ARG 3 exception METHOD method_10561 getIntArray (Ljava/lang/String;)[I + COMMENT {@return the int array associated with {@code key}, or an empty int array if there is no + COMMENT int array stored with the key} + COMMENT + COMMENT @apiNote Modifying the returned array also modifies the NBT int array. + COMMENT + COMMENT @see #putIntArray(String, int[]) + COMMENT @see NbtIntArray#getIntArray() ARG 1 key METHOD method_10562 getCompound (Ljava/lang/String;)Lnet/minecraft/class_2487; + COMMENT {@return the compound associated with {@code key}, or an empty compound if there is no + COMMENT compound stored with the key} + COMMENT + COMMENT @see #put(String, NbtElement) ARG 1 key METHOD method_10564 putLongArray (Ljava/lang/String;[J)V + COMMENT Puts a long array to this compound. This does not copy the array. + COMMENT + COMMENT @see #getLongArray(String) + COMMENT @see #putLongArray(String, List) ARG 1 key ARG 2 value METHOD method_10565 getLongArray (Ljava/lang/String;)[J + COMMENT {@return the long array associated with {@code key}, or an empty long array if there is no + COMMENT long array stored with the key} + COMMENT + COMMENT @apiNote Modifying the returned array also modifies the NBT long array. + COMMENT + COMMENT @see #putLongArray(String, long[]) + COMMENT @see NbtLongArray#getLongArray() ARG 1 key METHOD method_10566 put (Ljava/lang/String;Lnet/minecraft/class_2520;)Lnet/minecraft/class_2520; + COMMENT Puts an element to this compound. + COMMENT + COMMENT @return the previous value, or {@code null} if there was none + COMMENT @see #get(String) ARG 1 key ARG 2 element METHOD method_10567 putByte (Ljava/lang/String;B)V + COMMENT Puts a {@code byte} to this compound. + COMMENT + COMMENT @see #getByte(String) ARG 1 key ARG 2 value METHOD method_10568 getShort (Ljava/lang/String;)S + COMMENT {@return the {@code short} associated with {@code key}, or {@code 0} if there is no number + COMMENT stored with the key} + COMMENT + COMMENT

If a non-short numeric value is stored, this will cast the value. + COMMENT + COMMENT @see #putShort(String, short) + COMMENT @see AbstractNbtNumber#shortValue() ARG 1 key METHOD method_10569 putInt (Ljava/lang/String;I)V + COMMENT Puts an {@code int} to this compound. + COMMENT + COMMENT @see #getInt(String) ARG 1 key ARG 2 value METHOD method_10570 putByteArray (Ljava/lang/String;[B)V + COMMENT Puts a byte array to this compound. This does not copy the array. + COMMENT + COMMENT @see #getByteArray(String) + COMMENT @see #putByteArray(String, List) ARG 1 key ARG 2 value METHOD method_10571 getByte (Ljava/lang/String;)B + COMMENT {@return the {@code byte} associated with {@code key}, or {@code 0} if there is no number + COMMENT stored with the key} + COMMENT + COMMENT

If a non-byte numeric value is stored, this will cast the value. + COMMENT + COMMENT @see #putByte(String, byte) + COMMENT @see AbstractNbtNumber#byteValue() ARG 1 key METHOD method_10572 putIntArray (Ljava/lang/String;Ljava/util/List;)V + COMMENT Puts a list of integers to this compound. This copies the list. + COMMENT + COMMENT @see #getIntArray(String) + COMMENT @see #putIntArray(String, int[]) ARG 1 key ARG 2 value METHOD method_10573 contains (Ljava/lang/String;I)Z @@ -104,13 +231,38 @@ CLASS net/minecraft/class_2487 net/minecraft/nbt/NbtCompound ARG 1 key ARG 2 type METHOD method_10574 getDouble (Ljava/lang/String;)D + COMMENT {@return the {@code double} associated with {@code key}, or {@code 0.0} if there is + COMMENT no number stored with the key} + COMMENT + COMMENT

If a non-double numeric value is stored, this will cast the value. + COMMENT + COMMENT @see #putDouble(String, double) + COMMENT @see AbstractNbtNumber#doubleValue() ARG 1 key METHOD method_10575 putShort (Ljava/lang/String;S)V + COMMENT Puts a {@code short} to this compound. + COMMENT + COMMENT @see #getShort(String) ARG 1 key ARG 2 value METHOD method_10577 getBoolean (Ljava/lang/String;)Z + COMMENT {@return the boolean value stored with the {@code key}} + COMMENT + COMMENT @implNote Since NBT does not have a boolean type, {@link NbtByte} is used instead. This + COMMENT method returns {@code true} for any values which, after casting to {@code byte} as + COMMENT described at {@link #getByte(String)}, is not {@code 0}. Since all non-numeric values + COMMENT become {@code 0} during casting to bytes, this method returns {@code false} for those + COMMENT as well. This includes values often considered truthy in other languages, such as a + COMMENT non-empty string or list. ARG 1 key METHOD method_10580 get (Ljava/lang/String;)Lnet/minecraft/class_2520; + COMMENT {@return the element associated with the key from this compound, or + COMMENT {@code null} if there is none} + COMMENT + COMMENT @apiNote This method does not provide type safety; if the type is known, it is + COMMENT recommended to use other type-specific methods instead. + COMMENT + COMMENT @see #put(String, NbtElement) ARG 1 key METHOD method_10581 read (Lnet/minecraft/class_4614;Ljava/lang/String;Ljava/io/DataInput;ILnet/minecraft/class_2505;)Lnet/minecraft/class_2520; ARG 0 reader @@ -119,15 +271,40 @@ CLASS net/minecraft/class_2487 net/minecraft/nbt/NbtCompound ARG 3 depth ARG 4 tracker METHOD method_10582 putString (Ljava/lang/String;Ljava/lang/String;)V + COMMENT Puts a {@link String} to this compound. + COMMENT + COMMENT @see #getString(String) ARG 1 key ARG 2 value METHOD method_10583 getFloat (Ljava/lang/String;)F + COMMENT {@return the {@code float} associated with {@code key}, or {@code 0.0f} if there is + COMMENT no number stored with the key} + COMMENT + COMMENT

If a non-float numeric value is stored, this will cast the value. + COMMENT + COMMENT @see #putFloat(String, float) + COMMENT @see AbstractNbtNumber#floatValue() ARG 1 key METHOD method_25926 getUuid (Ljava/lang/String;)Ljava/util/UUID; - COMMENT Reads a {@link UUID} from its NBT representation in this {@code NbtCompound}. + COMMENT {@return a {@link UUID} from its NBT representation in this compound} + COMMENT + COMMENT @apiNote Unlike other specialized getters, this method can throw unchecked exceptions. + COMMENT It is therefore recommended to call {@link #containsUuid(String)} before getting the + COMMENT UUID. + COMMENT + COMMENT @throws IllegalArgumentException if there is no value with the key or the value + COMMENT associated with the key is not a valid + COMMENT NBT representation of a UUID + COMMENT @see NbtHelper#toUuid(NbtIntArray) + COMMENT @see #containsUuid(String) + COMMENT @see #putUuid(String, UUID) ARG 1 key METHOD method_25927 putUuid (Ljava/lang/String;Ljava/util/UUID;)V - COMMENT Writes a {@link UUID} to its NBT representation in this {@code NbtCompound}. + COMMENT Puts a {@link UUID}'s NBT representation to this compound. + COMMENT + COMMENT @see NbtHelper#fromUuid(UUID) + COMMENT @see #containsUuid(String) + COMMENT @see #getUuid(String) ARG 1 key ARG 2 value METHOD method_25928 containsUuid (Ljava/lang/String;)Z @@ -137,7 +314,15 @@ CLASS net/minecraft/class_2487 net/minecraft/nbt/NbtCompound METHOD method_29142 (Lnet/minecraft/class_2487;)Lcom/mojang/serialization/Dynamic; ARG 0 nbt METHOD method_29143 toMap ()Ljava/util/Map; + COMMENT {@return the compound as an unmodifiable map} + COMMENT + COMMENT

Changes to this compound will be propagated to the returned map. METHOD method_33133 isEmpty ()Z + COMMENT {@return whether the compound has no entries} METHOD method_36110 putByteArray (Ljava/lang/String;Ljava/util/List;)V + COMMENT Puts a list of bytes to this compound. This copies the list. + COMMENT + COMMENT @see #getByteArray(String) + COMMENT @see #putByteArray(String, byte[]) ARG 1 key ARG 2 value diff --git a/mappings/net/minecraft/nbt/NbtDouble.mapping b/mappings/net/minecraft/nbt/NbtDouble.mapping index ff005044cf..fa2fa8c7d7 100644 --- a/mappings/net/minecraft/nbt/NbtDouble.mapping +++ b/mappings/net/minecraft/nbt/NbtDouble.mapping @@ -1,7 +1,9 @@ CLASS net/minecraft/class_2489 net/minecraft/nbt/NbtDouble - COMMENT Represents an NBT 64-bit floating-point number. + COMMENT Represents an NBT 64-bit floating-point number. Its type is {@value NbtElement#DOUBLE_TYPE}. + COMMENT Instances are immutable. FIELD field_11520 value D FIELD field_21030 ZERO Lnet/minecraft/class_2489; + COMMENT The NBT double representing {@code 0.0}. FIELD field_21031 TYPE Lnet/minecraft/class_4614; FIELD field_33192 SIZE I METHOD (D)V @@ -9,4 +11,5 @@ CLASS net/minecraft/class_2489 net/minecraft/nbt/NbtDouble METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_23241 of (D)Lnet/minecraft/class_2489; + COMMENT {@return the NBT double from {@code value}} ARG 0 value diff --git a/mappings/net/minecraft/nbt/NbtElement.mapping b/mappings/net/minecraft/nbt/NbtElement.mapping index c17bc2bed4..e3655c7db7 100644 --- a/mappings/net/minecraft/nbt/NbtElement.mapping +++ b/mappings/net/minecraft/nbt/NbtElement.mapping @@ -59,20 +59,24 @@ CLASS net/minecraft/class_2520 net/minecraft/nbt/NbtElement COMMENT @see NbtCompound#contains(String, int) FIELD field_33264 MAX_DEPTH I METHOD method_10707 copy ()Lnet/minecraft/class_2520; - COMMENT Copies this NBT element. - COMMENT - COMMENT @return the copied element + COMMENT {@return an NBT element of equal value that won't change with this element} METHOD method_10711 getType ()B - COMMENT Gets the type of this NBT element. - COMMENT - COMMENT @return the type + COMMENT {@return the type of this NBT element} METHOD method_10713 write (Ljava/io/DataOutput;)V + COMMENT Writes the NBT element to {@code output}. + COMMENT + COMMENT @apiNote This is a low-level method for serializing NBT elements; consider using + COMMENT {@link NbtIo}, {@link NbtOps}, or {@link net.minecraft.network.PacketByteBuf#writeNbt} + COMMENT instead. ARG 1 output METHOD method_10714 asString ()Ljava/lang/String; - METHOD method_23258 getNbtType ()Lnet/minecraft/class_4614; - COMMENT Gets the NBT type definition of this NBT element. + COMMENT {@return the NBT's string representation} COMMENT - COMMENT @return the element type definition + COMMENT @implNote By default, this returns the same result as {@link + COMMENT net.minecraft.nbt.visitor.StringNbtWriter}. {@link NbtString} will return its + COMMENT string value instead. + METHOD method_23258 getNbtType ()Lnet/minecraft/class_4614; + COMMENT {@return the NBT type definition of this NBT element} METHOD method_32289 accept (Lnet/minecraft/class_5627;)V ARG 1 visitor METHOD method_39850 doAccept (Lnet/minecraft/class_6836;)Lnet/minecraft/class_6836$class_6838; diff --git a/mappings/net/minecraft/nbt/NbtFloat.mapping b/mappings/net/minecraft/nbt/NbtFloat.mapping index 13a36996f9..7a5e9c4883 100644 --- a/mappings/net/minecraft/nbt/NbtFloat.mapping +++ b/mappings/net/minecraft/nbt/NbtFloat.mapping @@ -1,7 +1,9 @@ CLASS net/minecraft/class_2494 net/minecraft/nbt/NbtFloat - COMMENT Represents an NBT 32-bit floating-point number. + COMMENT Represents an NBT 32-bit floating-point number. Its type is {@value NbtElement#FLOAT_TYPE}. + COMMENT Instances are immutable. FIELD field_11523 value F FIELD field_21034 ZERO Lnet/minecraft/class_2494; + COMMENT The NBT float representing {@code 0.0f}. FIELD field_21035 TYPE Lnet/minecraft/class_4614; FIELD field_33194 SIZE I METHOD (F)V @@ -9,4 +11,5 @@ CLASS net/minecraft/class_2494 net/minecraft/nbt/NbtFloat METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_23244 of (F)Lnet/minecraft/class_2494; + COMMENT {@return the NBT float from {@code value}} ARG 0 value diff --git a/mappings/net/minecraft/nbt/NbtHelper.mapping b/mappings/net/minecraft/nbt/NbtHelper.mapping index 6518aec856..595d214486 100644 --- a/mappings/net/minecraft/nbt/NbtHelper.mapping +++ b/mappings/net/minecraft/nbt/NbtHelper.mapping @@ -1,4 +1,5 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper + COMMENT Helper methods for handling NBT. FIELD field_11582 LOGGER Lorg/slf4j/Logger; FIELD field_27816 BLOCK_POS_COMPARATOR Ljava/util/Comparator; FIELD field_27817 ENTITY_POS_COMPARATOR Ljava/util/Comparator; @@ -10,7 +11,13 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper FIELD field_33227 COMMA Ljava/lang/String; FIELD field_33228 COLON C METHOD method_10681 toBlockState (Lnet/minecraft/class_2487;)Lnet/minecraft/class_2680; - ARG 0 compound + COMMENT {@return the block state from the {@code nbt}} + COMMENT + COMMENT

This returns the default state for {@link net.minecraft.block.Blocks#AIR} + COMMENT if the block name is not present. + COMMENT + COMMENT @see #fromBlockState(BlockState) + ARG 0 nbt METHOD method_10682 withProperty (Lnet/minecraft/class_2688;Lnet/minecraft/class_2769;Ljava/lang/String;Lnet/minecraft/class_2487;Lnet/minecraft/class_2487;)Lnet/minecraft/class_2688; ARG 0 state ARG 1 property @@ -18,19 +25,51 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper ARG 3 properties ARG 4 root METHOD method_10683 toGameProfile (Lnet/minecraft/class_2487;)Lcom/mojang/authlib/GameProfile; - ARG 0 compound + COMMENT {@return the game profile converted from {@code nbt}} + COMMENT + COMMENT @see #writeGameProfile(NbtCompound, GameProfile) + ARG 0 nbt METHOD method_10684 writeGameProfile (Lnet/minecraft/class_2487;Lcom/mojang/authlib/GameProfile;)Lnet/minecraft/class_2487; - ARG 0 compound + COMMENT Writes the game profile to {@code nbt}. This modifies the passed compound. + COMMENT + COMMENT @return the compound with the serialized game profile + COMMENT @see #toGameProfile(NbtCompound) + ARG 0 nbt ARG 1 profile METHOD method_10685 nameValue (Lnet/minecraft/class_2769;Ljava/lang/Comparable;)Ljava/lang/String; ARG 0 property ARG 1 value METHOD method_10686 fromBlockState (Lnet/minecraft/class_2680;)Lnet/minecraft/class_2487; + COMMENT {@return the serialized block state} + COMMENT + COMMENT @see #toBlockState(NbtCompound) ARG 0 state METHOD method_10687 matches (Lnet/minecraft/class_2520;Lnet/minecraft/class_2520;Z)Z + COMMENT {@return whether {@code standard} is a subset of {@code subject}} + COMMENT + COMMENT

Elements are matched based on the following order: + COMMENT

    + COMMENT
  1. Passing the same reference to both parameters will return {@code true}.
    2. + COMMENT
  2. If {@code standard} is {@code null}, return {@code true}.
    3. + COMMENT
  3. If {@code subject} is {@code null}, return {@code false}.
    4. + COMMENT
  4. If the types of {@code standard} and {@code subject} are different, + COMMENT return {@code false}.
    5. + COMMENT
  5. If {@code standard} is {@link NbtCompound}, return {@code true} if all keys + COMMENT in the {@code standard} exist in {@code subject} and the values match (comparing + COMMENT recursively.)
    6. + COMMENT
  6. If {@code standard} is {@link NbtList} and {@code ignoreListOrder} is {@code true}, + COMMENT return {@code true} if both lists are empty, or if there exists a "matching" value + COMMENT in {@code subject} for all values of {@code standard} (that is, if {@code standard} + COMMENT is a subset of {@code subject}, ignoring duplicates.), otherwise {@code false}. + COMMENT This means that the comparison ignores the ordering of the lists.
    7. + COMMENT
  7. Otherwise, return {@code standard.equals(subject)}.
    8. + COMMENT
ARG 0 standard + COMMENT the standard (also called as "template" or "schema") element ARG 1 subject - ARG 2 equalValue + COMMENT the element to test + ARG 2 ignoreListOrder + COMMENT whether to ignore ordering for {@link NbtList} METHOD method_10688 update (Lcom/mojang/datafixers/DataFixer;Lnet/minecraft/class_4284;Lnet/minecraft/class_2487;I)Lnet/minecraft/class_2487; COMMENT Uses the data fixer to update an NBT compound object to the latest data version. ARG 0 fixer @@ -42,8 +81,14 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper ARG 3 oldVersion COMMENT the data version of the NBT compound object METHOD method_10691 toBlockPos (Lnet/minecraft/class_2487;)Lnet/minecraft/class_2338; - ARG 0 compound + COMMENT {@return the block position from the {@code nbt}} + COMMENT + COMMENT @see #fromBlockPos(BlockPos) + ARG 0 nbt METHOD method_10692 fromBlockPos (Lnet/minecraft/class_2338;)Lnet/minecraft/class_2487; + COMMENT {@return the serialized block position} + COMMENT + COMMENT @see #toBlockPos(NbtCompound) ARG 0 pos METHOD method_10693 update (Lcom/mojang/datafixers/DataFixer;Lnet/minecraft/class_4284;Lnet/minecraft/class_2487;II)Lnet/minecraft/class_2487; COMMENT Uses the data fixer to update an NBT compound object. @@ -61,6 +106,7 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper COMMENT Serializes a {@link UUID} into its equivalent NBT representation. COMMENT COMMENT @since 20w10a + COMMENT @see #toUuid(NbtElement) ARG 0 uuid METHOD method_25930 toUuid (Lnet/minecraft/class_2520;)Ljava/util/UUID; COMMENT Deserializes an NBT element into a {@link UUID}. @@ -68,6 +114,7 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper COMMENT COMMENT @throws IllegalArgumentException if {@code element} is not a valid representation of a UUID COMMENT @since 20w10a + COMMENT @see #fromUuid(UUID) ARG 0 element METHOD method_32260 fromNbtProviderString (Ljava/lang/String;)Lnet/minecraft/class_2487; COMMENT {@return the {@code string} parsed as an NBT provider-formatted @@ -99,6 +146,9 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper METHOD method_32269 (Lnet/minecraft/class_2499;)D ARG 0 nbt METHOD method_32270 toPrettyPrintedText (Lnet/minecraft/class_2520;)Lnet/minecraft/class_2561; + COMMENT {@return the pretty-printed text representation of {@code element}} + COMMENT + COMMENT @see net.minecraft.nbt.visitor.NbtTextFormatter ARG 0 element METHOD method_32271 toNbtProviderString (Lnet/minecraft/class_2487;)Ljava/lang/String; COMMENT {@return the string representation of {@code compound} as used @@ -133,6 +183,7 @@ CLASS net/minecraft/class_2512 net/minecraft/nbt/NbtHelper ARG 0 depth ARG 1 stringBuilder METHOD method_36115 fromFluidState (Lnet/minecraft/class_3610;)Lnet/minecraft/class_2487; + COMMENT {@return the serialized fluid state} ARG 0 state METHOD method_36116 appendFormattedString (Ljava/lang/StringBuilder;Lnet/minecraft/class_2520;IZ)Ljava/lang/StringBuilder; ARG 0 stringBuilder diff --git a/mappings/net/minecraft/nbt/NbtInt.mapping b/mappings/net/minecraft/nbt/NbtInt.mapping index 1dc220d523..bc1fd32377 100644 --- a/mappings/net/minecraft/nbt/NbtInt.mapping +++ b/mappings/net/minecraft/nbt/NbtInt.mapping @@ -1,5 +1,6 @@ CLASS net/minecraft/class_2497 net/minecraft/nbt/NbtInt - COMMENT Represents an NBT 32-bit integer. + COMMENT Represents an NBT 32-bit integer. Its type is {@value NbtElement#INT_TYPE}. + COMMENT Instances are immutable. FIELD field_11525 value I FIELD field_21037 TYPE Lnet/minecraft/class_4614; FIELD field_33196 SIZE I @@ -8,6 +9,7 @@ CLASS net/minecraft/class_2497 net/minecraft/nbt/NbtInt METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_23247 of (I)Lnet/minecraft/class_2497; + COMMENT {@return the NBT integer from {@code value}} ARG 0 value CLASS class_4611 Cache FIELD field_21038 VALUES [Lnet/minecraft/class_2497; diff --git a/mappings/net/minecraft/nbt/NbtIntArray.mapping b/mappings/net/minecraft/nbt/NbtIntArray.mapping index 65524a99b0..4d18a3690b 100644 --- a/mappings/net/minecraft/nbt/NbtIntArray.mapping +++ b/mappings/net/minecraft/nbt/NbtIntArray.mapping @@ -1,5 +1,8 @@ CLASS net/minecraft/class_2495 net/minecraft/nbt/NbtIntArray - COMMENT Represents an NBT 32-bit integer array. + COMMENT Represents an NBT 32-bit integer array. This object is mutable and backed by + COMMENT {@code int[]}. Its type is {@value NbtElement#INT_ARRAY_TYPE}. Like Java arrays, + COMMENT accessing indices that are out of bounds will throw {@link ArrayIndexOutOfBoundsException}. + COMMENT The backing array can be obtained via {@link #getIntArray()}. FIELD field_11524 value [I FIELD field_21036 TYPE Lnet/minecraft/class_4614; FIELD field_33195 SIZE I @@ -12,5 +15,9 @@ CLASS net/minecraft/class_2495 net/minecraft/nbt/NbtIntArray METHOD get (I)Ljava/lang/Object; ARG 1 index METHOD method_10588 getIntArray ()[I + COMMENT {@return the underlying int array} + COMMENT + COMMENT @apiNote This does not copy the array, so modifications to the returned array + COMMENT also apply to this NBT int array. METHOD method_10590 toArray (Ljava/util/List;)[I ARG 0 list diff --git a/mappings/net/minecraft/nbt/NbtIo.mapping b/mappings/net/minecraft/nbt/NbtIo.mapping index 54c0557498..e21c5e515a 100644 --- a/mappings/net/minecraft/nbt/NbtIo.mapping +++ b/mappings/net/minecraft/nbt/NbtIo.mapping @@ -1,5 +1,11 @@ CLASS net/minecraft/class_2507 net/minecraft/nbt/NbtIo + COMMENT A set of utility functions for reading, writing, and scanning NBT files. METHOD method_10625 read (Ljava/io/DataInput;Lnet/minecraft/class_2505;)Lnet/minecraft/class_2487; + COMMENT Reads an NBT compound from {@code input}. + COMMENT + COMMENT @return the NBT compound from the input + COMMENT @throws IOException if the IO operation fails or if the root NBT element is + COMMENT not a compound ARG 0 input ARG 1 tracker METHOD method_10626 read (Ljava/io/DataInput;ILnet/minecraft/class_2505;)Lnet/minecraft/class_2520; @@ -7,29 +13,74 @@ CLASS net/minecraft/class_2507 net/minecraft/nbt/NbtIo ARG 1 depth ARG 2 tracker METHOD method_10627 read (Ljava/io/DataInput;)Lnet/minecraft/class_2487; + COMMENT Reads an NBT compound from {@code input}. + COMMENT + COMMENT @return the NBT compound from the input + COMMENT @throws IOException if the IO operation fails or if the root NBT element is + COMMENT not a compound ARG 0 input METHOD method_10628 write (Lnet/minecraft/class_2487;Ljava/io/DataOutput;)V - ARG 0 compound + COMMENT Writes the {@code nbt} to {@code file}. + COMMENT + COMMENT @throws IOException if the IO operation fails + COMMENT @see #write(NbtCompound, File) + ARG 0 nbt ARG 1 output METHOD method_10629 readCompressed (Ljava/io/InputStream;)Lnet/minecraft/class_2487; + COMMENT Reads an NBT compound from Gzip-compressed {@code stream}. + COMMENT + COMMENT @return the NBT compound from the stream + COMMENT @throws IOException if the IO operation fails or if the root NBT element is + COMMENT not a compound + COMMENT @see #readCompressed(File) ARG 0 stream METHOD method_10630 write (Lnet/minecraft/class_2487;Ljava/io/File;)V - ARG 0 compound + COMMENT Writes the {@code nbt} to {@code file}. + COMMENT + COMMENT @throws IOException if the IO operation fails + COMMENT @see #write(NbtCompound, DataOutput) + ARG 0 nbt ARG 1 file METHOD method_10631 write (Lnet/minecraft/class_2520;Ljava/io/DataOutput;)V - ARG 0 element + ARG 0 nbt ARG 1 output METHOD method_10633 read (Ljava/io/File;)Lnet/minecraft/class_2487; + COMMENT Reads an NBT compound from {@code file}. + COMMENT + COMMENT @return the NBT compound from the file, or {@code null} if the file does not exist + COMMENT @throws IOException if the IO operation fails or if the root NBT element is + COMMENT not a compound ARG 0 file METHOD method_10634 writeCompressed (Lnet/minecraft/class_2487;Ljava/io/OutputStream;)V - ARG 0 compound + COMMENT Writes the Gzip-compressed {@code nbt} to {@code stream}. + COMMENT + COMMENT @throws IOException if the IO operation fails + COMMENT @see #writeCompressed(NbtCompound, File) + ARG 0 nbt ARG 1 stream METHOD method_30613 readCompressed (Ljava/io/File;)Lnet/minecraft/class_2487; + COMMENT Reads an NBT compound from Gzip-compressed {@code file}. + COMMENT + COMMENT @return the NBT compound from the file + COMMENT @throws IOException if the IO operation fails or if the root NBT element is + COMMENT not a compound + COMMENT @see #readCompressed(InputStream) ARG 0 file METHOD method_30614 writeCompressed (Lnet/minecraft/class_2487;Ljava/io/File;)V - ARG 0 compound + COMMENT Writes the Gzip-compressed {@code nbt} to {@code file}. + COMMENT + COMMENT @throws IOException if the IO operation fails + COMMENT @see #writeCompressed(NbtCompound, OutputStream) + ARG 0 nbt ARG 1 file METHOD method_39855 scan (Ljava/io/DataInput;Lnet/minecraft/class_6836;)V + COMMENT Scans the NBT input using {@code scanner}. + COMMENT + COMMENT @apiNote This method does not return the scan result; the user is expected + COMMENT to call the appropriate method of the {@link NbtScanner} subclasses, such as + COMMENT {@link net.minecraft.nbt.scanner.NbtCollector#getRoot()}. + COMMENT + COMMENT @throws IOException if the IO operation fails ARG 0 input ARG 1 scanner METHOD method_40057 scanCompressed (Ljava/io/File;Lnet/minecraft/class_6836;)V @@ -39,6 +90,7 @@ CLASS net/minecraft/class_2507 net/minecraft/nbt/NbtIo COMMENT to call the appropriate method of the {@link NbtScanner} subclasses, such as COMMENT {@link net.minecraft.nbt.scanner.NbtCollector#getRoot()}. COMMENT + COMMENT @throws IOException if the IO operation fails COMMENT @see #scanCompressed(InputStream, NbtScanner) ARG 0 file ARG 1 scanner @@ -49,6 +101,7 @@ CLASS net/minecraft/class_2507 net/minecraft/nbt/NbtIo COMMENT to call the appropriate method of the {@link NbtScanner} subclasses, such as COMMENT {@link net.minecraft.nbt.scanner.NbtCollector#getRoot()}. COMMENT + COMMENT @throws IOException if the IO operation fails COMMENT @see #scanCompressed(File, NbtScanner) ARG 0 stream ARG 1 scanner diff --git a/mappings/net/minecraft/nbt/NbtList.mapping b/mappings/net/minecraft/nbt/NbtList.mapping index 49bd9c0476..56ee658584 100644 --- a/mappings/net/minecraft/nbt/NbtList.mapping +++ b/mappings/net/minecraft/nbt/NbtList.mapping @@ -1,9 +1,19 @@ CLASS net/minecraft/class_2499 net/minecraft/nbt/NbtList - COMMENT Represents an NBT list. + COMMENT Represents a mutable NBT list. Its type is {@value NbtElement#LIST_TYPE}. COMMENT

COMMENT An NBT list holds values of the same {@linkplain NbtElement#getType NBT type}. COMMENT The {@linkplain AbstractNbtList#getHeldType NBT type} of an NBT list is determined - COMMENT once its first element is inserted; empty NBT lists return {@link NbtElement#END_TYPE} as their held {@linkplain AbstractNbtList#getHeldType NBT type}. + COMMENT once its first element is inserted; empty NBT lists return {@link NbtElement#END_TYPE} + COMMENT as their held {@linkplain AbstractNbtList#getHeldType NBT type}. + COMMENT + COMMENT

To get values from this list, use methods with type names, such as + COMMENT {@link #getInt(int)}. Where applicable, these methods return Java types (e.g. {@code int}, + COMMENT {@code long[]}) instead of {@link NbtElement} subclasses. If type mismatch occurs or + COMMENT the index is out of bounds, it returns the default value for that type instead of + COMMENT throwing or returning {@code null}. + COMMENT + COMMENT

Unlike {@link NbtCompound}, there is no Java type-based adder, and numeric value + COMMENT getters will not try to cast the values. FIELD field_11550 value Ljava/util/List; FIELD field_11551 type B FIELD field_21039 TYPE Lnet/minecraft/class_4614; @@ -16,23 +26,47 @@ CLASS net/minecraft/class_2499 net/minecraft/nbt/NbtList METHOD get (I)Ljava/lang/Object; ARG 1 index METHOD method_10600 getInt (I)I + COMMENT {@return the integer at {@code index}, or {@code 0} if the index is out of bounds + COMMENT or if this is not a list of integers} ARG 1 index METHOD method_10602 getCompound (I)Lnet/minecraft/class_2487; + COMMENT {@return the compound at {@code index}, or an empty compound if the index is out + COMMENT of bounds or if this is not a list of compounds} ARG 1 index METHOD method_10603 getList (I)Lnet/minecraft/class_2499; + COMMENT {@return the list at {@code index}, or an empty list if the index is out + COMMENT of bounds or if this is not a list of lists} ARG 1 index METHOD method_10604 getFloat (I)F + COMMENT {@return the float at {@code index}, or {@code 0.0f} if the index is out of bounds + COMMENT or if this is not a list of floats} ARG 1 index METHOD method_10605 canAdd (Lnet/minecraft/class_2520;)Z ARG 1 element METHOD method_10608 getString (I)Ljava/lang/String; + COMMENT {@return the stringified value at {@code index}, or an empty string if the index + COMMENT is out of bounds} + COMMENT + COMMENT

Unlike other getters, this works with any type, not just {@link NbtString}. ARG 1 index METHOD method_10609 getShort (I)S + COMMENT {@return the short at {@code index}, or {@code 0} if the index is out of bounds + COMMENT or if this is not a list of shorts} ARG 1 index METHOD method_10611 getDouble (I)D + COMMENT {@return the double at {@code index}, or {@code 0.0} if the index is out of bounds + COMMENT or if this is not a list of doubles} ARG 1 index METHOD method_17809 forgetTypeIfEmpty ()V METHOD method_36111 getIntArray (I)[I + COMMENT {@return the int array at {@code index}, or an empty int array if the index is + COMMENT out of bounds or if this is not a list of int arrays} + COMMENT + COMMENT @apiNote Modifying the returned array also modifies the NBT int array. ARG 1 index METHOD method_36112 getLongArray (I)[J + COMMENT {@return the long array at {@code index}, or an empty int array if the index is + COMMENT out of bounds or if this is not a list of long arrays} + COMMENT + COMMENT @apiNote Modifying the returned array also modifies the NBT long array. ARG 1 index diff --git a/mappings/net/minecraft/nbt/NbtLong.mapping b/mappings/net/minecraft/nbt/NbtLong.mapping index ca83b3858d..23e31d3ca4 100644 --- a/mappings/net/minecraft/nbt/NbtLong.mapping +++ b/mappings/net/minecraft/nbt/NbtLong.mapping @@ -1,5 +1,6 @@ CLASS net/minecraft/class_2503 net/minecraft/nbt/NbtLong - COMMENT Represents an NBT 64-bit integer. + COMMENT Represents an NBT 64-bit integer. Its type is {@value NbtElement#LONG_TYPE}. + COMMENT Instances are immutable. FIELD field_11553 value J FIELD field_21041 TYPE Lnet/minecraft/class_4614; FIELD field_33201 SIZE I @@ -8,6 +9,7 @@ CLASS net/minecraft/class_2503 net/minecraft/nbt/NbtLong METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_23251 of (J)Lnet/minecraft/class_2503; + COMMENT {@return the NBT long from {@code value}} ARG 0 value CLASS class_4612 Cache FIELD field_21042 VALUES [Lnet/minecraft/class_2503; diff --git a/mappings/net/minecraft/nbt/NbtLongArray.mapping b/mappings/net/minecraft/nbt/NbtLongArray.mapping index 191bcfa8c9..5c87425cdd 100644 --- a/mappings/net/minecraft/nbt/NbtLongArray.mapping +++ b/mappings/net/minecraft/nbt/NbtLongArray.mapping @@ -1,5 +1,8 @@ CLASS net/minecraft/class_2501 net/minecraft/nbt/NbtLongArray - COMMENT Represents an NBT 64-bit integer array. + COMMENT Represents an NBT 64-bit integer array. This object is mutable and backed by + COMMENT {@code long[]}. Its type is {@value NbtElement#LONG_ARRAY_TYPE}. Like Java arrays, + COMMENT accessing indices that are out of bounds will throw {@link ArrayIndexOutOfBoundsException}. + COMMENT The backing array can be obtained via {@link #getLongArray()}. FIELD field_11552 value [J FIELD field_21040 TYPE Lnet/minecraft/class_4614; FIELD field_33200 SIZE I @@ -14,5 +17,9 @@ CLASS net/minecraft/class_2501 net/minecraft/nbt/NbtLongArray METHOD get (I)Ljava/lang/Object; ARG 1 index METHOD method_10615 getLongArray ()[J + COMMENT {@return the underlying long array} + COMMENT + COMMENT @apiNote This does not copy the array, so modifications to the returned array + COMMENT also apply to this NBT long array. METHOD method_10617 toArray (Ljava/util/List;)[J ARG 0 list diff --git a/mappings/net/minecraft/nbt/NbtShort.mapping b/mappings/net/minecraft/nbt/NbtShort.mapping index 1442925658..a24343549e 100644 --- a/mappings/net/minecraft/nbt/NbtShort.mapping +++ b/mappings/net/minecraft/nbt/NbtShort.mapping @@ -1,5 +1,6 @@ CLASS net/minecraft/class_2516 net/minecraft/nbt/NbtShort - COMMENT Represents an NBT 16-bit integer. + COMMENT Represents an NBT 16-bit integer. Its type is {@value NbtElement#SHORT_TYPE}. + COMMENT Instances are immutable. FIELD field_11588 value S FIELD field_21043 TYPE Lnet/minecraft/class_4614; FIELD field_33231 SIZE I @@ -8,6 +9,7 @@ CLASS net/minecraft/class_2516 net/minecraft/nbt/NbtShort METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_23254 of (S)Lnet/minecraft/class_2516; + COMMENT {@return the NBT short from {@code value}} ARG 0 value CLASS class_4613 Cache FIELD field_21044 VALUES [Lnet/minecraft/class_2516; diff --git a/mappings/net/minecraft/nbt/NbtString.mapping b/mappings/net/minecraft/nbt/NbtString.mapping index 5c34435e4c..5e57b126c7 100644 --- a/mappings/net/minecraft/nbt/NbtString.mapping +++ b/mappings/net/minecraft/nbt/NbtString.mapping @@ -1,5 +1,6 @@ CLASS net/minecraft/class_2519 net/minecraft/nbt/NbtString - COMMENT Represents an NBT string. + COMMENT Represents an NBT string. Its type is {@value NbtElement#STRING_TYPE}. + COMMENT Instances are immutable. FIELD field_11590 value Ljava/lang/String; FIELD field_21045 TYPE Lnet/minecraft/class_4614; FIELD field_21046 EMPTY Lnet/minecraft/class_2519; @@ -13,8 +14,17 @@ CLASS net/minecraft/class_2519 net/minecraft/nbt/NbtString METHOD equals (Ljava/lang/Object;)Z ARG 1 o METHOD method_10706 escape (Ljava/lang/String;)Ljava/lang/String; + COMMENT {@return the string quoted with quotes and backslashes escaped} + COMMENT + COMMENT @implNote If {@code value} contains one of the singlequote or the double quote, + COMMENT it tries to use the other quotes to quote the string. If both appear, then the quote + COMMENT that appeared later will be used to quote the string. If neither of them appears, this + COMMENT uses a double quote. For example, the string {@code It's a "Tiny Potato"!} will be + COMMENT escaped as {@code "It's a \\"Tiny Potato\\"!"}, while the string + COMMENT {@code It is a "Tiny Potato"!} will be escaped as {@code 'It is a "Tiny Potato"!'}. ARG 0 value METHOD method_23256 of (Ljava/lang/String;)Lnet/minecraft/class_2519; + COMMENT {@return the NBT string from {@code value}} ARG 0 value METHOD method_39875 skip (Ljava/io/DataInput;)V ARG 0 input diff --git a/mappings/net/minecraft/nbt/NbtTagSizeTracker.mapping b/mappings/net/minecraft/nbt/NbtTagSizeTracker.mapping index e7c75f8a73..73f335ebf5 100644 --- a/mappings/net/minecraft/nbt/NbtTagSizeTracker.mapping +++ b/mappings/net/minecraft/nbt/NbtTagSizeTracker.mapping @@ -1,4 +1,6 @@ CLASS net/minecraft/class_2505 net/minecraft/nbt/NbtTagSizeTracker + COMMENT Tracks the size of NBT elements. Throws {@link RuntimeException} if the + COMMENT tracked element becomes larger than {@link #maxBytes} during addition. FIELD field_11555 allocatedBytes J FIELD field_11556 EMPTY Lnet/minecraft/class_2505; FIELD field_11557 maxBytes J diff --git a/mappings/net/minecraft/nbt/NbtType.mapping b/mappings/net/minecraft/nbt/NbtType.mapping index efa56553fb..ebddc9e7dd 100644 --- a/mappings/net/minecraft/nbt/NbtType.mapping +++ b/mappings/net/minecraft/nbt/NbtType.mapping @@ -2,6 +2,11 @@ CLASS net/minecraft/class_4614 net/minecraft/nbt/NbtType COMMENT Represents an NBT type. METHOD method_23259 getCrashReportName ()Ljava/lang/String; METHOD method_23260 createInvalid (I)Lnet/minecraft/class_4614; + COMMENT {@return an invalid NBT type} + COMMENT + COMMENT

Operations with an invalid NBT type always throws {@link IOException}. + COMMENT + COMMENT @see NbtTypes#byId(int) ARG 0 type METHOD method_23261 getCommandFeedbackName ()Ljava/lang/String; METHOD method_23262 read (Ljava/io/DataInput;ILnet/minecraft/class_2505;)Lnet/minecraft/class_2520; @@ -29,5 +34,8 @@ CLASS net/minecraft/class_4614 net/minecraft/nbt/NbtType CLASS 1 METHOD method_39878 createException ()Ljava/io/IOException; CLASS class_6839 OfFixedSize + COMMENT Represents an NBT type whose elements have a fixed size, such as primitives. METHOD method_39853 getSizeInBytes ()I + COMMENT {@return the size of the elements in bytes} CLASS class_6840 OfVariableSize + COMMENT Represents an NBT type whose elements can have a variable size, such as lists. diff --git a/mappings/net/minecraft/nbt/NbtTypes.mapping b/mappings/net/minecraft/nbt/NbtTypes.mapping index 7d855d3ee1..5d2e4a1911 100644 --- a/mappings/net/minecraft/nbt/NbtTypes.mapping +++ b/mappings/net/minecraft/nbt/NbtTypes.mapping @@ -1,4 +1,5 @@ CLASS net/minecraft/class_4615 net/minecraft/nbt/NbtTypes + COMMENT A class holding known NBT types. FIELD field_21048 VALUES [Lnet/minecraft/class_4614; METHOD method_23265 byId (I)Lnet/minecraft/class_4614; COMMENT Gets the associated {@linkplain NbtType NBT type} for a given {@code id}. diff --git a/mappings/net/minecraft/nbt/StringNbtReader.mapping b/mappings/net/minecraft/nbt/StringNbtReader.mapping index 4a029e31ea..6233c07b5e 100644 --- a/mappings/net/minecraft/nbt/StringNbtReader.mapping +++ b/mappings/net/minecraft/nbt/StringNbtReader.mapping @@ -1,4 +1,8 @@ CLASS net/minecraft/class_2522 net/minecraft/nbt/StringNbtReader + COMMENT A class for reading a stringified NBT. + COMMENT + COMMENT @apiNote Methods in this class throw {@code CommandSyntaxException} to indicate + COMMENT syntax errors within the NBT representation. FIELD field_11596 FLOAT_PATTERN Ljava/util/regex/Pattern; FIELD field_11597 ARRAY_MIXED Lcom/mojang/brigadier/exceptions/Dynamic2CommandExceptionType; FIELD field_11598 reader Lcom/mojang/brigadier/StringReader; @@ -24,6 +28,10 @@ CLASS net/minecraft/class_2522 net/minecraft/nbt/StringNbtReader METHOD method_10716 readComma ()Z METHOD method_10717 parseArray ()Lnet/minecraft/class_2520; METHOD method_10718 parse (Ljava/lang/String;)Lnet/minecraft/class_2487; + COMMENT {@return the NBT compound parsed from the {@code string}} + COMMENT + COMMENT @throws CommandSyntaxException if the reader detects a syntax error (including + COMMENT {@linkplain #TRAILING trailing strings}) ARG 0 string METHOD method_10719 expect (C)V ARG 1 c @@ -32,12 +40,18 @@ CLASS net/minecraft/class_2522 net/minecraft/nbt/StringNbtReader METHOD method_10721 readCompound ()Lnet/minecraft/class_2487; METHOD method_10722 parseElementPrimitive ()Lnet/minecraft/class_2520; METHOD method_10723 parseElement ()Lnet/minecraft/class_2520; + COMMENT {@return the parsed NBT element} + COMMENT + COMMENT @throws CommandSyntaxException if the reader detects a syntax error METHOD method_10724 (Ljava/lang/Object;Ljava/lang/Object;)Lcom/mojang/brigadier/Message; ARG 0 receivedType ARG 1 expectedType METHOD method_10725 readString ()Ljava/lang/String; METHOD method_10726 parseElementPrimitiveArray ()Lnet/minecraft/class_2520; METHOD method_10727 parseCompound ()Lnet/minecraft/class_2487; + COMMENT {@return the parsed NBT compound} + COMMENT + COMMENT @throws CommandSyntaxException if the reader detects a syntax error METHOD method_10728 readArray (Lnet/minecraft/class_4614;Lnet/minecraft/class_4614;)Ljava/util/List; ARG 1 arrayTypeReader ARG 2 typeReader diff --git a/mappings/net/minecraft/nbt/visitor/NbtOrderedStringFormatter.mapping b/mappings/net/minecraft/nbt/visitor/NbtOrderedStringFormatter.mapping index e39a8259c0..bc40c6181a 100644 --- a/mappings/net/minecraft/nbt/visitor/NbtOrderedStringFormatter.mapping +++ b/mappings/net/minecraft/nbt/visitor/NbtOrderedStringFormatter.mapping @@ -31,6 +31,7 @@ CLASS net/minecraft/class_5625 net/minecraft/nbt/visitor/NbtOrderedStringFormatt METHOD method_32282 (Ljava/util/HashMap;)V ARG 0 map METHOD method_32283 apply (Lnet/minecraft/class_2520;)Ljava/lang/String; + COMMENT {@return the stringified NBT {@code element}} ARG 1 element METHOD method_32284 popPathPart ()V METHOD method_32285 pushPathPart (Ljava/lang/String;)V diff --git a/mappings/net/minecraft/nbt/visitor/NbtTextFormatter.mapping b/mappings/net/minecraft/nbt/visitor/NbtTextFormatter.mapping index 533de1bd77..76c1f8d110 100644 --- a/mappings/net/minecraft/nbt/visitor/NbtTextFormatter.mapping +++ b/mappings/net/minecraft/nbt/visitor/NbtTextFormatter.mapping @@ -26,4 +26,5 @@ CLASS net/minecraft/class_5628 net/minecraft/nbt/visitor/NbtTextFormatter METHOD method_32304 escapeName (Ljava/lang/String;)Lnet/minecraft/class_2561; ARG 0 name METHOD method_32305 apply (Lnet/minecraft/class_2520;)Lnet/minecraft/class_2561; + COMMENT {@return the textified NBT {@code element}} ARG 1 element diff --git a/mappings/net/minecraft/nbt/visitor/StringNbtWriter.mapping b/mappings/net/minecraft/nbt/visitor/StringNbtWriter.mapping index b0e50e47c3..d0fc724bc1 100644 --- a/mappings/net/minecraft/nbt/visitor/StringNbtWriter.mapping +++ b/mappings/net/minecraft/nbt/visitor/StringNbtWriter.mapping @@ -5,4 +5,5 @@ CLASS net/minecraft/class_5626 net/minecraft/nbt/visitor/StringNbtWriter METHOD method_32287 escapeName (Ljava/lang/String;)Ljava/lang/String; ARG 0 name METHOD method_32288 apply (Lnet/minecraft/class_2520;)Ljava/lang/String; + COMMENT {@return the stringified NBT {@code element}} ARG 1 element diff --git a/src/packageDocs/java/net/minecraft/nbt/package-info.java b/src/packageDocs/java/net/minecraft/nbt/package-info.java new file mode 100644 index 0000000000..b6b58650a5 --- /dev/null +++ b/src/packageDocs/java/net/minecraft/nbt/package-info.java @@ -0,0 +1,238 @@ +/* + * This file is free for everyone to use under the Creative Commons Zero license. + */ + +/** + * The Named Binary Tag (NBT) data format. + * + *

NBT is a simple data structure format used in Minecraft's in-game data + * serialization. Data stored on disks, modified by commands, and transported + * via packets are usually in this format. In most cases, NBT is not + * the runtime form of data; data are instead written to Java + * class fields using Java types, and during serialization (as part of saving + * or network transportation) or modification by commands, the code will write + * the fields to NBT data. NBT data is also known as "NBT element". + * + *

Types

+ *

There are 13 NBT element types, as shown below. Each NBT type has its own class, + * and a {@link NbtType} instance used during deserialization in the {@code TYPE} + * static field. They also have the "numeric ID" used during serialization and at + * {@link NbtCompound#getList(String, int)} method. The ID of the element's type can + * be obtained via the {@link NbtElement#getType()} method. There is also a special + * ID, {@link NbtElement#NUMBER_TYPE}, which indicates the read value + * can be any of the six numeric types; this cannot be used as the list's held type. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NBT types
ClassNumeric IDImmutable?DefaultDescription
{@link NbtEnd}
{@value NbtElement#END_TYPE}Yes(none)Internal type used during serialization, should not be used directly
{@link NbtByte}{@value NbtElement#BYTE_TYPE}Yes{@code 0}Corresponds to {@code byte}
{@link NbtShort}{@value NbtElement#SHORT_TYPE}Yes{@code 0}Corresponds to {@code short}
{@link NbtInt}{@value NbtElement#INT_TYPE}Yes{@code 0}Corresponds to {@code int}
{@link NbtLong}{@value NbtElement#LONG_TYPE}Yes{@code 0L}Corresponds to {@code long}
{@link NbtFloat}{@value NbtElement#FLOAT_TYPE}Yes{@code 0.0f}Corresponds to {@code float}
{@link NbtDouble}{@value NbtElement#DOUBLE_TYPE}Yes{@code 0.0}Corresponds to {@code double}
{@link NbtByteArray}{@value NbtElement#BYTE_ARRAY_TYPE}NoEmpty arrayCorresponds to {@code byte[]}
{@link NbtString}{@value NbtElement#STRING_TYPE}Yes{@code ""}Corresponds to {@link String}
{@link NbtList}{@value NbtElement#LIST_TYPE}NoEmpty listList of NBT elements with the same type
{@link NbtCompound}{@value NbtElement#COMPOUND_TYPE}NoEmpty compoundHash map-like object with string keys that can store any NBT elements
{@link NbtIntArray}
{@value NbtElement#INT_ARRAY_TYPE}NoEmpty arrayCorresponds to {@code int[]}
{@link NbtLongArray}{@value NbtElement#LONG_ARRAY_TYPE}NoEmpty arrayCorresponds to {@code long[]}
+ * + *

{@link NbtEnd}

+ *

NbtEnd is a special sentinel used to indicate the end of lists and compounds. + * This is also used as the type of empty lists. + * + *

Numeric types

+ *

NBT offers 6 numeric types (4 for integers and 2 for decimals), all corresponding + * to Java equivalents. There is no unsigned type or {@code char} equivalent. These + * inherit {@link AbstractNbtNumber}. To create an instance of these, use the {@code of} + * static method, and to obtain the value as the Java primitive value, use the + * {@code typeValue()} method. + * + * 

{@code
+ *   NbtInt nbt = NbtInt.of(100);
+ *   int value = nbt.intValue();
+ * }
+ * + *

One thing to note here is that NBT lacks the boolean type; instead {@link NbtByte} + * is used when boolean values are needed. See also {@link NbtByte#of(boolean)} method. + * + *

NBT typed arrays

+ *

There are 3 typed arrays in NBT: {@link NbtByteArray}, {@link NbtIntArray}, and + * {@link NbtLongArray}. There are no array types for shorts, floats or doubles. While they + * are arrays internally, they also support {@linkplain AbstractNbtList#add adding items} + * at runtime. Like Java arrays, out of bounds access is forbidden and will throw + * {@link ArrayIndexOutOfBoundsException}. + * + *

{@link NbtList}

+ *

NbtList is a list of a specific type of NBT elements. Empty lists always have the type + * set as {@link NbtEnd}. {@link NbtList#add} throws when the type is incompatible, while + * {@link NbtList#addElement} does nothing and returns {@code false} in that case. + * There are type-specific getters which can be used to get the value. They return the default + * value when type mismatch occurs or when the index is out of bounds. Note that they do not + * cast the value at all. + * + * 

{@code
+ *   NbtList list = new NbtList();
+ *   list.addElement(0, NbtFloat.of(0.5f));
+ *   float firstItem = list.getFloat(0); // 0.5f
+ *   float secondItem = list.getFloat(1); // 0.0f (default value)
+ *   double firstItemDouble = list.getDouble(0); // 0.0 (no casting)
+ *   list.addElement(1, NbtDouble.of(1.0)); // returns false, does nothing
+ *   list.add(NbtDouble.of(2.0)); // throws UnsupportedOperationException
+ * }
+ * + *

{@link NbtCompound}

+ *

NbtCompound is a hash map-like key-value storage object. It also acts as the root + * object for serialized NBTs. The keys are always strings, while the values can be of + * any type, and multiple value types can be mixed in a single compound. The order of items + * is not guaranteed. There are generic {@link NbtCompound#put} and {@link NbtCompound#get} + * methods, and there also exist type-specific getters and putters. Like the list getters + * mentioned above, they return the default value when the key is missing or type mismatch + * occurs. However, unlike lists, they attempt to cast numeric values. + * + * 

{@code
+ *   NbtCompound compound = new NbtCompound();
+ *   compound.put("Awesomeness", NbtInt.of(90));
+ *
+ *   // Don't do this! This will crash if the type is incompatible,
+ *   // even if they can be casted!
+ *   NbtInt awesomenessNbt = (NbtInt)compound.get("Awesomeness");
+ *
+ *   compound.putLong("Awesomeness", 100L);
+ *   int awesomeness = compound.getInt("Awesomeness"); // 100 (after casting)
+ *   int evilness = compound.getInt("Evilness"); // 0 (default value)
+ *
+ *   // Shortcuts for getting and putting a boolean value
+ *   // (internally represented as a byte)
+ *   compound.putBoolean("Awesome", true);
+ *   boolean awesome = compound.getBoolean("Awesome");
+ *   compound.put("awesome", NbtDouble.of(1.0)); // key is case-sensitive
+ * }
+ * + *

Using NBT

+ *

As noted before, NBT is a serialized format, not runtime format. + * Unrecognized custom data stored inside NBT will be lost once the game loads it and saves. + * Therefore, modifying NBT is usually not the solution for attaching custom data to + * objects like entities. For this purpose it is recommended to use third-party APIs + * or use Mixin to add a field to the class. + * + *

With that said, here is how to use NBT in the vanilla code: + * + *

Methods named {@code readNbt} will read the values from the element, modifying + * the current instance. Static methods named {@code fromNbt} will create a new instance + * of the class with values from the element. Methods named {@code writeNbt} will add + * the NBT data to the passed element. Methods named {@code toNbt} will create and return + * a new element with the data. + * + *

There are several helper classes for NBTs: + *

+ * + *

NBT compounds can also be transported using {@link + * net.minecraft.network.PacketByteBuf#writeNbt} and {@link + * net.minecraft.network.PacketByteBuf#readNbt}. + */ + +package net.minecraft.nbt;