Persistent Data

What is persistent data and how to use it

persistentData is an NBT compound tag object available on players, levels, and servers.

It's useful for simple, persistent data storage.

Persistent Data does not use beans in 1.21+!

Here's an example of persistentData:

PlayerEvents.loggedIn(event => {
	const pData = event.player.persistentData
	if (!pData.getBoolean('firstJoin')) {
		pData.putBoolean('firstJoin', true)
		// Do stuff only on first join, here we give the player some diamonds and a sword
		event.player.give('29x diamond')
		event.player.give('minecraft:diamond_sword[damage=2]')
	}
})

PlayerEvents.loggedIn(event => {
  const pData = event.player.persistentData
  if (!pData.firstJoin) {
    pData.firstJoin = true
    // Do stuff only on first join, here we give the player some diamonds and a sword
    event.player.give('29x diamond')
    event.player.give('minecraft:diamond_sword[damage=2]')
  }
})

PlayerEvents.loggedIn(event => {
	const pData = event.player.persistentData
	if (!pData.firstJoin) {
		pData.firstJoin = true
		// Do stuff only on first join, here we give the player some diamonds and a sword
		event.player.give('29x diamond')
		event.player.give(Item.of('minecraft:diamond_sword', '{Damage:2}'))
	}
})

#NBT Compound methods

These are the methods usable on NBT compound tags like persistentData.

In code snippets below, compound will refer to the compound tag.

#Generic key access

compound.put(name, tag)
- name: The name of the key to put to.
- tag: The NBT tag to insert. Plain numbers and strings can also be inserted, being automatically wrapped into NBT tags.

Please note that JS numbers are doubles!

This is equivalent to the compound[name] = tag bean.

compound.get(name)
- name: The name of the key to get from.
- Returns: The NBT tag stored at that key.

This is equivalent to the const tag = compound[name] bean.

#Typed key access

Data type	Setter	Getter
Boolean	`compound.putBoolean(name, value)`	`compound.getBoolean(name)`
Byte	`compound.putByte(name, value)`	`compound.getByte(name)`
Byte array	`compound['putByteArray(java.lang.String,byte[])'](name, value)`	`compound.getByteArray(name)`
Double	`compound.putDouble(name, value)`	`compound.getDouble(name)`
Float	`compound.putFloat(name, value)`	`compound.getFloat(name)`
Integer	`compound.putInt(name, value)`	`compound.getInt(name)`
Integer array	`compound['putIntArray(java.lang.String,int[])'](name, value)`	`compound.getIntArray(name)`
Long	`compound.putLong(name, value)`	`compound.getLong(name)`
Long array	`compound['putLongArray(java.lang.String,long[])'](name, value)`	`compound.getLongArray(name)`
Short	`compound.putShort(name, value)`	`compound.getShort(name)`
String	`compound.putString(name, value)`	`compound.getString(name)`
UUID	`compound.putUUID(name, value)`	`compound.getUUID(name)`

name: The name of the key to get from/put to.
value: The value of the appropriate type. Type conversions will happen if necessary.
Getters return the appropriate value type.

If there's an attempt to read a different type than one actually stored at that key, the return value will be cast to the appropriate type if possible.

Conversions that succeed:
- UUIDs can be converted to integer arrays of exactly 4 elements, and vice versa.
- Number types can be cast between each other.
Conversions that fail:
- Conversion of a number type to string will result in an empty string.
- Conversion of a string into a number type will result in a 0.
- Conversion of between number arrays will result in an empty array.
- Conversion of any other type into UUID will result in an exception being thrown.

#Other useful methods

compound.getAllKeys()
- Returns: A set of the names of all keys in the compound tag.

compound.remove(name)
- name: The name of the key to remove from the tag.
- Returns: The NBT compound as string.

compound.getAsString()
compound.toString()
- Returns: The NBT compound as string.

compound.merge(otherCompound)
- otherCompound: Another NBT compound tag.
- Returns: The compound tag that is the result of merging two compound tags together.

compound.copy()
- Returns: A shallow clone of the compound tag.

compound.isEmpty()
- Returns: true if the compound tag is empty, false otherwise.

Also available as a bean: compound.empty.

compound.size()
- Returns: The number of keys in the compound tag.

compound.sizeInBytes()
- Returns: The size in bytes of the compound tag.