SkinsRestorer API

Java plugins can use the public SkinsRestorer API to read and change skin data.

CAUTION: The API can change between releases. A new release can break your integration.

Resources

These resources contain complete API details and an example plugin:

Add to your build file

Select your build tool, then add the repository and dependency.

Use the latest version number without the v prefix:

Add the following repository and dependency to your pom.xml file:

<repositories>
  <repository>
    <id>codemc</id>
    <url>https://repo.codemc.org/repository/maven-public/</url>
  </repository>
</repositories>

<dependencies>
  <!-- SkinsRestorer API -->
  <dependency>
    <groupId>net.skinsrestorer</groupId>
    <artifactId>skinsrestorer-api</artifactId>
    <version>VERSION</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

Add SkinsRestorer as a dependency

Add SkinsRestorer as a plugin dependency. The server then loads SkinsRestorer before your plugin.

These examples use an optional dependency. Your plugin can load without SkinsRestorer, but API calls will fail.

If your build generates plugin metadata, add the dependency in the build tool instead.

Add the following dependency to your plugin.yml file:

softdepend: [ "SkinsRestorer" ]

Code examples

Getting the API instance

import net.skinsrestorer.api.SkinsRestorer;
import net.skinsrestorer.api.SkinsRestorerProvider;

public class MyPlugin extends JavaPlugin {
    private SkinsRestorer skinsRestorerAPI;

    @Override
    public void onEnable() {
        // Get the API instance
        this.skinsRestorerAPI = SkinsRestorerProvider.get();
    }
}

Setting a player's skin by name

import net.skinsrestorer.api.storage.PlayerStorage;
import net.skinsrestorer.api.storage.SkinStorage;
import net.skinsrestorer.api.property.InputDataResult;

public void setSkinByName(Player player, String skinName) {
    SkinStorage skinStorage = skinsRestorerAPI.getSkinStorage();
    PlayerStorage playerStorage = skinsRestorerAPI.getPlayerStorage();

    // Find or fetch the skin data
    Optional<InputDataResult> result = skinStorage.findOrCreateSkinData(skinName);

    if (result.isPresent()) {
        // Set the skin identifier for the player
        playerStorage.setSkinIdOfPlayer(
            player.getUniqueId(),
            result.get().getIdentifier()
        );

        // Apply the skin visually
        skinsRestorerAPI.getSkinApplier(Player.class).applySkin(player);
    }
}

Setting a skin from a URL

import net.skinsrestorer.api.connections.MineSkinAPI;
import net.skinsrestorer.api.connections.model.MineSkinResponse;
import net.skinsrestorer.api.property.SkinProperty;
import net.skinsrestorer.api.property.SkinVariant;

public void setSkinFromUrl(Player player, String url) {
    MineSkinAPI mineSkinAPI = skinsRestorerAPI.getMineSkinAPI();

    // Generate skin from URL (use CLASSIC or SLIM)
    MineSkinResponse response = mineSkinAPI.genSkin(url, SkinVariant.CLASSIC);
    SkinProperty skinProperty = response.getProperty();

    // Apply directly to player
    skinsRestorerAPI.getSkinApplier(Player.class).applySkin(player, skinProperty);
}

Getting a player's current skin

import net.skinsrestorer.api.property.SkinProperty;

public SkinProperty getPlayerSkin(Player player) {
    PlayerStorage playerStorage = skinsRestorerAPI.getPlayerStorage();

    Optional<SkinProperty> property = playerStorage.getSkinForPlayer(
        player.getUniqueId(),
        player.getName()
    );

    return property.orElse(null);
}

Creating a custom server skin

import net.skinsrestorer.api.property.SkinProperty;

public void createCustomSkin(String skinName, String value, String signature) {
    SkinStorage skinStorage = skinsRestorerAPI.getSkinStorage();

    // Create a skin property from raw data
    SkinProperty property = SkinProperty.of(value, signature);

    // Store it as a custom skin
    skinStorage.setCustomSkinData(skinName, property);
}

Getting the texture URL from skin data

import net.skinsrestorer.api.property.SkinProperty;
import net.skinsrestorer.api.PropertyUtils;

public String getTextureUrl(SkinProperty skinProperty) {
    return PropertyUtils.getSkinTextureUrl(skinProperty);
}

Checking API version compatibility

import net.skinsrestorer.api.VersionProvider;

public boolean isCompatible() {
    // Check if running at least version 15
    return VersionProvider.isCompatibleWith("15");
}

Use the API on a proxy network

On BungeeCord or Velocity, use one of these options:

Call the API from the proxy: Put your API plugin on BungeeCord or Velocity. Use plugin messages to communicate with plugins on backend servers.
Call the API from backend servers: Enable server.proxyMode.api on every backend server. Use the same MySQL database on the proxy and backend servers.

Error handling

Handle errors from API calls:

try {
    Optional<InputDataResult> result = skinStorage.findOrCreateSkinData(skinName);
    // ... handle result
} catch (DataRequestException e) {
    // Handle API/network errors
    getLogger().warning("Failed to fetch skin: " + e.getMessage());
}

Fix common API problems

If you see Cannot find symbol or Cannot resolve symbol, add the required imports.
Get the API with this.skinsRestorer = SkinsRestorerProvider.get();.
Add the private SkinsRestorer skinsRestorer; field to the class.
Add the dependency to the build file and plugin metadata.
On a backend server, enable server.proxyMode.api and use the proxy's MySQL database.

SkinsRestorer API

On this page