From 79ba1dd2752508ab8156a56469c08a652b078c83 Mon Sep 17 00:00:00 2001 From: SoSeDiK Date: Fri, 14 Jun 2024 04:12:21 +0300 Subject: [PATCH] [WIP] Started updating wiki --- README.md | 4 +- curseforge.md | 4 +- ...ng-Minecraft-Objects-to-NBT-and-Strings.md | 42 --- ...kin-using-NBT-API.md => Example-Usages.md} | 24 +- wiki/FAQ.md | 26 ++ wiki/Home.md | 25 +- ...he-data-from-one-onto-another-compound).md | 24 -- wiki/Plugins.md | 7 +- wiki/Using-Gradle.md | 6 +- wiki/Using-Maven.md | 6 +- wiki/Using-the-NBT-API.md | 323 ++++++++++++++---- ...-up-loot-and-does-0.5-hearths-of-damage.md | 14 - wiki/_Footer.md | 4 +- wiki/_Sidebar.md | 22 +- 14 files changed, 348 insertions(+), 183 deletions(-) delete mode 100644 wiki/Converting-Minecraft-Objects-to-NBT-and-Strings.md rename wiki/{Set-a-skull's-skin-using-NBT-API.md => Example-Usages.md} (57%) create mode 100644 wiki/FAQ.md delete mode 100644 wiki/Merging-Compounds-(Copy-the-data-from-one-onto-another-compound).md delete mode 100644 wiki/Zombie-that-can-pick-up-loot-and-does-0.5-hearths-of-damage.md diff --git a/README.md b/README.md index 8fbe9fd11..5a41acb2b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Item-NBT-API -Add custom NBT tags to Items/Tiles/Entities without NMS! Modify NBT and store it Files, other NBT or as String in yaml/json/SQL/Redis. +Add custom NBT tags to Items/Tiles/Entities without NMS! Modify NBT and store it in Files, other NBT, or as String in yaml/json/SQL/Redis. [Server Owner/Developer Wiki](https://github.com/tr7zw/Item-NBT-API/wiki) ### Build/Maven/Sonar Status @@ -15,7 +15,7 @@ Add custom NBT tags to Items/Tiles/Entities without NMS! Modify NBT and store it ## Getting started -Import the API [using Maven](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Maven), then check out the [basic usage](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API) or code examples like [working with Skulls](https://github.com/tr7zw/Item-NBT-API/wiki/Set-a-skull's-skin-using-NBT-API). +Import the API using [Maven](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Maven) or [Gradle](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Gradle), then check out the [basic usage](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API) or code examples like [working with Skulls](https://github.com/tr7zw/Item-NBT-API/wiki/Example-Usages#set-a-skulls-skin). ### bStats diff --git a/curseforge.md b/curseforge.md index 217ab406c..a019b8c0b 100644 --- a/curseforge.md +++ b/curseforge.md @@ -1,6 +1,6 @@ # (Item-)NBT-API -Add custom NBT tags to Items/Tiles/Entities without NMS! Modify NBT and store it Files, other NBT or as String in yaml/json/SQL/Redis. +Add custom NBT tags to Items/Tiles/Entities without NMS! Modify NBT and store it in Files, other NBT, or as String in yaml/json/SQL/Redis. [Server Owner/Developer Wiki](https://github.com/tr7zw/Item-NBT-API/wiki) ### Build/Maven/Sonar Status @@ -14,7 +14,7 @@ Discord:[![Discord](https://img.shields.io/discord/342814924310970398?color=%237 ## Getting started -Import the API [using Maven](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Maven), then check out the [basic usage](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API) or code examples like [working with Skulls](https://github.com/tr7zw/Item-NBT-API/wiki/Set-a-skull's-skin-using-NBT-API). +Import the API using [Maven](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Maven) or [Gradle](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Gradle), then check out the [basic usage](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API) or code examples like [working with Skulls](https://github.com/tr7zw/Item-NBT-API/wiki/Example-Usages#set-a-skulls-skin). ### bStats diff --git a/wiki/Converting-Minecraft-Objects-to-NBT-and-Strings.md b/wiki/Converting-Minecraft-Objects-to-NBT-and-Strings.md deleted file mode 100644 index 775f41219..000000000 --- a/wiki/Converting-Minecraft-Objects-to-NBT-and-Strings.md +++ /dev/null @@ -1,42 +0,0 @@ -# Converting Minecraft Objects to NBT and Strings - -The basic idea is that you can convert data into different representations: -Minecraft Objects <-> NBT <-> String(Mojang-Json) - -## Converting Minecraft Objects into NBT - -```java -// Items -ReadWriteNBT nbt = NBT.itemStackToNBT(itemStack); -ReadWriteNBT nbt = NBT.itemStackArrayToNBT(itemStacks); -// Entity -NBTEntity nbte = new NBTEntity(entity); -// Tiles -NBTTileEntity nbtt= new NBTTileEntity(block.getState()); -// Gameprofiles -ReadWriteNBT nbt = NBT.gameProfileToNBT(profile); -// NBT Files -NBTFile file = new NBTFile(testFile); -``` - -## Converting NBT to a String and the String back to NBT - -```java -// to String(works with any NBT object) -String str = nbt.toString(); -// String back to NBT -ReadWriteNBT nbt = NBT.parseNBT(json); -``` - -## Recreating the Minecraft Objects from NBT - -```java -// Items -ItemStack itemStack = NBT.itemStackFromNBT(nbt); -ItemStack[] itemStacks = NBT.itemStackArrayFromNBT(nbt); -// Entity/Tiles -In general "new NBTEntity(entity).mergeCompound(nbt)", but you might want to remove some data from the nbt first like the Location, uuid and entityId -// Gameprofile -GameProfile profile = NBT.gameProfileFromNBT(nbt); -``` - diff --git a/wiki/Set-a-skull's-skin-using-NBT-API.md b/wiki/Example-Usages.md similarity index 57% rename from wiki/Set-a-skull's-skin-using-NBT-API.md rename to wiki/Example-Usages.md index 6967d9286..f8c4c0058 100644 --- a/wiki/Set-a-skull's-skin-using-NBT-API.md +++ b/wiki/Example-Usages.md @@ -1,4 +1,7 @@ -### We will be using [this head](https://minecraft-heads.com/custom-heads/food%20&%20drinks/28194-cup-of-soda) as example. +## Set a skull's skin + +// TODO broken link +#### We will be using [this head](https://minecraft-heads.com/custom-heads/food%20&%20drinks/28194-cup-of-soda) as example. ```java // This is the base64 texture value from the bottom of the previously mentioned website. @@ -6,7 +9,7 @@ final String textureValue = "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh // Creating ItemStack -// For Minecraft 1.12 and above +// For Minecraft 1.12 and below final ItemStack item = new ItemStack(Material.SKULL_ITEM); item.setDurability((short) 3); @@ -25,5 +28,22 @@ NBT.modify(item, nbt -> { .addCompound() .setString("Value", textureValue); }); + +// TODO 1.20.5+ example +// TODO A note/example about alternative in Paper API? ``` +## Zombie that can pick up loot and does 0.5 hearts of damage +```java +Zombie zombie = (Zombie) world.spawnEntity(location, EntityType.ZOMBIE); +NBT.modify(zombie, nbt -> { + nbt.setByte("CanPickUpLoot", (byte) 1); + ReadWriteNBTCompoundList list = nbt.getCompoundList("Attributes"); + for(int i = 0; i < list.size(); i++){ + ReadWriteNBT lc = list.get(i); + if(lc.getString("Name").equals("generic.attackDamage")){ + lc.setDouble("Base", 0.5d); + } + } +}); +``` diff --git a/wiki/FAQ.md b/wiki/FAQ.md new file mode 100644 index 000000000..2709927af --- /dev/null +++ b/wiki/FAQ.md @@ -0,0 +1,26 @@ +## Frequently Asked Questions + +### I've updated NBT-API, but is keeps saying that it's outdated + +// TODO + +### I've downloaded NBT-API, but the plugin keeps asking for ItemNBTAPI + +The plugin uses a very outdated version of NBT-API. In this case, download the version 1.8.3 from the versions tab. The outdated "ItemNBTAPI" and "NBTAPI" can be used both at the same time. + +### 1.7 support + +- Use 1.7.10. +- NBTLists may not work. +- NBTTypes don't work as 1.7.x is missing this feature. +- TLDR: 1.7.10 is a bit broken and not everything will work! Also, it's not supported anymore! + +### Where did NBTInjector go? + +The experimental NBTInjector became unsupported since Minecraft 1.14 and was removed in 2.13.0 with Minecraft 1.21 release. + +NBTInjector is incompatible with reloads and may break things, and thus is not recommended. + +If you're using Minecraft 1.14, you should switch to the persistent storage API instead. + +In versions prior to 1.14, you may use a workaround like storing data inside an item's nbt that the entity is wearing (e.g. having a button in mob's helmet, and storing data on that button). diff --git a/wiki/Home.md b/wiki/Home.md index 3cd554ca0..0892f962c 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -1,26 +1,19 @@ -# Welcome to the NBT API wiki +# Welcome to the NBT-API wiki -NBT API has been tested on Spigot -1.7.10-1.19+ +NBT-API supports Spigot and Paper versions starting at 1.8. It runs on 1.7.10 too, but some features might not work (see [1.7 support](https://github.com/tr7zw/Item-NBT-API/wiki/FAQ#17-support)). + +Feel free to seek for support in [![Discord](https://img.shields.io/discord/342814924310970398?color=%237289DA&label=Discord&logo=discord&logoColor=white)](https://discordapp.com/invite/yk4caxM). -Full JavaDoc can be found [here](https://tr7zw.github.io/Item-NBT-API/v2-api/)! ### What do I have to do as a server owner? -Just download the jar and drop it in the plugins folder. Done. -Note that outdated plugins may ask for "ItemNBTAPI". In this case, download version 1.8.3 from the versions tab. The outdated "ItemNBTAPI" and "NBTAPI" can be used at the same time. +Just download the jar and drop it in the plugins folder. Done! -### 1.7 Notes +You might also want to check out some [plugins that use NBT-API](https://github.com/tr7zw/Item-NBT-API/wiki/Plugins). -* Use 1.7.10 -* NBTLists may not work -* NBTTypes don't work as 1.7.x is missing this feature. -* TLDR: 1.7.10 is a bit broken and not everything will work! Also it's not supported anymore! - -### Don't reload the NBT-Injector - -Reloading in general is a horrible thing and it will break the NBTInjector in horrible ways! When updating plugins/changing configs always restart the server normally! ### How can I use the API as a developer? -See [Using the NBT API](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API) +Import the API using [Maven](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Maven) or [Gradle](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Gradle), then see the [basic usage](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API) or code examples like [working with Skulls](https://github.com/tr7zw/Item-NBT-API/wiki/Set-a-skull's-skin-using-NBT-API) to familiarize yourself with the API. + +Full JavaDoc can be found [here](https://tr7zw.github.io/Item-NBT-API/v2-api/)! diff --git a/wiki/Merging-Compounds-(Copy-the-data-from-one-onto-another-compound).md b/wiki/Merging-Compounds-(Copy-the-data-from-one-onto-another-compound).md deleted file mode 100644 index b8992bcc2..000000000 --- a/wiki/Merging-Compounds-(Copy-the-data-from-one-onto-another-compound).md +++ /dev/null @@ -1,24 +0,0 @@ -# Merging Compounds - -You can "merge" the data from any given Compound onto some other Compound. This will overwrite tags with the same name. - -Example: - -`Tag1: {Num1:1, Num2:2} Tag2: {Num1:7, Num3:3}` - -After merging Tag2 on Tag1: - -```java -tag1.mergeCompound(tag2); -``` - -`Tag1: {Num1:7, Num2:2, Num3:3} Tag2: {Num1:7, Num3:3}` - -## Simulate the "/data merge" command - -```java -NBT.modify(zombie, nbt -> { - nbt.mergeCompound(NBT.parseNBT("{Silent:1b,Invulnerable:1b,Glowing:1b,IsBaby:1b}")); -}); -``` - diff --git a/wiki/Plugins.md b/wiki/Plugins.md index 24df57fd0..63c3606b4 100644 --- a/wiki/Plugins.md +++ b/wiki/Plugins.md @@ -1,6 +1,4 @@ -## List of some plugins on Github that utilize NBTAPI - -Want your plugin added to this list? Submit a PR editing this file located in `~/wiki/Plugins.md`! +## List of some plugins on GitHub that utilize NBT-API - [IllegalStack](https://github.com/dniym/IllegalStack) - [Prison](https://github.com/PrisonTeam/Prison) @@ -8,3 +6,6 @@ Want your plugin added to this list? Submit a PR editing this file located in `~ - [SkBee](https://github.com/ShaneBeee/SkBee/) - [Monumenta](https://github.com/TeamMonumenta/monumenta-plugins-public/) + +___ +Want your plugin added to this list? Submit a PR editing this file located in `~/wiki/Plugins.md`! diff --git a/wiki/Using-Gradle.md b/wiki/Using-Gradle.md index dd1b9d1e2..a079d7674 100644 --- a/wiki/Using-Gradle.md +++ b/wiki/Using-Gradle.md @@ -19,7 +19,7 @@ repositories { } ``` -Finally, add the API as dependency to your ``plugin.yml`` +Add the API as dependency to your ``plugin.yml``: ```yml depend: [NBTAPI] @@ -48,6 +48,9 @@ implementation("de.tr7zw:item-nbt-api:VERSION") (Get the current Version from [here](https://www.spigotmc.org/resources/nbt-api.7939/)) +> [!IMPORTANT] +> Make sure you're using ``item-nbt-api`` as ``artifactId``, never shade the ``-plugin`` artifact! + ```groovy repositories { ... @@ -74,4 +77,3 @@ build { dependsOn(shadowJar) } ``` - diff --git a/wiki/Using-Maven.md b/wiki/Using-Maven.md index 61313bcaa..24caa3191 100644 --- a/wiki/Using-Maven.md +++ b/wiki/Using-Maven.md @@ -26,7 +26,7 @@ Add the following Entries to your pom at the correct location: ``` -Add the API as dependency to your plugin.yml +Add the API as dependency to your ``plugin.yml``: ```yaml depend: [NBTAPI] @@ -46,7 +46,8 @@ Add the following Entries to your pom at the correct location: (Get the current Version from [here](https://modrinth.com/plugin/nbtapi/versions)) -**IMPORTANT: This is not the same ``artifactId`` as using it as dependency! Never shade the ``-plugin`` artifact!** +> [!IMPORTANT] +> Make sure you're using ``item-nbt-api`` as ``artifactId``, never shade the ``-plugin`` artifact! ```xml @@ -96,4 +97,3 @@ Example: com.yourname.pluginname.nbtapi ``` - diff --git a/wiki/Using-the-NBT-API.md b/wiki/Using-the-NBT-API.md index be1281ff1..8cd8617d4 100644 --- a/wiki/Using-the-NBT-API.md +++ b/wiki/Using-the-NBT-API.md @@ -1,88 +1,289 @@ -## Using the ``NBT`` class (prefered) +## General usage + +### Basics overview + +Most of the things are exposed inside the [NBT](https://tr7zw.github.io/Item-NBT-API/v2-api/de/tr7zw/changeme/nbtapi/NBT.html) class. + +#### Basic getting and setting of data + +[ReadableNBT](https://tr7zw.github.io/Item-NBT-API/v2-api/de/tr7zw/changeme/nbtapi/iface/ReadableNBT.html) and [ReadWriteNBT](https://tr7zw.github.io/Item-NBT-API/v2-api/de/tr7zw/changeme/nbtapi/iface/ReadWriteNBT.html) are used to read/write nbt: ```java -// Setting data on ItemStacks/Entities/BlockEntities +// Creating a new empty NBT tag +ReadWriteNBT nbt = NBT.createNBTObject(); + +// Setting nbt +nbt.setString("Stringtest", "Teststring"); +nbt.setInteger("Inttest", 42); +nbt.setDouble("Doubletest", 1.5); +nbt.setBoolean("Booleantest", true); +// More are available! Ask your IDE, or see Javadoc for suggestions! + +// Getting nbt +String s1 = nbt.getString("Stringtest"); +int i1 = nbt.getInteger("Inttest"); +double d = nbt.getDouble("Doubletest"); +boolean b = nbt.getBoolean("Booleantest"); +// Or, alternatively +String s2 = nbt.getOrDefault("Stringtest", "fallback_value"); +Integer i2 = nbt.getOrNull("Inttest", Integer.class); + +// Keys manipulation +nbt.getKeys(); // Get all Tags +nbt.hasTag("key"); // Check whether the Tag exists +nbt.hasTag("key", NbtType.NBTTagString); // Check whether the Tag exists and matches the type +nbt.removeKey("key"); // Remove the Tag +NBTType nbtType = getType("key"); // Get the type of the Tag + +// Subtag compounds +nbt.getCompound("subtag"); // Get a subtag, or null +nbt.getOrCreateCompound("subtag"); // Get or create a subtag +``` + +#### Converting NBT to String and the String back to NBT + +```java +// Parse Mojang-Json string to nbt +ReadWriteNBT nbt = NBT.parseNBT("{Silent:1b,Invulnerable:1b,Glowing:1b,IsBaby:1b}"); +// Get the NBT back as a Mojang-Json string (works with any NBT object) +String json = nbt.toString(); +// Turn back into nbt again +ReadWriteNBT nbt2 = NBT.parseNBT(json); +``` + +#### Merging Compounds + +You can "merge" the data from any given Compound onto some other Compound. This will overwrite the tags with the same name. + +Example: + +`Tag1: {Num1:1, Num2:2} Tag2: {Num1:7, Num3:3}` + +After merging Tag2 on Tag1: + +```java +tag1.mergeCompound(tag2); +``` + +`Tag1: {Num1:7, Num2:2, Num3:3} Tag2: {Num1:7, Num3:3}` + +#### Resolving data + +```java +// For accessing deeply nested subtags, you may use the resolve methods +// For example, the following code: +nbt.resolveOrCreateCompound("foo.bar.baz"); +// Will get/create the same subtag compound as: +nbt.getOrCreateCompound("foo").getOrCreateCompound("bar").getOrCreateCompound("baz"); + +// Dots in keys may be escaped with a backslash +nbt.resolveCompound("foo.some\\.key.baz"); // Gets the nested compound, or null + +// Similarly, you may also fetch values from nested subtags +String s = nbt.resolveOrDefault("foo.bar.Stringtest", "fallback_value"); +Integer i = nbt.resolveOrNull("foo\\.bar.baz.Inttest", Integer.class); +``` + +#### Accessing/creating lists and their data + +> [!NOTE] +> The lists will be created if they do not exist, there are no setters for lists! + +```java +// Get or create a string list +ReadWriteNBTList stringList = nbt.getStringList("list_key"); +stringList.add("value"); + +// You can obtain the value back just like with normal Lists +nbt.getStringList("list_key").get(0); +// Or by fetching it +nbt.resolveOrNull("list_key[0]", String.class); // Get the first value in list +// You can also use negative number to get the value from the end of the list/array +nbt.resolveOrDefault("list_key[-1]", "fallback_value"); // Get the last value in list, or use the default + + +// NBT compound lists +ReadWriteNBTCompoundList nbtList = nbt.getOrCreateCompound("foo").getCompoundList("other_key"); +ReadWriteNBT nbtListEntry = addCompound(); +nbtListEntry.setBoolean("bar", true); + +// You can also fetch compounds in lists +nbt.resolveCompound("foo.other_key[0]"); // Get the first compound in list, or null +nbt.resolveOrCreateCompound("foo.other_key[1]"); // Get the second compound in list, or create it +// Or fetch data from them +boolean bar = nbt.resolveOrDefault("foo.other_key[0].bar", false); +``` + +### Working with items + +```java +// Setting data NBT.modify(itemStack, nbt -> { nbt.setString("Stringtest", "Teststring"); nbt.setInteger("Inttest", 42); nbt.setDouble("Doubletest", 1.5d); nbt.setBoolean("Booleantest", true); - //More are available! Ask your IDE/Javadocs for suggestions! + // More are available! Ask your IDE, or see Javadoc for suggestions! }); -// Getting data from ItemStacks -String string = NBT.get(itemStack, nbt -> nbt.getString("Stringtest")); + +// Reading data +NBT.get(itemStack, nbt -> { + String stringTest = nbt.getString("Stringtest"); + int intTest = nbt.getOrDefault("Inttest", 0); + // Do more stuff +}); + +// Getting data +String string = NBT.get(itemStack, (String) nbt -> nbt.getString("Stringtest")); + +// Modifying and getting data +int someValue = NBT.modify(itemStack, nbt -> { + int i = nbt.getOrDefault("key", 0) + 1; + nbt.setInteger(i); + return i; +}); + // Updating ItemMeta using NBT NBT.modify(itemStack, nbt -> { nbt.setInteger("kills", nbt.getOrDefault("kills", 0) + 1); - nbt.modifyMeta((meta, readOnlyNbt) -> { // do not modify the nbt while modifying the meta! + nbt.modifyMeta((meta, readOnlyNbt) -> { // Do not modify the nbt while modifying the meta! meta.setDisplayName("Kills: " + readOnlyNbt.getOrDefault("kills", 0)); }); - //Do more stuff + // Do more stuff }); +``` -// Gameprofile to NBT -ReadWriteNBT nbt = NBT.gameProfileToNBT(profile); -// NBT to Gameprofile -GameProfile profile = NBT.nbtToGameProfile(nbt); -// ItemStack to NBT +> [!IMPORTANT] +> Since Minecraft 1.20.5 ItemStacks no longer have vanilla nbt during runtime. +> +> As a workaround, you may use the following code: + +```java +// NOTE: This code is only for 1.20.5+! +NBT.modifyComponents(item, nbt -> { + nbt.setString("minecraft:custom_name", "{\"extra\":[\"foobar\"],\"text\":\"\"}"); +}); +``` + +### Working with tiles/entities + +Working with entities and tile entities is similar to working items. + +#### Accessing vanilla nbt + +The example code for entities is applicable for tile entities too. + +```java +// Obtain data +boolean silent = NBT.get(entity, (boolean) nbt -> nbt.getBoolean("Silent")); +// Modify data +NBT.modify(entity, nbt -> { + nbt.setBoolean("Silent", true); + nbt.setByte("CanPickUpLoot", (byte) 1); +}); +``` + +#### Accessing custom data + +For reading/storing custom data on tiles/entities, you should use methods that end with PersistentData. + +```java +// Obtain data +boolean test = NBT.getPersistentData(entity, (boolean) nbt -> nbt.getBoolean("custom_key")); +// Modify data +NBT.modifyPersistentData(entity, nbt -> { + nbt.setBoolean("custom_key", true); + nbt.setByte("custom_byte", (byte) 1); +}); +``` + +> [!IMPORTANT] +> When working with tile entities, make sure that the block entity exists in the world. +> +> For example, you may not be able to add data to a chest in `BlockPlaceEvent` because the chest hasn't been placed yet. In such case, you can delay your actions by one tick or set the block to chest manually. + +#### Simulate the "/data merge" command + +```java +NBT.modify(zombie, nbt -> { + nbt.mergeCompound(NBT.parseNBT("{Silent:1b,Invulnerable:1b,Glowing:1b,IsBaby:1b}")); +}); +``` + +### Working with blocks + +You can store data in tile blocks (tile entities like chest, furnace, etc.) using the examples above, but normal blocks do not have the nbt data. + +// TODO nbt chunk & nbt block + +## Extras + +> [!TIP] +> Besides this page, you may also take a look at some code examples at [example usages](https://github.com/tr7zw/Item-NBT-API/wiki/Example-Usages). + +### NBT files + +```java +// Creating nbt file +// NBTFile will automatically create the file if it does not exist +NBTFile file = new NBTFile(new File("directory"), "test.nbt"); // Will be created at ./directory/test.nbt +// Setting data +file.setString("foo", "bar"); +// Saving file +file.save(); + +// Alternatively, you may use helper methods in NBTFile class +// To read the file without creating it if does not exist: +ReadWriteNBT nbt = NBTFile.readFrom(file); +// To save nbt to the file: +NBTFile.saveTo(file, nbt); +``` + +### Converting Minecraft Objects to NBT and Strings + +The basic idea is that you can convert data into different representations: +Minecraft Objects <-> NBT <-> String (Mojang-Json) + +#### Items + +// TODO explanation about ItemStack object nbt vs get/setItemStack nbt + +```java +// Saving ReadWriteNBT nbt = NBT.itemStackToNBT(itemStack); -// NBT to ItemStack -ItemStack itemStack = NBT.itemStackFromNBT(nbt); -// ItemStack Array to NBT ReadWriteNBT nbt = NBT.itemStackArrayToNBT(itemStacks); -// NBT to ItemStack Array +// Restoring +ItemStack itemStack = NBT.itemStackFromNBT(nbt); ItemStack[] itemStacks = NBT.itemStackArrayFromNBT(nbt); -// Creating a new NBT tag -ReadWriteNBT nbt = NBT.createNBTObject(); -// Parsing a Mojang-Json String to NBT -ReadWriteNBT nbt = NBT.parseNBT(json); - ``` -## Old style of creating a NBT Wrapper +#### Tiles/Entities + +// TODO is there a more elegant solution? ```java -NBTItem nbti = new NBTItem(ItemStack); - -NBTEntity nbtent = new NBTEntity(Entity); // Vanilla tags only! - -NBTTileEntity tent = new NBTTileEntity(block.getState()); // Vanilla tags only! - -NBTFile file = new NBTFile(new File("directory"), "test.nbt")); // Will be created at ./directory/test.nbt - -NBTContainer container = new NBTContainer(json); // Parse in json - -NBTContainer container = new NBTContainer(); // Empty NBTCompound +// Saving +ReadWriteNBT entityNbt = NBT.parseNBT(NBT.get(entity, (String) nbt -> nbt.toString())); +// Restoring +NBT.modify(entity, nbt -> { + // You might want also to filter out entityNbt first, + // e.g. remove some data like location, uuid, entityId, etc. + nbt.mergeCompound(entityNbt); +}); ``` -## Using the wrapper(NBTCompound/) - +#### Game profiles ```java -//Set -nbti.setString("Stringtest", "Teststring"); -nbti.setInteger("Inttest", 42); -nbti.setDouble("Doubletest", 1.5d); -nbti.setBoolean("Booleantest", true); -//More are available! Ask your IDE for suggestions! Don't use deprecated methods! - -//Access/create lists -nbtent.getCompoundList("Attributes"); -nbtent.getStringList("Attributes"); -//The list will be created if it doesn't exist, there is no setter for lists! - -//Get -nbti.getString("Stringtest"); -nbti.getInteger("Inttest"); -nbti.getDouble("Doubletest"); -nbti.getBoolean("Booleantest"); -nbti.getKeys(); //Get all Tags -nbti.hasTag("Key"); -nbti.removeKey("Key"); - -nbti.getOrCreateCompound("subtag"); // Get or create a subtag - -NBTCompound comp = nbti.getCompound("subtag"); // Get the tag or null -B.mergeCompound(A); // Merge the data from compound A into B (Like the /data merge command) -comp.toString(); // Get the nbt as a Mojang-Json string +// Saving +ReadWriteNBT nbt = NBT.gameProfileToNBT(profile); +// Restoring +GameProfile profile = NBT.gameProfileFromNBT(nbt); ``` +### NBT proxies + +// TODO + +### Data converter utils + +// TODO diff --git a/wiki/Zombie-that-can-pick-up-loot-and-does-0.5-hearths-of-damage.md b/wiki/Zombie-that-can-pick-up-loot-and-does-0.5-hearths-of-damage.md deleted file mode 100644 index ba170e120..000000000 --- a/wiki/Zombie-that-can-pick-up-loot-and-does-0.5-hearths-of-damage.md +++ /dev/null @@ -1,14 +0,0 @@ -```java -Zombie zombie = (Zombie) b.getWorld().spawnEntity(b.getLocation().add(0, 1, 0), EntityType.ZOMBIE); -NBT.modify(zombie, nbt -> { - nbt.setByte("CanPickUpLoot", (byte) 1); - ReadWriteNBTCompoundList list = nbt.getCompoundList("Attributes"); - for(int i = 0; i < list.size(); i++){ - ReadWriteNBT lc = list.get(i); - if(lc.getString("Name").equals("generic.attackDamage")){ - lc.setDouble("Base", 0.5d); - } - } -}); -``` - diff --git a/wiki/_Footer.md b/wiki/_Footer.md index cec3c3a1e..16bed66bc 100644 --- a/wiki/_Footer.md +++ b/wiki/_Footer.md @@ -1,5 +1,5 @@ [tr7zw](https://github.com/tr7zw) -[SpigotMC](https://www.spigotmc.org/resources/nbt-api.7939/) [Modrinth](https://modrinth.com/plugin/nbtapi) -[Bukkit](https://dev.bukkit.org/projects/nbt-api) [Hangar](https://hangar.papermc.io/tr7zw/NBTAPI) +[SpigotMC](https://www.spigotmc.org/resources/nbt-api.7939/) +[Bukkit](https://dev.bukkit.org/projects/nbt-api) diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index c5f4c674f..d4ba9c3b7 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -1,21 +1,23 @@ [Home](https://github.com/tr7zw/Item-NBT-API/wiki) -[Using the NBT API](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API) [Using Maven](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Maven) / [Using Gradle](https://github.com/tr7zw/Item-NBT-API/wiki/Using-Gradle) +[FAQ](https://github.com/tr7zw/Item-NBT-API/wiki/FAQ) + ## Code Examples ### General -* [Converting Minecraft Objects to NBT and Strings](https://github.com/tr7zw/Item-NBT-API/wiki/Converting-Minecraft-Objects-to-NBT-and-Strings) -* [Merging Compounds](https://github.com/tr7zw/Item-NBT-API/wiki/Merging-Compounds-(Copy-the-data-from-one-onto-another-compound)) +* [Basics](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#basics-overview) +* [Items](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#working-with-items) +* [Tiles/Entities](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#working-with-tilesentities) +* [Blocks](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#working-with-blocks) -### Items - -* [Set a skull's skin using NBT API](https://github.com/tr7zw/Item-NBT-API/wiki/Set-a-skull's-skin-using-NBT-API) - -### Entities - -* [Zombie that can pick up loot and does 0.5 hearths of damage](https://github.com/tr7zw/Item-NBT-API/wiki/Zombie-that-can-pick-up-loot-and-does-0.5-hearths-of-damage) +### Extras +* [Example usages](https://github.com/tr7zw/Item-NBT-API/wiki/Example-Usages) +* [NBT files](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#nbt-files) +* [NBT objects](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#converting-minecraft-objects-to-nbt-and-strings) +* [NBT proxies](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#nbt-proxies) +* [Data converter utils](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#data-converter-utils)