Merge pull request #282 from SoSeDiK/wiki

Update wiki
tr7zw · Jun 20, 2024 · ffa6126 · ffa6126
2 parents 2e20af4 + 7396821
commit ffa6126
Show file tree

Hide file tree

Showing 15 changed files with 618 additions and 230 deletions.
diff --git 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
@@ -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
diff --git a/wiki/Example-Usages.md b/wiki/Example-Usages.md
@@ -0,0 +1,122 @@
+## Set a skull's skin
+
+#### We will be using [this head](https://minecraft-heads.com/custom-heads/head/28194-cup-of-soda) as example.
+
+```java
+// This is the base64 texture value from the bottom of the previously mentioned website.
+final String textureValue = "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTQyY2M5MjAzYzkwYjg5YmRhYzFkZjI4NDE2NzI2NmI5NTNkZmViZjNjNDY5MGE3Y2QwYjE1NzkxYTYyZTU4MiJ9fX0=";
+
+
+// Creating ItemStack
+
+// For Minecraft 1.12.2 and below
+final ItemStack item = new ItemStack(Material.SKULL_ITEM);
+item.setDurability((short) 3);
+
+// For Minecraft 1.13 and newer
+final ItemStack item = new ItemStack(Material.PLAYER_HEAD);
+
+
+// Applying nbt
+
+// For Minecraft 1.20.4 and below
+NBT.modify(item, nbt -> {
+    ReadWriteNBT skullOwnerCompound = nbt.getOrCreateCompound("SkullOwner");
+
+    // The owner UUID. Note that skulls with the same UUID but different textures will misbehave and only one texture will load.
+    // They will share the texture. To avoid this limitation, it is recommended to use a random UUID.
+    skullOwnerCompound.setUUID("Id", UUID.randomUUID());
+
+    skullOwnerCompound.getOrCreateCompound("Properties")
+        .getCompoundList("textures")
+        .addCompound()
+        .setString("Value", textureValue);
+});
+
+// Workaround for Minecraft 1.20.5+
+NBT.modifyComponents(item, nbt -> {
+    ReadWriteNBT profileNbt = nbt.getOrCreateCompound("minecraft:profile");
+    profileNbt.setUUID("id", uuid);
+    ReadWriteNBT propertiesNbt = profileNbt.getCompoundList("properties").addCompound();
+    propertiesNbt.setString("name", "textures");
+    propertiesNbt.setString("value", textureValue);
+});
+```
+
+> [!TIP]
+> If you are using Paper API on 1.12.2+, you may use the following code to create textured skulls
+
+```java
+SkullMeta meta = (SkullMeta) item.getItemMeta();
+PlayerProfile playerProfile = Bukkit.createProfile(uuid);
+playerProfile.setProperty(new ProfileProperty("textures", textureValue));
+meta.setPlayerProfile(playerProfile);
+// You can also use item.editMeta(SkullMeta.class, meta -> {}); on 1.17+
+item.setItemMeta(meta);
+```
+
+## Zombie that can pick up loot and does 0.5 hearts of damage
+
+This code should serve only as a reference, the nbt structure might change between versions.
+
+```java
+Zombie zombie = location.getWorld().spawn(location, Zombie.class);
+
+String attributeName = "minecraft:generic.attack_damage"; // Or generic.attackDamage prior to 1.16
+double damageValue = 0.5;
+
+// Modify vanilla data
+NBT.modify(zombie, nbt -> {
+    nbt.setBoolean("CanPickUpLoot", true);
+
+    ReadWriteNBTCompoundList list = nbt.getCompoundList("Attributes");
+
+    // Check if zombie already has attribute set. If so, modify it
+    for (ReadWriteNBT listEntryNbt : list) {
+        if (!listEntryNbt.getString("Name").equals(attributeName)) continue;
+
+        listEntryNbt.setDouble("Base", damageValue);
+
+        return;
+    }
+
+    // Attribute is missing, add it instead
+    ReadWriteNBT listEntryNbt = list.addCompound();
+    listEntryNbt.setString("Name", attributeName);
+    listEntryNbt.setDouble("Base", damageValue);
+});
+
+// Modify custom data
+NBT.modifyPersistentData(zombie, nbt -> {
+    // Let's mark our zombie as a custom one
+    nbt.setBoolean("custom_zombie", true);
+});
+```
+
+## Reading world data
+
+```java
+// Get main world's folder
+File worldDataFolder = Bukkit.getWorlds().getFirst().getWorldFolder();
+
+// Read level data
+NBTFile levelNbtFile = new NBTFile(new File(worldDataFolder, "level.dat"));
+
+// Obtain world name
+String worldName = levelNbtFile.resolveOrNull("Data.LevelName", String.class);
+
+// Read some player's data
+UUID playerUuid;
+File playerFile = new File(worldDataFolder, "playerdata/" + playerUuid + ".dat");
+if (!playerFile.exists()) {
+    // No offline player data for provided uuid
+    return;
+}
+
+NBTFile playerNbtFile = new NBTFile(playerFile);
+
+// Change player's health
+float health = playerNbtFile.getFloat("Health");
+playerNbtFile.setFloat("Health", health + 5);
+```
+
diff --git a/wiki/FAQ.md b/wiki/FAQ.md
@@ -0,0 +1,26 @@
+## Frequently Asked Questions
+
+### I've updated NBT-API, but it keeps saying that it's outdated
+
+Some other plugin on your server has a shaded version of NBT-API. Try looking at the logs to find out which plugin is it, or add/remove your plugins until you find a culprit.
+
+### I've installed 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
@@ -1,26 +1,17 @@
-# 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)).
 
