Skip to content

API 8 Data (Part 2) #1010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: stable
Choose a base branch
from
Open

API 8 Data (Part 2) #1010

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8b49d53
addressed comments
mosemister Aug 19, 2024
a015552
missing import
mosemister Aug 19, 2024
85d38a9
Merge branch 'stable' of https://github.com/SpongePowered/SpongeDocs …
mosemister Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 18 additions & 12 deletions source/plugin/data/customdata.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Custom Data
org.spongepowered.api.data.persistence.DataQuery
org.spongepowered.api.data.persistence.DataSerializable
org.spongepowered.api.data.persistence.DataStore
org.spongepowered.api.data.DataProvider
org.spongepowered.api.data.value.MapValue
org.spongepowered.api.data.value.Value
org.spongepowered.api.entity.Entity
Expand Down Expand Up @@ -99,12 +100,15 @@ the :javadoc:`DataBuilder` which can be implemented as follows:
Registration
============

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.
All data needs to be registered before the Minecraft registers freeze, therefore the event of :javadoc:`RegisterDataEvent`
exsits for your plugin to register custom data. Data is registered using the :javadoc:`DataRegistration` class that holds
your custom :javadoc:`Key`, custom :javadoc:`DataStore` and custom :javadoc:`DataProvider`.

To register a ``DataSerializable`` Sponge has the :javadoc:`RegisterDataEvent` event. This will allow you to register
your data with the appropriate ``DataHolder``
Data is required to be registered so that your custom data can be serialized/deserialize into persistence data containers,
such as Players, Entity, BlockEntity, ItemStacks, etc.

.. tip::
Not including either the DataStore or the DataProvider is valid, however your custom data will not persist across reboots

Simple Custom Data
==================
Expand All @@ -131,7 +135,7 @@ other developers access to your data manipulator.
import org.spongepowered.api.data.Key;
import org.spongepowered.api.data.value.Value;

ResourceKey resourceKey = ResourceKey(pluginContainer, "last_attacker_manipulator");
ResourceKey resourceKey = ResourceKey(pluginContainer, "last_attacker_data");
Key<? extends Value<LastAttackerDataSerilizable>> key = Key
.builder()
.key(resourceKey)
Expand All @@ -140,18 +144,18 @@ other developers access to your data manipulator.

.. warning::

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.

.. tip::

You can register a key for a specific element within a DataSerializable
You can register a key for a specific field within a DataSerializable

Data Store
==========

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``.
The :javadoc:`DataStore` is used to register your ``Key`` with the appropriate ``DataHolder`` so that Key knows how/where to store the custom data whenever
serializing/deserializing. The DataStore also is used to 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``.

.. code-block:: java

Expand Down Expand Up @@ -197,7 +201,7 @@ Data Provider

For data that requires more code to be used whenever the getter, setter, deleter are used will require the use of
a ``DataProvider``. With a ``dataProvider`` a plugin is able to manipulate how its data should be received, set, and
deleted automatically.
deleted automatically such as being stored to a external database.

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.
Expand Down Expand Up @@ -230,6 +234,8 @@ Data Registration

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.
Only the ``key`` is required, however not providing the ``store`` or the ``provider`` will mean that
data will not persist across reboots.

.. code-block:: java

Expand Down
Loading