Gestore dei profili di gioco

Avvertimento

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!

A GameProfile represents the profile of a player, including such data as a name, UUID, and other arbitrary data known as properties. SpongeAPI provides the GameProfileManager class to get, create, and fill GameProfiles. You may obtain an instance of the GameProfileManager using the following code.

import org.spongepowered.api.Sponge;
import org.spongepowered.api.profile.GameProfileManager;

GameProfileManager profileManager = Sponge.getServer().getGameProfileManager();

Retrieving GameProfiles

It is important to note that Sponge maintains a cache of GameProfiles to be used as a substitute to making a request to the Mojang API every time a GameProfile is requested. The methods for retrieving GameProfiles offer a boolean second argument determining whether the cache will be used. By default, the cache will be used when possible.

A GameProfile can be looked up using either a UUID or username. Note that the same profile will always be returned when looking up by UUID, but as usernames can be changed, this may not necessarily be the case when looking up by username.

Retrieving by username

import org.spongepowered.api.profile.GameProfile;

import java.util.concurrent.CompletableFuture;

CompletableFuture<GameProfile> futureGameProfile = profileManager.get("Notch");

Retrieving by UUID

import java.util.UUID;

CompletableFuture<GameProfile> futureGameProfile =
    profileManager.get(UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5"));

Suggerimento

You can also retrieve many GameProfiles at once using GameProfileManager#getAllById(Iterable<UUID>, boolean) or GameProfileManager#getAllByName(Iterable<String>, boolean). Both of these methods return CompletableFuture<Collection<GameProfile>>.

Note that each of these methods return some sort of CompletableFuture. This indicates that the GameProfile (or Collection<GameProfile>) may not be immediately available because of pending requests to the Mojang API. The Javadocs for CompletableFuture describe the full capabilities of the class, but we will focus on the get method for the purpose of this article.

To retrieve a GameProfile from a CompletableFuture<GameProfile, you can simply call the CompletableFuture#get method.

GameProfile gameProfile = futureGameProfile.get();

Avvertimento

If the GameProfile is not immediately available (such as if the cache is not being used or does not contain the GameProfile), then get will wait for the future to complete. For that reason, it is not advisable to use this on the main thread as it will halt the server. Alternatively, you can use the CompletableFuture#thenAccept(Consumer<? super T>) method to specify a Consumer to be run upon completion.

Creating GameProfiles

You can generate a new GameProfile using GameProfile#of(UUID, String). Note that the username does not necessarily need to correspond to the UUID of that player. Likewise, the UUID does not need to belong to a valid player.

GameProfile gameProfile = GameProfile.of(
        UUID.fromString("00000000-0000-0000-0000-000000000000"),
        "Herobrine");

Nota

It is not mandatory to specify the name of the GameProfile (null is a valid argument).

Filling GameProfiles

Filling a GameProfile completes the profile by fetching information like the player’s skin from the Mojang API. Note that if faked data like username is associated with a certain UUID, it will be replaced by the actual data from the Mojang API.

GameProfile filledProfile = profileManager.fill(gameProfile).get();

ProfileProperties

GameProfiles can be used to store arbitrary data about a player using ProfilePropertys. However, this cannot not be used as a permanent data store, as the data does not persist across server restarts. We can retrieve the properties of a GameProfile using the GameProfile#getPropertyMap() method, which returns a Multimap. From there, you can retrieve existing or store new ProfilePropertys, which are represented as a key value pair. To generate a new ProfileProperty, simply call the ProfileProperty#of(String, String) method. The third argument (signature) is optional. However, a valid signature from Mojang must be specified for certain properties.

import org.spongepowered.api.profile.property.ProfileProperty;

import java.util.Collection;

profile.getPropertyMap().put(
    "key", ProfileProperty.of("foo", "bar", null));
Collection<ProfileProperty> customProperties = profile.getPropertyMap().get("key");

GameProfileCache

You can also directly access the GameProfileCache used by Sponge to store GameProfiles. To do so, simply call the GameProfileManager#getCache() method. Using the GameProfileCache, you can look up GameProfiles, add newly constructed GameProfiles, and fill profiles with data stored in the cache.

import org.spongepowered.api.profile.GameProfileCache;

GameProfile fakeProfile =
    GameProfile.of(UUID.fromString("00000000-0000-0000-0000-000000000000"),
    "Herobrine");
GameProfileCache cache = profileManager.getCache();
cache.add(profile);

Suggerimento

GameProfileCache#add(GameProfile) also accepts a boolean second argument determining whether existing cache entries should be overwritten, and a Date third argument setting the expiry of the GameProfile.

If you ever decide you need to remove a GameProfile from the cache, you may call GameProfileCache#remove(GameProfile). If you need to remove all GameProfiles from the cache, you may call GameProfileCache#clear().

The GameProfileCache may also be set by plugins with the GameProfileManager#setCache(GameProfileCache) method. To restore the original cache, use the same method, passing in the result of GameProfileManager#getDefaultCache().