-Full JavaDoc can be found [here](https://tr7zw.github.io/Item-NBT-API/v2-api/)!
+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).
 
 ### 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
-
-* 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!
+You might also want to check out some [plugins that use NBT-API](https://github.com/tr7zw/Item-NBT-API/wiki/Plugins).
 
 ### 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
diff --git a/wiki/Plugins.md b/wiki/Plugins.md
@@ -1,10 +1,11 @@
-## 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)
 - [CommandAPI](https://github.com/JorelAli/CommandAPI)
 - [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/Set-a-skull's-skin-using-NBT-API.md b/wiki/Set-a-skull's-skin-using-NBT-API.md
diff --git a/wiki/Using-Gradle.md b/wiki/Using-Gradle.md
@@ -1,12 +1,17 @@
+To start using NB-API, you either need to depend on its plugin version, or shade (include) it inside your plugin.
+
+> [!IMPORTANT]
+> Plugin and shaded versions have different ``artifactId``. Make sure to correctly choose the one you need!
+
 # Option 1) NBT-API as a dependency
 
-Add the following Entries to your Gradle build at the correct location:
+Add the following entries to your Gradle build at the correct locations:
 
 ```groovy
 compileOnly("de.tr7zw:item-nbt-api-plugin:VERSION")
 ```
 
-(Get the current Version from [here](https://www.spigotmc.org/resources/nbt-api.7939/))
+(Get the current ``VERSION`` from [here](https://modrinth.com/plugin/nbtapi/versions))
 
 ```groovy
 repositories {
@@ -19,7 +24,7 @@ repositories {
 }
 ```
 
-Finally, add the API as dependency to your ``plugin.yml``
+Add the API as dependency to your ``plugin.yml``:
 
 ```yml
 depend: [NBTAPI]
@@ -38,15 +43,17 @@ plugins {
 ```
 
 The latest version of the shadow plugin can be found [here](https://github.com/johnrengelman/shadow/releases).
-<br/>
 
 Add NBT-API to your dependencies:
 
 ```groovy
 implementation("de.tr7zw:item-nbt-api:VERSION")
 ```
 
-(Get the current Version from [here](https://www.spigotmc.org/resources/nbt-api.7939/))
+(Get the current ``VERSION`` from [here](https://modrinth.com/plugin/nbtapi/versions))
+
+> [!WARNING]
+> Make sure you're using ``item-nbt-api`` as ``artifactId``, never shade the ``-plugin`` artifact!
 
 ```groovy
 repositories {
@@ -59,15 +66,15 @@ repositories {
 }
 ```
 
-After this you can add the shadowjar configuration to relocate the api package:
+After this you can add the shadowJar configuration to relocate the API package:
 
 ```groovy
 shadowJar {
     relocate("de.tr7zw.changeme.nbtapi", "YOUR PACKAGE WHERE THE API SHOULD END UP")
 }
 ```
 
-If you want to run the shadowJar task when the build task is executed, you can write like this:
+If you want to run the shadowJar task when the build task is executed, you can use this:
 
 ```groovy
 build {