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