You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/paper/dev/api/pdc.md
+7-8Lines changed: 7 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -49,7 +49,6 @@ NamespacedKey key = ...; // Retrieve the key from before
49
49
50
50
// For 1.20.4 and below, use 'new ItemStack(Material.DIAMOND)' instead
51
51
ItemStack item =ItemStack.of(Material.DIAMOND);
52
-
// ItemStack provides a util method, so we can directly edit its PDC
53
52
item.editPersistentDataContainer(pdc -> {
54
53
pdc.set(key, PersistentDataType.STRING, "I love Tacos!");
55
54
});
@@ -68,13 +67,12 @@ It is considered good practice to reuse `NamespacedKey` objects. They can be con
68
67
- A [`Plugin`](jd:paper:org.bukkit.plugin.Plugin) instance and a [`String`](jd:java:java.lang.String) identifier
69
68
- A [`String`](jd:java:java.lang.String) namespace and a [`String`](jd:java:java.lang.String) identifier
70
69
71
-
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
72
-
want to use a different namespace or access the data from another plugin.
70
+
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.
73
71
74
72
:::
75
73
76
74
## Getting data
77
-
To get data from the PDC, you need to know the `NamespacedKey` and the `PersistentDataType` of the data.
75
+
To get data from the PDC, you need to know the `NamespacedKey` and the [`PersistentDataType`](jd:paper:org.bukkit.persistence.PersistentDataType) of the data.
78
76
Some API parts, such as Adventure's [`Component.text(String)`](https://jd.advntr.dev/api/latest/net/kyori/adventure/text/Component.html#text(java.lang.String)), require non-null values. In such cases, use the [`getOrDefault`](jd:paper:io.papermc.paper.persistence.PersistentDataContainerView#getOrDefault(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType,C)) on the pdc instead of [`get`](jd:paper:io.papermc.paper.persistence.PersistentDataContainerView#get(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType)), which is nullable.
79
77
80
78
```java
@@ -83,6 +81,7 @@ World world = ...; // Retrieve the world from before
Certain classes, like `ItemStack` or [`OfflinePlayer`](jd:paper:org.bukkit.OfflinePlayer), provide a read-only view of their PDC.
195
194
In contrast to `ItemStack`, `OfflinePlayer` does <u>not</u> provide any way to modify the underlying container.
196
195
This is because the `OfflinePlayer` is directly read from disk and would require a blocking file operation.
197
-
Mutable objects, like the `PersistentDataHolder#getPersistentDataContainer()`, generally need to be re-saved even without modification or monitored.
196
+
Mutable objects, like the [`PersistentDataHolder#getPersistentDataContainer()`](jd:paper:org.bukkit.persistence.PersistentDataHolder#getPersistentDataContainer()), generally need to be re-saved even without modification or monitored.
198
197
That's why it's better to use unmodifiable "views" for read-only operations.
199
198
200
199
```java
@@ -225,13 +224,13 @@ E.g. Placing an ItemStack as a Block (with a TileState) ***does not*** copy over
225
224
:::
226
225
227
226
Objects that can have a PDC implement the [`PersistentDataHolder`](jd:paper:org.bukkit.persistence.PersistentDataHolder) interface
228
-
and their PDC can be fetched with [`PersistentDataHolder#getPersistentDataContainer()`](jd:paper:org.bukkit.persistence.PersistentDataHolder#getPersistentDataContainer()).
227
+
and their PDC can be fetched with `PersistentDataHolder#getPersistentDataContainer()`.
- The persistent data container of an `ItemStack` has historically been accessed by
232
231
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.
233
232
234
-
To avoid this overhead in 1.21.1+, ItemStack exposes a read-only view of its persistent data container at `ItemStack#getPersistentDataContainer()`.
233
+
To avoid this overhead in 1.21.1+, ItemStack exposes a read-only view of its persistent data container at [`ItemStack#getPersistentDataContainer()`](jd:paper:org.bukkit.inventory.ItemStack#getPersistentDataContainer()).
235
234
Edits to the persistent data container can also be simplified in 1.21.4+ using `ItemStack#editPersistentDataContainer(java.util.function.Consumer)`.
236
235
The persistent data container available in the consumer is not valid outside the consumer.
0 commit comments