Merge pull request #287 from SoSeDiK/wiki

Small wiki changes
tr7zw · Jul 21, 2024 · 2079123 · 2079123
2 parents 5280ba8 + 31b17fe
commit 2079123
Show file tree

Hide file tree

Showing 5 changed files with 88 additions and 44 deletions.
diff --git 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
@@ -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
@@ -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
+<repositories>
+...
+<!-- CodeMC -->
+<repository>
+  <id>codemc-repo</id>
+  <url>https://repo.codemc.io/repository/maven-public/</url>
+  <layout>default</layout>
+</repository>
+...
+</repositories>
+```
+
 ```xml
 <dependency>
   <groupId>de.tr7zw</groupId>
@@ -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
-<repositories>
-...
-<!-- CodeMC -->
-<repository>
-<id>codemc-repo</id>
-<url>https://repo.codemc.io/repository/maven-public/</url>
-<layout>default</layout>
-</repository>
-...
-</repositories>
-```
-
 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
+<repositories>
+...
+<!-- CodeMC -->
+<repository>
+  <id>codemc-repo</id>
+  <url>https://repo.codemc.io/repository/maven-public/</url>
+  <layout>default</layout>
+</repository>
+...
+</repositories>
+```
+
 ```xml
 <dependency>
   <groupId>de.tr7zw</groupId>
@@ -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
-<repositories>
-...
-<!-- CodeMC -->
-<repository>
-<id>codemc-repo</id>
-<url>https://repo.codemc.io/repository/maven-public/</url>
-<layout>default</layout>
-</repository>
-...
-</repositories>
+###### 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
@@ -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
@@ -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