[WIP] Started updating wiki
This commit is contained in:
SoSeDiK committed
1 parent
25c59b0eae
commit
79ba1dd275
14 files changed
+348
-183
No files matched your search
@@ -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
|
||||
|
||||
|
||||
+2
-2
@@ -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:[, 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
|
||||
|
||||
|
||||
@@ -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);
|
||||
```
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
+26
@@ -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).
|
||||
+9
-16
@@ -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 [](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/)!
|
||||
@@ -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}"));
|
||||
});
|
||||
```
|
||||
|
||||
+4
-3
@@ -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`!
|
||||
@@ -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)
|
||||
}
|
||||
```
|
||||
|
||||
+3
-3
@@ -26,7 +26,7 @@ Add the following Entries to your pom at the correct location:
|
||||
</repositories>
|
||||
```
|
||||
|
||||
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
|
||||
<repositories>
|
||||
@@ -96,4 +97,3 @@ Example:
|
||||
<shadedPattern>com.yourname.pluginname.nbtapi</shadedPattern>
|
||||
</relocation>
|
||||
```
|
||||
|
||||
+262
-61
@@ -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<String> 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
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
+2
-2
@@ -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)
|
||||
+12
-10
@@ -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)
|
||||
Reference in new issue
Block a user