diff --git a/wiki/Example-Usages.md b/wiki/Example-Usages.md
index 12a504e3a..c1d5090f9 100644
--- a/wiki/Example-Usages.md
+++ b/wiki/Example-Usages.md
@@ -118,5 +118,8 @@ NBTFile playerNbtFile = new NBTFile(playerFile);
// Change player's health
float health = playerNbtFile.getFloat("Health");
playerNbtFile.setFloat("Health", health + 5);
+
+// Once finished, save the file
+playerNbtFile.save();
```
diff --git a/wiki/Using-Gradle.md b/wiki/Using-Gradle.md
index 512f6f660..6242e276b 100644
--- a/wiki/Using-Gradle.md
+++ b/wiki/Using-Gradle.md
@@ -7,12 +7,6 @@ To start using NB-API, you either need to depend on its plugin version, or shade
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://modrinth.com/plugin/nbtapi/versions))
-
```groovy
repositories {
...
@@ -24,6 +18,12 @@ repositories {
}
```
+```groovy
+compileOnly("de.tr7zw:item-nbt-api-plugin:VERSION")
+```
+
+(Get the current ``VERSION`` from [here](https://modrinth.com/plugin/nbtapi/versions))
+
Add the API as dependency to your ``plugin.yml``:
```yml
@@ -46,15 +46,6 @@ The latest version of the shadow plugin can be found [here](https://github.com/j
Add NBT-API to your dependencies:
-```groovy
-implementation("de.tr7zw:item-nbt-api:VERSION")
-```
-
-(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 {
...
@@ -66,6 +57,15 @@ repositories {
}
```
+```groovy
+implementation("de.tr7zw:item-nbt-api:VERSION")
+```
+
+(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!
+
After this you can add the shadowJar configuration to relocate the API package:
```groovy
@@ -82,3 +82,19 @@ build {
}
```
+###### Initializing NBT-API early
+
+If you are shading NBT-API, you may call ``NBT.preloadApi()`` during ``onEnable`` to initialize NBT-API early and check whether everything works. If you omit this step, NBT-API will be initialized on the first call to the API.
+
+```java
+@Override
+public void onEnable() {
+ if (!NBT.preloadApi()) {
+ getLogger().warning("NBT-API wasn't initialized properly, disabling the plugin");
+ getPluginLoader().disablePlugin(this);
+ return;
+ }
+ // Load other things
+}
+```
+
diff --git a/wiki/Using-Maven.md b/wiki/Using-Maven.md
index b8de94259..3f6643bad 100644
--- a/wiki/Using-Maven.md
+++ b/wiki/Using-Maven.md
@@ -7,6 +7,19 @@ To start using NB-API, you either need to depend on its plugin version, or shade
Add the following entries to your pom at the correct locations:
+```xml
+
+...
+
+
+ codemc-repo
+ https://repo.codemc.io/repository/maven-public/
+ default
+
+...
+
+```
+
```xml
de.tr7zw
@@ -18,19 +31,6 @@ Add the following entries to your pom at the correct locations:
(Get the current ``VERSION`` from [here](https://modrinth.com/plugin/nbtapi/versions))
-```xml
-
-...
-
-
-codemc-repo
-https://repo.codemc.io/repository/maven-public/
-default
-
-...
-
-```
-
Add the API as dependency to your ``plugin.yml``:
```yaml
@@ -83,6 +83,19 @@ Replace ``YOUR PACKAGE WHERE THE API SHOULD END UP`` with your own unique packag
Then, add NBT-API to your dependencies by including the following entries to your pom at the correct locations:
+```xml
+
+...
+
+
+ codemc-repo
+ https://repo.codemc.io/repository/maven-public/
+ default
+
+...
+
+```
+
```xml
de.tr7zw
@@ -96,16 +109,19 @@ Then, add NBT-API to your dependencies by including the following entries to you
> [!WARNING]
> Make sure you're using ``item-nbt-api`` as ``artifactId``, never shade the ``-plugin`` artifact!
-```xml
-
-...
-
-
-codemc-repo
-https://repo.codemc.io/repository/maven-public/
-default
-
-...
-
+###### Initializing NBT-API early
+
+If you are shading NBT-API, you may call ``NBT.preloadApi()`` during ``onEnable`` to initialize NBT-API early and check whether everything works. If you omit this step, NBT-API will be initialized on the first call to the API.
+
+```java
+@Override
+public void onEnable() {
+ if (!NBT.preloadApi()) {
+ getLogger().warning("NBT-API wasn't initialized properly, disabling the plugin");
+ getPluginLoader().disablePlugin(this);
+ return;
+ }
+ // Load other things
+}
```
diff --git a/wiki/Using-the-NBT-API.md b/wiki/Using-the-NBT-API.md
index 71d5ccb17..9fbd0331f 100644
--- a/wiki/Using-the-NBT-API.md
+++ b/wiki/Using-the-NBT-API.md
@@ -128,6 +128,8 @@ boolean bar = nbt.resolveOrDefault("foo.other_key[0].bar", false);
### Working with items
+You can read/write nbt data on items using ``NBT.get``/``NBT.modify`` methods.
+
```java
// Setting data
NBT.modify(itemStack, nbt -> {
@@ -154,7 +156,14 @@ int someValue = NBT.modify(itemStack, nbt -> {
nbt.setInteger(i);
return i;
});
+```
+
+###### ItemMeta usage
+> [!WARNING]
+> Never mix the usage of ItemMeta and NBT.
+
+```java
// Updating ItemMeta using NBT
NBT.modify(itemStack, nbt -> {
nbt.setInteger("kills", nbt.getOrDefault("kills", 0) + 1);
@@ -180,9 +189,9 @@ NBT.modifyComponents(item, nbt -> {
});
```
-### Working with (block-)entities
+### Working with entities and block entities
-Working with entities and block entities is similar to working items.
+Working with entities and block entities is similar to working with items.
#### Accessing vanilla nbt
@@ -313,7 +322,7 @@ String json = nbt.toString();
ReadWriteNBT nbt = NBT.parseNBT(json);
```
-#### (Block-)Entities
+#### Entities and block entities
```java
// Saving
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index aec48fe19..8ce6f6e44 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -9,9 +9,9 @@
### General
-* [Basics](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#basics-overview)
+* [Basics](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API)
* [Items](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#working-with-items)
-* [Block-Entities/Entities](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#working-with-(block-)entities)
+* [Block-Entities/Entities](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#working-with-entities-and-block-entities)
* [Blocks](https://github.com/tr7zw/Item-NBT-API/wiki/Using-the-NBT-API#working-with-blocks)
### Extras