NBT Component Serializer

nbt/src/main/java/net/kyori/adventure/nbt/TagStringWriter.java

@@ -25,7 +25,9 @@
 
 import java.io.IOException;
 import java.io.Writer;
-import java.util.Map;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 
 /**
  * An emitter for the SNBT format.
@@ -80,10 +82,17 @@ public TagStringWriter writeTag(final BinaryTag tag) throws IOException {
 
   private TagStringWriter writeCompound(final CompoundBinaryTag tag) throws IOException {
     this.beginCompound();
-    for (final Map.Entry<String, ? extends BinaryTag> entry : tag) {
-      this.key(entry.getKey());
-      this.writeTag(entry.getValue());
+
+    final List<String> keys = new ArrayList<>(tag.keySet());
+    Collections.sort(keys);
+
+    for (final String key : keys) {
+      final BinaryTag value = tag.get(key);
+      if (value == null) continue;
+      this.key(key);
+      this.writeTag(value);
     }
+
     this.endCompound();
     return this;
   }

nbt/src/test/resources/bigtest.snbt

@@ -1,11 +1,8 @@
 {
-    shortTest: 32767s,
-    longTest: 9223372036854775807L,
-    byteTest: 127b,
     "byteArrayTest (the first 1000 values of (n*n*255+n*7)%100, starting with n=0 (0, 62, 34, 16, 8, ...))": [B; 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B, 0B, 62B, 34B, 16B, 8B, 10B, 22B, 44B, 76B, 18B, 70B, 32B, 4B, 86B, 78B, 80B, 92B, 14B, 46B, 88B, 40B, 2B, 74B, 56B, 48B, 50B, 62B, 84B, 16B, 58B, 10B, 72B, 44B, 26B, 18B, 20B, 32B, 54B, 86B, 28B, 80B, 42B, 14B, 96B, 88B, 90B, 2B, 24B, 56B, 98B, 50B, 12B, 84B, 66B, 58B, 60B, 72B, 94B, 26B, 68B, 20B, 82B, 54B, 36B, 28B, 30B, 42B, 64B, 96B, 38B, 90B, 52B, 24B, 6B, 98B, 0B, 12B, 34B, 66B, 8B, 60B, 22B, 94B, 76B, 68B, 70B, 82B, 4B, 36B, 78B, 30B, 92B, 64B, 46B, 38B, 40B, 52B, 74B, 6B, 48B],
-    "listTest (long)": [11L, 12L, 13L, 14L, 15L],
-    floatTest: 0.49823147f,
+    byteTest: 127b,
     doubleTest: 0.4931287132182315d,
+    floatTest: 0.49823147f,
     intTest: 2147483647,
     "listTest (compound)": [
         {
@@ -17,6 +14,8 @@
             name: "Compound tag #1"
         }
     ],
+    "listTest (long)": [11L, 12L, 13L, 14L, 15L],
+    longTest: 9223372036854775807L,
     "nested compound test": {
         egg: {
             name: "Eggbert",
@@ -27,5 +26,6 @@
             value: 0.75f
         }
     },
+    shortTest: 32767s,
     stringTest: "HELLO WORLD THIS IS A TEST STRING ÅÄÖ!"
 }

settings.gradle.kts

@@ -51,6 +51,7 @@ sequenceOf(
   "text-serializer-legacy",
   "text-serializer-plain",
   "text-serializer-ansi",
+  "text-serializer-nbt"
 ).forEach {
   include("adventure-$it")
   project(":adventure-$it").projectDir = file(it)

text-serializer-commons/src/main/java/net/kyori/adventure/text/serializer/commons/ComponentTreeConstants.java

@@ -86,6 +86,8 @@ public final class ComponentTreeConstants {
   @ApiStatus.Obsolete
   public static final String HOVER_EVENT_VALUE = "value";
   @ApiStatus.Obsolete
+  public static final String SHOW_TEXT_TEXT = "text";
+  @ApiStatus.Obsolete
   public static final String SHOW_ENTITY_TYPE = "type";
   public static final String SHOW_ENTITY_ID = "id";
   public static final String SHOW_ENTITY_UUID = "uuid";

text-serializer-gson/src/main/java/net/kyori/adventure/text/serializer/gson/ShowItemSerializer.java

@@ -147,7 +147,7 @@ public void write(final JsonWriter out, final HoverEvent.ShowItem value) throws
       out.name(SHOW_ITEM_COMPONENTS);
       out.beginObject();
       for (final Map.Entry<Key, GsonDataComponentValue> entry : value.dataComponentsAs(GsonDataComponentValue.class).entrySet()) {
-        final JsonElement el = entry.getValue().element();;
+        final JsonElement el = entry.getValue().element();
         if (el instanceof JsonNull) { // removed
           out.name(DATA_COMPONENT_REMOVAL_PREFIX + entry.getKey().asString());
           out.beginObject().endObject();

text-serializer-nbt/build.gradle.kts

@@ -0,0 +1,14 @@
+plugins {
+  id("adventure.common-conventions")
+}
+
+dependencies {
+  api(libs.option)
+  api(projects.adventureApi)
+  api(projects.adventureNbt)
+  compileOnlyApi(libs.autoService.annotations)
+  implementation(projects.adventureTextSerializerCommons)
+  annotationProcessor(libs.autoService)
+}
+
+applyJarMetadata("net.kyori.adventure.text.serializer.nbt")

text-serializer-nbt/src/main/java/net/kyori/adventure/text/serializer/nbt/ClickEventSerializer.java

@@ -0,0 +1,167 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2025 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package net.kyori.adventure.text.serializer.nbt;
+
+import java.io.IOException;
+import net.kyori.adventure.nbt.BinaryTag;
+import net.kyori.adventure.nbt.BinaryTagTypes;
+import net.kyori.adventure.nbt.CompoundBinaryTag;
+import net.kyori.adventure.nbt.StringBinaryTag;
+import net.kyori.adventure.nbt.api.BinaryTagHolder;
+import net.kyori.adventure.text.event.ClickEvent;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import static net.kyori.adventure.text.serializer.commons.ComponentTreeConstants.CLICK_EVENT_ACTION;
+import static net.kyori.adventure.text.serializer.commons.ComponentTreeConstants.CLICK_EVENT_COMMAND;
+import static net.kyori.adventure.text.serializer.commons.ComponentTreeConstants.CLICK_EVENT_ID;
+import static net.kyori.adventure.text.serializer.commons.ComponentTreeConstants.CLICK_EVENT_PAGE;
+import static net.kyori.adventure.text.serializer.commons.ComponentTreeConstants.CLICK_EVENT_PAYLOAD;
+import static net.kyori.adventure.text.serializer.commons.ComponentTreeConstants.CLICK_EVENT_URL;
+import static net.kyori.adventure.text.serializer.commons.ComponentTreeConstants.CLICK_EVENT_VALUE;
+import static net.kyori.adventure.text.serializer.nbt.NBTSerializerUtils.SNBT_CODEC;
+import static net.kyori.adventure.text.serializer.nbt.NBTSerializerUtils.requiredTag;
+
+final class ClickEventSerializer {
+
+  private static final String FALLBACK_URL_PROTOCOL = "https://";
+
+  private ClickEventSerializer() {
+  }
+
+  static @Nullable ClickEvent<?> deserialize(final @NotNull CompoundBinaryTag compound, final boolean snakeCase) {
+    final StringBinaryTag actionTag = requiredTag(compound, CLICK_EVENT_ACTION, BinaryTagTypes.STRING);
+    final ClickEvent.Action<?> action = ClickEvent.Action.NAMES.valueOrThrow(actionTag.value());
+
+    if (!action.readable()) {
+      return null;
+    }
+
+    if (snakeCase) {
+      return switch (action) {
+        case ClickEvent.Action.OpenUrl ignored ->
+          ClickEvent.openUrl(requiredTag(compound, CLICK_EVENT_URL, BinaryTagTypes.STRING).value());
+        case ClickEvent.Action.RunCommand ignored ->
+          ClickEvent.runCommand(requiredTag(compound, CLICK_EVENT_COMMAND, BinaryTagTypes.STRING).value());
+        case ClickEvent.Action.SuggestCommand ignored ->
+          ClickEvent.suggestCommand(requiredTag(compound, CLICK_EVENT_COMMAND, BinaryTagTypes.STRING).value());
+        case ClickEvent.Action.ChangePage ignored ->
+          ClickEvent.changePage(requiredTag(compound, CLICK_EVENT_PAGE, BinaryTagTypes.INT).value());
+        case ClickEvent.Action.CopyToClipboard ignored ->
+          ClickEvent.copyToClipboard(requiredTag(compound, CLICK_EVENT_VALUE, BinaryTagTypes.STRING).value());
+        case ClickEvent.Action.Custom ignored -> {
+          try {
+            final StringBinaryTag clickEventIdTag = requiredTag(compound, CLICK_EVENT_ID, BinaryTagTypes.STRING);
+            final BinaryTag payloadTag = requiredTag(compound, CLICK_EVENT_PAYLOAD);
+            yield ClickEvent.custom(KeySerializer.deserialize(clickEventIdTag), BinaryTagHolder.encode(payloadTag, SNBT_CODEC));
+          } catch (final IOException exception) {
+            throw new RuntimeException("An error occurred while encoding payload tag", exception);
+          }
+        }
+        // Non-readable actions are filtered out above.
+        case ClickEvent.Action.OpenFile ignored -> null;
+        case ClickEvent.Action.ShowDialog ignored -> null;
+      };
+    } else {
+      final String value = requiredTag(compound, CLICK_EVENT_VALUE, BinaryTagTypes.STRING).value();
+      if (action instanceof ClickEvent.Action.TextCarrier) {
+        @SuppressWarnings("unchecked")
+        final ClickEvent.Action<ClickEvent.Payload.Text> textAction = (ClickEvent.Action<ClickEvent.Payload.Text>) action;
+        return ClickEvent.clickEvent(textAction, ClickEvent.Payload.string(value));
+      } else if (action instanceof ClickEvent.Action.ChangePage) {
+        return ClickEvent.changePage(Integer.parseInt(value));
+      }
+      return null;
+    }
+  }
+
+  static @Nullable CompoundBinaryTag serialize(final @NotNull ClickEvent<?> event, final boolean snakeCase,
+                                               final @NotNull NBTComponentSerializerImpl serializer) {
+    final ClickEvent.Action<?> action = event.action();
+    if (!action.readable()) {
+      return null;
+    }
+
+    final CompoundBinaryTag.Builder builder = CompoundBinaryTag.builder()
+      .putString(CLICK_EVENT_ACTION, ClickEvent.Action.NAMES.keyOrThrow(action));
+
+    final boolean emitHttps = serializer.options().value(NBTSerializerOptions.EMIT_CLICK_URL_HTTPS);
+
+    if (snakeCase) {
+      final ClickEvent.Payload payload = event.payload();
+      switch (payload) {
+        case ClickEvent.Payload.Text text -> {
+          final String payloadFieldName = switch (action) {
+            case ClickEvent.Action.OpenUrl ignored -> CLICK_EVENT_URL;
+            case ClickEvent.Action.RunCommand ignored -> CLICK_EVENT_COMMAND;
+            case ClickEvent.Action.SuggestCommand ignored -> CLICK_EVENT_COMMAND;
+            case ClickEvent.Action.CopyToClipboard ignored -> CLICK_EVENT_VALUE;
+            default -> throw new IllegalArgumentException("Unexpected text-payload click event action: " + action);
+          };
+          builder.putString(payloadFieldName, textPayloadValue(action, text.value(), emitHttps));
+        }
+        case ClickEvent.Payload.Int intPayload -> builder.putInt(CLICK_EVENT_PAGE, intPayload.integer());
+        case ClickEvent.Payload.Custom customPayload -> {
+          try {
+            builder.put(CLICK_EVENT_ID, KeySerializer.serialize(customPayload.key()));
+            final BinaryTagHolder nbt = customPayload.nbt();
+            if (nbt != null) {
+              builder.put(CLICK_EVENT_PAYLOAD, nbt.get(SNBT_CODEC));
+            }
+          } catch (final IOException exception) {
+            throw new RuntimeException("An error occurred while decoding a payload tag", exception);
+          }
+        }
+        case ClickEvent.Payload.Dialog ignored -> {
+        }
+      }
+    } else {
+      final ClickEvent.Payload payload = event.payload();
+      final String value = switch (payload) {
+        case ClickEvent.Payload.Text text -> textPayloadValue(action, text.value(), emitHttps);
+        case ClickEvent.Payload.Int intPayload -> String.valueOf(intPayload.integer());
+        case ClickEvent.Payload.Custom ignored -> null;
+        case ClickEvent.Payload.Dialog ignored -> null;
+      };
+      if (value == null) {
+        return null;
+      }
+      builder.putString(CLICK_EVENT_VALUE, value);
+    }
+
+    return builder.build();
+  }
+
+  private static @NotNull String textPayloadValue(final ClickEvent.@NotNull Action<?> action, final @NotNull String value, final boolean emitHttps) {
+    if (emitHttps && action == ClickEvent.Action.OPEN_URL && !hasUrlScheme(value)) {
+      return FALLBACK_URL_PROTOCOL + value;
+    }
+    return value;
+  }
+
+  @SuppressWarnings("HttpUrlsUsage")
+  private static boolean hasUrlScheme(final @NotNull String url) {
+    return url.startsWith("http://") || url.startsWith("https://");
+  }
+}