SkinsRestorer API

SkinsRestorer has a public API that can be used by other plugins to interact with SkinsRestorer.

Please note that this API is still work-in-progress. Expect breaking changes!

Resources

You can find useful resources to the SkinsRestorer API below:

Add to your build file

Here is an example of how to add the API to your build file. Select your build tool below.

Latest Version (Without the v):

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 the following repository and dependency to your build.gradle file:

repositories {
    maven {
        name 'codemc'
        url 'https://repo.codemc.org/repository/maven-public/'
    }
}

dependencies {
    // SkinsRestorer API
    compileOnly 'net.skinsrestorer:skinsrestorer-api:VERSION'
}

Add the following repository and dependency to your build.gradle.kts file:

repositories {
    maven("https://repo.codemc.org/repository/maven-public/") {
        name = "codemc"
    }
}

dependencies {
    // SkinsRestorer API
    compileOnly("net.skinsrestorer:skinsrestorer-api:VERSION")
}

Add SkinsRestorer as a dependency

If you want to use the API in your plugin, you will need to add SkinsRestorer as a dependency of your plugin. This is used, so SkinsRestorer is loaded BEFORE your plugin, so you can use the API in your onEnable() method. In the example below, we will use a soft dependency, so your plugin will still work if SkinsRestorer is not installed, but to use the API, SkinsRestorer will need to be installed. Errors will be thrown if SkinsRestorer is not installed, but you use the API. The process below may vary depending on your build configuration. (E.g., you have a build plugin that generates plugin configs)

Add the following dependency to your plugin.yml file:

softdepend: [ "SkinsRestorer" ]

BungeeCord uses softDepends instead of softdepend like Bukkit/Spigot. Add the following dependency to your bungee.yml or plugin.yml file:

softDepends: [ "SkinsRestorer" ]

Add the following dependency to your plugin entry file annotation:

@Plugin(dependencies = {@Dependency(id = "skinsrestorer", optional = true)})

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");
}

When using BungeeCord/Velocity?

If you are using BungeeCord/Velocity, you have two options:

Call the API from the proxy: Have a plugin that calls the API directly on BungeeCord/Velocity. You would need to use plugin messaging channels to send information between your proxy and backend plugins.
Call the API from backend servers: Enable server.proxyMode.api in your backend server's config.yml (enabled by default) and configure MySQL to connect to the same database as the proxy. This allows backend plugins to use the SkinsRestorer API directly.

Error handling

Always wrap API calls in try-catch blocks:

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

Getting issues?

Make sure to import all your classes if you see the message "Cannot find symbol" or "Cannot resolve symbol"
Make sure to get the API using this.skinsRestorer = SkinsRestorerProvider.get(); and you have the field private SkinsRestorer skinsRestorer; at the start of your class.
Make sure to add the dependency to your build file as described above.
Make sure to add the dependency to your plugin.yml as described above.
If using the API on backend servers behind a proxy, ensure server.proxyMode.api is enabled and MySQL is configured to the same database as the proxy.

SkinsRestorer API

On this page