From fb56eef3558583614744dab9fc7b0a4b1734f64b Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sat, 5 Jul 2025 14:24:51 +0200 Subject: [PATCH 01/12] chore: update pdc docs --- src/content/docs/paper/dev/api/pdc.md | 76 +++++++++++++++++---------- 1 file changed, 47 insertions(+), 29 deletions(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index 4641e60ee..e55dc9d29 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -7,16 +7,16 @@ slug: paper/dev/pdc The Persistent Data Container (PDC) is a way to store custom data on a whole range of objects; such as items, entities, and block entities. The full list of classes that support the PDC are: +- [`ItemStack`](#itemstack) - [`Chunk`](#chunk) - [`World`](#world) - [`Entity`](#entity) - [`TileState`](#tilestate) - [`Structure`](#structure) -- [`ItemMeta`](#itemmeta) - [`GeneratedStructure`](#generatedstructure) - [`Raid`](#raid) - [`OfflinePlayer`](#offlineplayer) -- [`ItemStack`](#itemstack) +- [`ItemMeta`](#itemmeta) ## What is it used for? In the past, developers resorted to a variety of methods to store custom data on objects: @@ -37,10 +37,22 @@ which is the object you want to store the data on. The third is the data itself. // Create a NamespacedKey NamespacedKey key = new NamespacedKey(pluginInstance, "example-key"); -ItemStack item = ItemStack.of(Material.DIAMOND); -// ItemMeta implements PersistentDataHolder, so we can get the PDC from it -item.editMeta(meta -> { - meta.getPersistentDataContainer().set(key, PersistentDataType.STRING, "I love Tacos!"); +World world = Bukkit.getServer().getWorlds().getFirst(); + +PersistentDataContainer pdc = world.getPersistentDataContainer(); + +pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); +``` + +[`ItemStack`](jd:paper:org.bukkit.inventory.ItemStack) however doesn't have this method and instead requires you to use its builder-style consumer: +y +```java +NamespacedKey key = ...; // Retrieve the key from before + +ItemStack item = ItemType.DIAMOND.createItemStack(); +// ItemStack provides a util method, so we can directly edit its PDC +item.editPersistentDataContainer(pdc -> { + pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); }); ``` @@ -49,8 +61,9 @@ item.editMeta(meta -> { It is considered good practice to reuse `NamespacedKey` objects. They can be constructed with either: - A [`Plugin`](jd:paper:org.bukkit.plugin.Plugin) instance and a [`String`](jd:java:java.lang.String) identifier - A [`String`](jd:java:java.lang.String) namespace and a [`String`](jd:java:java.lang.String) identifier +- Some classes such as ItemStack and OfflinePlayer provide a read-only container "view" and other than ItemStack, OfflinePlayer has no other method to add data. -The first option is often preferred as it will automatically use the plugin's namespace; however, the second option can be used if you +The first option is often preferred as it will automatically use the plugin's name as namespace; however, the second option can be used if you want to use a different namespace or access the data from another plugin. ::: @@ -63,10 +76,10 @@ To get data from the PDC, you need to know the `NamespacedKey` and the `Persiste NamespacedKey key = new NamespacedKey(pluginInstance, "example-key"); ItemStack item = ...; // Retrieve the item from before -// Get the data from the PDC -PersistentDataContainer container = item.getItemMeta().getPersistentDataContainer(); -if (container.has(key, PersistentDataType.STRING)) { - String value = container.get(key, PersistentDataType.STRING); +// Get the data from the PDC. Do note that ItemStack provides a "view", which is read-only +PersistentDataContainerView containerView = item.getPersistentDataContainer(); +if (containerView.has(key, PersistentDataType.STRING)) { + String value = containerView.get(key, PersistentDataType.STRING); // Do something with the value player.sendMessage(Component.text(value)); } @@ -124,7 +137,14 @@ The `PersistentDataType`'s job is to "deconstruct" a complex data type into some Here is an example of how to do that for a UUID: ```java title="UUIDDataType.java" +@NullMarked public class UUIDDataType implements PersistentDataType { + + public static final UUIDDataType INSTANCE = new UUIDDataType(); + + // We just need a singleton, so there's no need to allow instantiation + private UUIDDataType() {} + @Override public Class getPrimitiveType() { return byte[].class; @@ -160,7 +180,7 @@ In order to use your own `PersistentDataType`, you must pass an instance of it t [`set`](jd:paper:org.bukkit.persistence.PersistentDataContainer#set(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType,C))/ [`has`](jd:paper:io.papermc.paper.persistence.PersistentDataContainerView#has(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType)) methods. ```java -container.set(key, new UUIDDataType(), uuid); +container.set(key, UUIDDataType.INSTANCE, uuid); ``` ::: @@ -178,6 +198,19 @@ E.g. Placing an ItemStack as a Block (with a TileState) ***does not*** copy over Objects that can have a PDC implement the [`PersistentDataHolder`](jd:paper:org.bukkit.persistence.PersistentDataHolder) interface and their PDC can be fetched with [`PersistentDataHolder#getPersistentDataContainer()`](jd:paper:org.bukkit.persistence.PersistentDataHolder#getPersistentDataContainer()). +- ##### [`ItemStack`](jd:paper:org.bukkit.inventory.ItemStack) + - The persistent data container of an `ItemStack` has historically been accessed by + the `ItemStack`'s `ItemMeta`. This, however, includes the overhead of constructing the entire `ItemMeta`, which acts as a snapshot of the `ItemStack`'s data at the point of creation. + + To avoid this overhead, ItemStack exposes a read-only view of its persistent data container at `ItemStack#getPersistentDataContainer()`. + Edits to the persistent data container can be achieved via `ItemStack#editPersistentDataContainer(Consumer)`. + The persistent data container available in the consumer is not valid outside the consumer. + ```java + ItemStack itemStack = ...; + itemStack.editPersistentDataContainer(pdc -> { + pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); + }); + ``` - ##### [`Chunk`](jd:paper:org.bukkit.Chunk) - `Chunk#getPersistentDataContainer()` - ##### [`World`](jd:paper:org.bukkit.World) @@ -196,8 +229,6 @@ and their PDC can be fetched with [`PersistentDataHolder#getPersistentDataContai ``` - ##### [`Structure`](jd:paper:org.bukkit.structure.Structure) - `Structure#getPersistentDataContainer()` -- ##### [`ItemMeta`](jd:paper:org.bukkit.inventory.meta.ItemMeta) - - `ItemMeta#getPersistentDataContainer()` - ##### [`GeneratedStructure`](jd:paper:org.bukkit.generator.structure.GeneratedStructure) - `GeneratedStructure#getPersistentDataContainer()` - ##### [`Raid`](jd:paper:org.bukkit.Raid) @@ -205,18 +236,5 @@ and their PDC can be fetched with [`PersistentDataHolder#getPersistentDataContai - ##### [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer) - OfflinePlayer only exposes a read-only version of the persistent data container. It can be accessed via `OfflinePlayer#getPersistentDataContainer()`. -- ##### [`ItemStack`](jd:paper:org.bukkit.inventory.ItemStack) - - The persistent data container of an `ItemStack` has historically been accessed by - the `ItemStack`'s `ItemMeta`. This, however, includes the overhead of constructing the entire - `ItemMeta`, which acts as a snapshot of the `ItemStack`'s data at the point of creation. - - To avoid this overhead, ItemStack exposes a read-only view of its persistent data container at - `ItemStack#getPersistentDataContainer()`. - Edits to the persistent data container can be achieved via `ItemStack#editPersistentDataContainer(Consumer)`. - The persistent data container available in the consumer is not valid outside the consumer. - ```java - ItemStack itemStack = ...; - itemStack.editPersistentDataContainer(pdc -> { - pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); - }); - ``` +- ##### [`ItemMeta`](jd:paper:org.bukkit.inventory.meta.ItemMeta) + - `ItemMeta#getPersistentDataContainer()` From a232b079718a340aea75a857232a917782468db6 Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sat, 5 Jul 2025 15:15:44 +0200 Subject: [PATCH 02/12] chore: improve writing --- src/content/docs/paper/dev/api/pdc.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index e55dc9d29..d2d66728c 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -61,9 +61,10 @@ item.editPersistentDataContainer(pdc -> { It is considered good practice to reuse `NamespacedKey` objects. They can be constructed with either: - A [`Plugin`](jd:paper:org.bukkit.plugin.Plugin) instance and a [`String`](jd:java:java.lang.String) identifier - A [`String`](jd:java:java.lang.String) namespace and a [`String`](jd:java:java.lang.String) identifier -- Some classes such as ItemStack and OfflinePlayer provide a read-only container "view" and other than ItemStack, OfflinePlayer has no other method to add data. +- Certain classes, like `ItemStack` or [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer), provide a read-only view of their PDC. +In contrast to `ItemStack`, `OfflinePlayer` does __not__ provide any way to modify the underlying container. -The first option is often preferred as it will automatically use the plugin's name as namespace; however, the second option can be used if you +The first option is often preferred as it will automatically use the plugin's lowercased name as namespace; however, the second option can be used if you want to use a different namespace or access the data from another plugin. ::: From 938df9a4c868630188cda52cd15aa4916b4fef90 Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sat, 5 Jul 2025 15:21:36 +0200 Subject: [PATCH 03/12] fix: underline tag + typo --- src/content/docs/paper/dev/api/pdc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index d2d66728c..f7010a378 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -45,7 +45,7 @@ pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); ``` [`ItemStack`](jd:paper:org.bukkit.inventory.ItemStack) however doesn't have this method and instead requires you to use its builder-style consumer: -y + ```java NamespacedKey key = ...; // Retrieve the key from before @@ -62,7 +62,7 @@ It is considered good practice to reuse `NamespacedKey` objects. They can be con - A [`Plugin`](jd:paper:org.bukkit.plugin.Plugin) instance and a [`String`](jd:java:java.lang.String) identifier - A [`String`](jd:java:java.lang.String) namespace and a [`String`](jd:java:java.lang.String) identifier - Certain classes, like `ItemStack` or [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer), provide a read-only view of their PDC. -In contrast to `ItemStack`, `OfflinePlayer` does __not__ provide any way to modify the underlying container. +In contrast to `ItemStack`, `OfflinePlayer` does not provide any way to modify the underlying container. The first option is often preferred as it will automatically use the plugin's lowercased name as namespace; however, the second option can be used if you want to use a different namespace or access the data from another plugin. From 4be6a5baa5025565188eea617cdf033f9e7387ec Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sat, 5 Jul 2025 15:54:34 +0200 Subject: [PATCH 04/12] chore: add version information --- src/content/docs/paper/dev/api/pdc.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index f7010a378..bd303fc45 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -2,6 +2,7 @@ title: Persistent data container (PDC) description: A guide to the PDC API for storing data. slug: paper/dev/pdc +version: "Up to 1.21.5" --- The Persistent Data Container (PDC) is a way to store custom data on a whole range of objects; such as items, entities, and block entities. @@ -49,12 +50,15 @@ pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); ```java NamespacedKey key = ...; // Retrieve the key from before +// For 1.20.4 and below, use new ItemStack(Material.DIAMOND) instead ItemStack item = ItemType.DIAMOND.createItemStack(); // ItemStack provides a util method, so we can directly edit its PDC item.editPersistentDataContainer(pdc -> { pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); }); ``` +Note: The [`ItemStack#editPersistentDataContainer()`](jd:org.bukkit.inventory.ItemStack#editPersistentDataContainer()) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. +For 1.16.5+, there's the [`ItemStack#editMeta()`](jd:org.bukkit.inventory.ItemStack#editMeta(Consumer)) method though. :::note @@ -85,6 +89,7 @@ if (containerView.has(key, PersistentDataType.STRING)) { player.sendMessage(Component.text(value)); } ``` +Note: The [`ItemStack#getPersistentDataContainer()`](jd:org.bukkit.inventory.ItemStack#getPersistentDataContainer()) method on `ItemStack` is only available in 1.21.1+. For older versions, you need to access and modify the `ItemMeta` instead. ## Data types @@ -203,8 +208,8 @@ and their PDC can be fetched with [`PersistentDataHolder#getPersistentDataContai - The persistent data container of an `ItemStack` has historically been accessed by the `ItemStack`'s `ItemMeta`. This, however, includes the overhead of constructing the entire `ItemMeta`, which acts as a snapshot of the `ItemStack`'s data at the point of creation. - To avoid this overhead, ItemStack exposes a read-only view of its persistent data container at `ItemStack#getPersistentDataContainer()`. - Edits to the persistent data container can be achieved via `ItemStack#editPersistentDataContainer(Consumer)`. + To avoid this overhead in 1.21.1+, ItemStack exposes a read-only view of its persistent data container at `ItemStack#getPersistentDataContainer()`. + Edits to the persistent data container can also be simplified in 1.21.4+ using `ItemStack#editPersistentDataContainer(Consumer)`. The persistent data container available in the consumer is not valid outside the consumer. ```java ItemStack itemStack = ...; From 3e40d6d3ee661d8aff326ded36fc88d0bef398a6 Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sat, 5 Jul 2025 16:02:52 +0200 Subject: [PATCH 05/12] fix: formatting --- src/content/docs/paper/dev/api/pdc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index bd303fc45..497a2490e 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -50,7 +50,7 @@ pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); ```java NamespacedKey key = ...; // Retrieve the key from before -// For 1.20.4 and below, use new ItemStack(Material.DIAMOND) instead +// For 1.20.4 and below, use 'new ItemStack(Material.DIAMOND)' instead ItemStack item = ItemType.DIAMOND.createItemStack(); // ItemStack provides a util method, so we can directly edit its PDC item.editPersistentDataContainer(pdc -> { From abfd04b5644684505514733a2b0f4f9105cc995e Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sat, 5 Jul 2025 22:36:04 +0200 Subject: [PATCH 06/12] chore: improve version info --- src/content/docs/paper/dev/api/pdc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index 497a2490e..8b0fc96fc 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -2,7 +2,7 @@ title: Persistent data container (PDC) description: A guide to the PDC API for storing data. slug: paper/dev/pdc -version: "Up to 1.21.5" +version: "1.21.4 and below" --- The Persistent Data Container (PDC) is a way to store custom data on a whole range of objects; such as items, entities, and block entities. From d95441d63b6728c1f74bb78b3cb47aa25ce14267 Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sun, 6 Jul 2025 09:10:33 +0200 Subject: [PATCH 07/12] chore: move read only note --- src/content/docs/paper/dev/api/pdc.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index 8b0fc96fc..8694c610d 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -65,8 +65,6 @@ For 1.16.5+, there's the [`ItemStack#editMeta()`](jd:org.bukkit.inventory.ItemSt It is considered good practice to reuse `NamespacedKey` objects. They can be constructed with either: - A [`Plugin`](jd:paper:org.bukkit.plugin.Plugin) instance and a [`String`](jd:java:java.lang.String) identifier - A [`String`](jd:java:java.lang.String) namespace and a [`String`](jd:java:java.lang.String) identifier -- Certain classes, like `ItemStack` or [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer), provide a read-only view of their PDC. -In contrast to `ItemStack`, `OfflinePlayer` does not provide any way to modify the underlying container. The first option is often preferred as it will automatically use the plugin's lowercased name as namespace; however, the second option can be used if you want to use a different namespace or access the data from another plugin. @@ -191,6 +189,15 @@ container.set(key, UUIDDataType.INSTANCE, uuid); ::: + +## Read-only containers +:::note + +Certain classes, like `ItemStack` or [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer), provide a read-only view of their PDC. +In contrast to `ItemStack`, `OfflinePlayer` does not provide any way to modify the underlying container. + +::: + ## Storing on different objects :::caution From 65610cc0a23ff5214e861f561e3afcfe1c96b47c Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sun, 6 Jul 2025 13:33:01 +0200 Subject: [PATCH 08/12] chore: formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fix: javadoc links Co-authored-by: Matouš Kučera --- src/content/docs/paper/dev/api/pdc.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index 8694c610d..5f499d4c0 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -57,8 +57,12 @@ item.editPersistentDataContainer(pdc -> { pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); }); ``` -Note: The [`ItemStack#editPersistentDataContainer()`](jd:org.bukkit.inventory.ItemStack#editPersistentDataContainer()) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. -For 1.16.5+, there's the [`ItemStack#editMeta()`](jd:org.bukkit.inventory.ItemStack#editMeta(Consumer)) method though. +:::note + +The [`ItemStack#editPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#editPersistentDataContainer()) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. +For 1.16.5+, there's the [`ItemStack#editMeta()`](jd:paper:org.bukkit.inventory.ItemStack#editMeta(Consumer)) method though. + +::: :::note From 6803f6a172e88a05aff84d34eab07d0af86189fe Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sun, 6 Jul 2025 13:35:42 +0200 Subject: [PATCH 09/12] chore: >admonitions --- src/content/docs/paper/dev/api/pdc.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index 5f499d4c0..e25bbbe3f 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -57,6 +57,7 @@ item.editPersistentDataContainer(pdc -> { pdc.set(key, PersistentDataType.STRING, "I love Tacos!"); }); ``` + :::note The [`ItemStack#editPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#editPersistentDataContainer()) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. @@ -91,7 +92,12 @@ if (containerView.has(key, PersistentDataType.STRING)) { player.sendMessage(Component.text(value)); } ``` -Note: The [`ItemStack#getPersistentDataContainer()`](jd:org.bukkit.inventory.ItemStack#getPersistentDataContainer()) method on `ItemStack` is only available in 1.21.1+. For older versions, you need to access and modify the `ItemMeta` instead. + +:::note + +The [`ItemStack#getPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#getPersistentDataContainer()) method on `ItemStack` is only available in 1.21.1+. For older versions, you need to access and modify the `ItemMeta` instead. + +::: ## Data types From bb725f5776d184bea90a44e9b746e0e7c304ca52 Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sun, 6 Jul 2025 13:36:47 +0200 Subject: [PATCH 10/12] fix: javadoc --- src/content/docs/paper/dev/api/pdc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index e25bbbe3f..a22bbc7fb 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -60,7 +60,7 @@ item.editPersistentDataContainer(pdc -> { :::note -The [`ItemStack#editPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#editPersistentDataContainer()) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. +The [`ItemStack#editPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#editPersistentDataContainer(Consumer)) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. For 1.16.5+, there's the [`ItemStack#editMeta()`](jd:paper:org.bukkit.inventory.ItemStack#editMeta(Consumer)) method though. ::: From 76e717a03038422146f1a0e7b1f7e34a70e0dd47 Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sun, 6 Jul 2025 13:42:43 +0200 Subject: [PATCH 11/12] fix: javadoc - need to specify consumer class --- src/content/docs/paper/dev/api/pdc.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index a22bbc7fb..c52f50bc8 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -60,8 +60,8 @@ item.editPersistentDataContainer(pdc -> { :::note -The [`ItemStack#editPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#editPersistentDataContainer(Consumer)) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. -For 1.16.5+, there's the [`ItemStack#editMeta()`](jd:paper:org.bukkit.inventory.ItemStack#editMeta(Consumer)) method though. +The [`ItemStack#editPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#editPersistentDataContainer(java.util.function.Consumer)) method on `ItemStack` is only available in 1.21.4+. For older versions, you need to access and modify the `ItemMeta` instead. +For 1.16.5+, there's the [`ItemStack#editMeta()`](jd:paper:org.bukkit.inventory.ItemStack#editMeta(java.util.function.Consumer)) method though. ::: @@ -226,7 +226,7 @@ and their PDC can be fetched with [`PersistentDataHolder#getPersistentDataContai the `ItemStack`'s `ItemMeta`. This, however, includes the overhead of constructing the entire `ItemMeta`, which acts as a snapshot of the `ItemStack`'s data at the point of creation. To avoid this overhead in 1.21.1+, ItemStack exposes a read-only view of its persistent data container at `ItemStack#getPersistentDataContainer()`. - Edits to the persistent data container can also be simplified in 1.21.4+ using `ItemStack#editPersistentDataContainer(Consumer)`. + Edits to the persistent data container can also be simplified in 1.21.4+ using `ItemStack#editPersistentDataContainer(java.util.function.Consumer)`. The persistent data container available in the consumer is not valid outside the consumer. ```java ItemStack itemStack = ...; From 074bce96665bf9f0ee8cfa58ce86bb5264ab0967 Mon Sep 17 00:00:00 2001 From: Timon Seidel Date: Sun, 6 Jul 2025 16:11:58 +0200 Subject: [PATCH 12/12] feat: expand read-only section --- src/content/docs/paper/dev/api/pdc.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/content/docs/paper/dev/api/pdc.md b/src/content/docs/paper/dev/api/pdc.md index c52f50bc8..bfdf25d0f 100644 --- a/src/content/docs/paper/dev/api/pdc.md +++ b/src/content/docs/paper/dev/api/pdc.md @@ -203,8 +203,11 @@ container.set(key, UUIDDataType.INSTANCE, uuid); ## Read-only containers :::note -Certain classes, like `ItemStack` or [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer), provide a read-only view of their PDC. +- Certain classes, like `ItemStack` or [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer), provide a read-only view of their PDC. In contrast to `ItemStack`, `OfflinePlayer` does not provide any way to modify the underlying container. +- This is because the `OfflinePlayer` is directly read from disk and would require a blocking file operation. +Mutable objects, like the `PersistentDataHolder#getPersistentDataContainer()`, generally need to be re-saved even without modification or monitored. +That's why it's better to use unmodifiable "views" for read-only operations. :::