Conversation
mosemister
added
needs review
Inscrutable
left a comment
Inscrutable
left a comment
There was a problem hiding this comment.
Minor quibbles alone, great work again. And I concur we should bump it up an index level in the docs if you don't foresee the need to have any further pages in the section.
|
|
||
| Simple Custom Data | ||
| ================== | ||
|
|
There was a problem hiding this comment.
Maybe mention this earlier? No need to read how to create more complex custom data if you just want a string
There was a problem hiding this comment.
My thoughts was to learn how it works and then learn how to shortcut the process. But ill make it earlier
|
Not sure how this one got closed. Must be by accident |
| Registering your ``DataSerializable`` allows it to be accessible by Sponge and by other plugins in a generic way. The | ||
| game/plugin can create copies of your data and serialize/deserialize your data without referencing any of your classes | ||
| directly. | ||
|
|
||
| To register a ``DataSerializable`` Sponge has the :javadoc:`RegisterDataEvent` event. This will allow you to register | ||
| your data with the appropriate ``DataHolder`` |
There was a problem hiding this comment.
I'd almost reword this that the DataSerializable isn't the core intent of it being accessible, moreso that it's persisted to Minecraft's traditional data objects that can support custom data (Items, Entities, BlockEntities), accessible via the author's registered Key.
There was a problem hiding this comment.
Specifically mentioning that custom data is most easily accessible via Keys, DataSerializable is only one of two options to making data persisted.
| import org.spongepowered.api.data.Key; | ||
| import org.spongepowered.api.data.value.Value; | ||
|
|
||
| ResourceKey resourceKey = ResourceKey(pluginContainer, "last_attacker_manipulator"); |
There was a problem hiding this comment.
Maybe remove manipulator and use something more like last_attacker_data
|
|
||
| .. warning:: | ||
|
|
||
| Be sure to store your ``Key`` somewhere global so you can access it later. |
There was a problem hiding this comment.
| Be sure to store your ``Key`` somewhere global so you can access it later. | |
| Retain your ``Key`` reference readily available for later access, otherwise you incur additional processing expense recreating a new `Key` each time. |
Although, I'm unsure whether we use equality or ResourceKey equality for comparison.
|
|
||
| .. tip:: | ||
|
|
||
| You can register a key for a specific element within a DataSerializable |
There was a problem hiding this comment.
What does this mean? Can you clarify what element means? Are we talking about a field of an Object implementing DataSerializable?
| The :javadoc:`DataStore` is used to register your ``Key`` with the appropriate ``DataHolder`` and also register | ||
| any other keys you may have accessing your ``DataSerializable``. In the example below, it creates a ``DataStore`` | ||
| and makes it appliciable to only the :javadoc:`Entity` ``DataHolder``. |
There was a problem hiding this comment.
Mention how this is to enable the DataHolder's mode of persistence to know where/how to store the data backed by the Key in that automatic serialization and deserialization (based on whether it's simple or a DataSerializable kind).
| a ``DataProvider``. With a ``dataProvider`` a plugin is able to manipulate how its data should be received, set, and | ||
| deleted automatically. | ||
|
|
||
| In the following example, we will be getting the UUID from the last attacker but if there is no last attacker, then | ||
| return the player's UUID instead. |
There was a problem hiding this comment.
Also equally to enable external persistence of the Keyed data for a plugin to be able to consume/provide said data, such as a database.
| The final object you will need to register your data is the :javadoc:`DataRegistration` which combines | ||
| your ``Key``, ``DataStore`` and ``DataProvider`` together into a single package that you can register. | ||
|
|
||
| .. code-block:: java | ||
|
|
||
| import org.spongepowered.api.data.DataRegistration; | ||
|
|
||
| DataRegistration myData = DataRegistration.builder() | ||
| .key(key) | ||
| .store(datastore) | ||
| .provider(provider) | ||
| .build(); | ||
|
|
||
| event.register(myData); |
There was a problem hiding this comment.
Note that not including a store or provider means the data will simply be ephemeral and has no guarantees to the persistence of said data. This means if an Entity has some custom data offered, it will accept it, but not persist it.
|
Ill merge, but have a follow up pr soon addressing the comments |
4 participants
When it comes to user facing stuff on data, a lot of it is the same as API 7, therefore only imports and method names have changed.
However vanilla
DataManipulators have moved toSponge(common) instead of being expose to the API and the rangedValuehas also been removed. This has caused some major deletions and some examples to change.The largest change comes in custom data, whereby the custom
DataHolderhas been removed (as it wasnt even written in API 7) andSerializationas well asDataManipulators have been combined into a single page (as they have in the Sponge API). This has resulted in theCustomdrop down menu to only hold a single page, so I would be more then happy to bring theDataManipulatorpage up a parent and rename toCustom DataManipulator