Skip to content
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

updated User page #1014

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

updated User page #1014

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a3a10a
updated userManager
mosemister Oct 3, 2024
a92ffa3
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
44 changes: 18 additions & 26 deletions source/plugin/offline-userplayer-data.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,32 +2,21 @@
Offline Player Data
===================

.. warning::

These docs were written for SpongeAPI 7 and are likely out of date.
`If you feel like you can help update them, please submit a PR! <https://github.com/SpongePowered/SpongeDocs>`__


.. javadoc-import::
org.spongepowered.api.entity.living.player.Player
org.spongepowered.api.entity.living.player.server.ServerPlayer
org.spongepowered.api.entity.living.player.User
org.spongepowered.api.profile.GameProfileManager
org.spongepowered.api.service.ServiceManager
org.spongepowered.api.service.user.UserStorageService
org.spongepowered.api.user.UserManager

It may be necessary for plugins to access player data even when the player is offline.
You might think that ``Sponge.getServer().getPlayer()`` returning a :javadoc:`Player` can be used for this.
But since ``Player`` objects only exist for online players, another solution must be used.
You might think that ``Sponge.server().player()`` returning a :javadoc:`ServerPlayer` can be used for this.
But since all ``Player`` objects only exist for online players,
another solution must be used.

Some plugins store the relevant data themselves and associate the user by using the :javadoc:`GameProfileManager`.
But writing different code for offline and online users is not necessary.
The :javadoc:`ServiceManager` natively provides a service known as the :javadoc:`UserStorageService` which is capable
of returning :javadoc:`User` instances for ``Player``\s who are currently offline.
Since the ``Player`` interface extends ``User`` most methods you call on a ``Player`` are also available.

For example:

* ``#hasPermission(String permission)`` is available from both instances.
The :javadoc:`UserManager` is capable of returning :javadoc:`User` instances for ``Player``\s who are currently
offline.

Code Example
------------
Expand All @@ -38,23 +27,26 @@ Here's an example for a utility method that can be used to get a ``User``:

import java.util.Optional;
import java.util.UUID;
import java.util.concurrent;

import org.spongepowered.api.Sponge;
import org.spongepowered.api.entity.living.player.User;
import org.spongepowered.api.service.user.UserStorageService;
import org.spongepowered.api.user.UserManager;

public Optional<User> getUser(UUID uuid) {
Optional<UserStorageService> userStorage = Sponge.getServiceManager().provide(UserStorageService.class);
return userStorage.get().get(uuid);
public CompletableFuture<Optional<User>> getUser(UUID uuid) {
UserManager userManager = Sponge.server().userManager();
return userManager.load(uuid);
}

This code will get the ``UserStorageService`` from the ``ServiceManager`` and then retrieve the ``User`` from there.
This code will get the ``UserManager`` and then retrieve the ``User`` from there.

.. note::

The ``UserStorageService`` can only return ``User``\s who previously were connected.
The ``UserManager`` will use local cached versions of the user, however will contact Mojang servers if
the user has not previously joined, hence why the load returns a ``CompletableFuture``. If the user
cannot be found in either cache or Mojang then the ``CompletableFuture`` will return ``Optional.empty``

.. note::

This solution will not return ``Player`` instances. This makes it safe to store the returned ``User`` objects,
but you will need to use the ``User.getPlayer()`` method to retrieve the online entity.
You can check if the player is loaded in cache with the ``exists(UUID playerUuid)`` method found in
``UserManager``
Loading