# Introduction URL: /docs Learn what SkinsRestorer does and how to get started. SkinsRestorer shows player skins on Minecraft servers. It works on online-mode and offline-mode servers. Players can change their skin with one command. Server networks can also share cached skin data. ## Why use SkinsRestorer? [#why-use-skinsrestorer] SkinsRestorer works on a single server or a large proxy network. The default permissions work without another plugin. If you need more control, use a permissions plugin. ### Main features [#main-features] * Apply a custom skin with `/skin url ""`. * Create a shared server skin with `/sr createcustom`. * Use cached skins when Mojang is unavailable. * Replace the default Steve and Alex skins. * Apply skin changes without reconnecting. ## Getting started [#getting-started] # Auto update URL: /docs/configuration/auto-update Understand how SkinsRestorer installs updates. SkinsRestorer looks for updates when the server starts. If an update is available, it downloads the file. SkinsRestorer installs the update during the next server restart. On BungeeCord and Velocity networks, only backend servers update automatically. If SkinsRestorer reports an update, update the proxy manually. ## Why automatic updates are enabled [#why-automatic-updates-are-enabled] Updates contain security fixes, bug fixes, and new features. The project supports only the latest version. Before you request support, update SkinsRestorer. The latest version can already contain a fix for the problem. ## Benefits of the latest version [#benefits-of-the-latest-version] * **Security:** The latest version contains current security fixes. * **Features:** The latest version contains current features and bug fixes. * **Support:** The project provides support only for the latest version. * **Compatibility:** The latest version contains current compatibility fixes. ## Update security [#update-security] SkinsRestorer compares the downloaded file hash with the hash from the GitHub release. This comparison finds damaged or changed files. Automated tests and project testers examine each release before publication. ## Disable automatic updates [#disable-automatic-updates] The project does not provide support for installations with automatic updates disabled. The automatic updater installs updates for you. It also shows an in-game message when an update is available. If you still want to disable it, read the instructions at the bottom of `config.yml`. # Commands and Permissions URL: /docs/configuration/commands-permissions Find SkinsRestorer commands and configure their permissions. A permission works only when the player also has its parent permissions. For example, `skinsrestorer.command.set.other` also needs `skinsrestorer.command.set` and `skinsrestorer.command`. If commands do not work, read the [installation guide](/docs/installation). ## Commands [#commands] SkinsRestorer provides player commands and administrator commands. ### Player commands [#player-commands] These parent permissions give access to all player commands: `skinsrestorer.player` / `skinsrestorer.command.*` | Command | Description | Permission | | --------------------------------------------- | ------------------------------------- | ------------------------------------ | | `/skin` | Changes your own skin. | `skinsrestorer.command` | | `/skin set ` | Changes your skin. | `skinsrestorer.command.set` | | `/skin set ` | Sets the skin for a target player. | `skinsrestorer.command.set.other` | | `/skin set ` | Sets the skin for a target player. | `skinsrestorer.command.set.other` | | `/skin url ` | Changes your skin from a URL. | `skinsrestorer.command.set.url` | | `/skin url ` | Changes your skin from a URL. | `skinsrestorer.command.set.url` | | `/skin update` | Updates your skin. | `skinsrestorer.command.update` | | `/skin update ` | Updates the skin of a target player. | `skinsrestorer.command.update.other` | | `/skin search ` | Searches for a skin. | `skinsrestorer.command.search` | | `/skin clear` | Clears your skin. | `skinsrestorer.command.clear` | | `/skin clear ` | Clears the skin of a target player. | `skinsrestorer.command.clear.other` | | `/skin random` | Applies a random recommended skin. | `skinsrestorer.command` | | `/skin undo` | Reverts to your previous skin. | `skinsrestorer.command` | | `/skin history` | Shows your skin change history. | `skinsrestorer.command` | | `/skin favourite` | Adds or removes the current favorite. | `skinsrestorer.command` | | `/skin favourites` | Lists your favorited skins. | `skinsrestorer.command` | | `/skin edit` | Opens the skin editor in browser. | `skinsrestorer.command` | | `/skin upload` | Shows skin upload information. | `skinsrestorer.command.set.url` | | `/skin ` | Changes your own skin. | `skinsrestorer.command` | | `/skin help` | Shows command help. | `skinsrestorer.command.set` | | `/skins` | Opens the skins GUI. | `skinsrestorer.command.gui` | ### Admin commands [#admin-commands] These parent permissions give access to all administrator commands: `skinsrestorer.admin` / `skinsrestorer.admincommand.*` | Command | Description | Permission | | ------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------- | | `/sr` | Admin commands for SkinsRestorer. | `skinsrestorer.admincommand` | | `/sr createcustom ` | Creates a custom server-wide skin. | `skinsrestorer.admincommand.createcustom` | | `/sr createcustom ` | Creates a custom server-wide skin. | `skinsrestorer.admincommand.createcustom` | | `/sr setskinall ` | Sets one skin for every player. | `skinsrestorer.admincommand.setskinall` | | `/sr info ` | Displays info about a player or skin. | `skinsrestorer.admincommand.info` | | `/sr props ` | Displays info about a player or skin. | `skinsrestorer.admincommand.info` | | `/sr lookup ` | Displays info about a player or skin. | `skinsrestorer.admincommand.info` | | `/sr drop ` | Removes player or skin data from the database. | `skinsrestorer.admincommand.drop` | | `/sr remove ` | Removes player or skin data from the database. | `skinsrestorer.admincommand.drop` | | `/sr purgeolddata ` | Removes skin data older than the given age. | `skinsrestorer.admincommand.purgeolddata` | | `/sr applyskin ` | Applies the target player's skin again. | `skinsrestorer.admincommand.applyskin` | | `/sr dump` | Uploads support data to bytebin.lucko.me. | `skinsrestorer.admincommand.dump` | | `/sr applyskinall` | Applies every online player's skin again. | `skinsrestorer.admincommand.applyskinall` | | `/sr status` | Shows the required API services. | `skinsrestorer.admincommand.status` | | `/sr reload` | Reloads the configuration file. | `skinsrestorer.admincommand.reload` | ## Special permissions [#special-permissions] These permissions control specific features. | Permission | Description | | ------------------------------ | -------------------------------------------------------------------- | | `skinsrestorer.bypasscooldown` | Bypasses any command cooldown in the configuration. | | `skinsrestorer.bypassdisabled` | Bypasses the list of disabled skins in the configuration. | | `skinsrestorer.ownskin` | Allows access to set your own skin. | | `skinsrestorer.skin.` | Allows access to a specific skin if `perSkinPermissions` is enabled. | ## Cooldowns [#cooldowns] Cooldowns limit repeated commands. ### Default cooldowns [#default-cooldowns] | Action | Default | Config option | | ----------------- | ---------- | ----------------------------- | | Skin change | 30 seconds | `commands.skinChangeCooldown` | | Skin error retry | 5 seconds | `commands.skinErrorCooldown` | | Skull command | 30 seconds | `commands.skullCooldown` | | Skull error retry | 5 seconds | `commands.skullErrorCooldown` | ### Bypassing cooldowns [#bypassing-cooldowns] Grant `skinsrestorer.bypasscooldown` to ignore all cooldowns. ## Permission plugin examples [#permission-plugin-examples] ### LuckPerms [#luckperms] **Give all players basic skin access:** ``` /lp group default permission set skinsrestorer.player true ``` **Give staff admin commands:** ``` /lp group staff permission set skinsrestorer.admin true ``` **Give VIPs cooldown bypass:** ``` /lp group vip permission set skinsrestorer.bypasscooldown true ``` **Give VIPs access to URL skins:** ``` /lp group vip permission set skinsrestorer.command.set.url true ``` **Give VIPs access to set other players' skins:** ``` /lp group vip permission set skinsrestorer.command.set.other true ``` **First, enable per-skin permissions in `config.yml`:** ```yaml filename="config.yml" commands: perSkinPermissions: enabled: true list: - "Notch" - "Dream" - "Technoblade" ``` **Then grant access to specific skins:** ``` /lp group vip permission set skinsrestorer.skin.Notch true /lp group mvp permission set skinsrestorer.skin.Dream true ``` The GUI shows a locked skin to players without permission. ### PermissionsEx (Legacy) [#permissionsex-legacy] ``` /pex group default add skinsrestorer.player /pex group staff add skinsrestorer.admin /pex group vip add skinsrestorer.bypasscooldown ``` ## Restricting skin access [#restricting-skin-access] ### Disable specific skins [#disable-specific-skins] Add skins to the disabled list in `config.yml`: ```yaml filename="config.yml" commands: disabledSkins: - "steve" - "owner" - "admin" - "inappropriateskin" ``` Players with `skinsrestorer.bypassdisabled` can still use these skins. ### Restrict URL domains [#restrict-url-domains] Allow skin URLs only from specific domains: ```yaml filename="config.yml" commands: restrictSkinUrls: enabled: true list: - "https://i.imgur.com" - "https://textures.minecraft.net" ``` ### Per-skin permissions [#per-skin-permissions] Require a permission for each listed skin: ```yaml filename="config.yml" commands: perSkinPermissions: enabled: true list: - "Notch" - "specialskin" ``` Players need `skinsrestorer.skin.` to use skins in the list. ## Command usage examples [#command-usage-examples] ### Set skin for every player [#set-skin-for-every-player] Use this command to change every online player's skin until they rejoin: ``` /sr setskinall ``` Example: ``` /sr setskinall Santa classic ``` ### Create a custom server skin [#create-a-custom-server-skin] Create a skin that all players can use: ``` /sr createcustom ``` Examples: ``` /sr createcustom staff Notch /sr createcustom event "https://i.imgur.com/abc123.png" slim ``` ### Look up skin information [#look-up-skin-information] ``` /sr info player /sr info skin ``` ### Remove old data [#remove-old-data] Purge skin data older than 30 days: ``` /sr purgeolddata 30 ``` ## Create a support report [#create-a-support-report] If you need support, run `/sr dump`. Then send the generated link to the developers. ``` /sr dump ``` The command uploads server information, the configuration, and logs to a paste service. # Database Setup URL: /docs/configuration/database Store SkinsRestorer data in a MySQL database. SkinsRestorer can store skin data in MySQL instead of local files. MySQL lets multiple servers share the same skin data. ## When to use database storage [#when-to-use-database-storage] Use MySQL when you: * Run a proxy network (BungeeCord/Velocity) with multiple backend servers * Want skin data shared across multiple servers * Need the backend API to work on servers behind a proxy * Have many players Use local files when you: * Run a single standalone server * Do not need to share skin data between servers * Want a simpler setup ## Database configuration [#database-configuration] Add this configuration to `config.yml`: ```yaml filename="config.yml" database: enabled: true host: localhost port: 3306 database: skinsrestorer username: sr_user password: your_secure_password maxPoolSize: 10 tablePrefix: sr_ connectionOptions: "sslMode=trust&serverTimezone=UTC" ``` ### Configuration options [#configuration-options] | Option | Default | Description | | ------------------- | ---------------------------------- | ----------------------------------------- | | `enabled` | `false` | Set to `true` to enable database storage | | `host` | `localhost` | MySQL server address | | `port` | `3306` | MySQL server port | | `database` | `db` | Database name | | `username` | `root` | Database username | | `password` | `pass` | Database password | | `maxPoolSize` | `10` | Maximum number of connections in the pool | | `tablePrefix` | `sr_` | Prefix for all SkinsRestorer tables | | `connectionOptions` | `sslMode=trust&serverTimezone=UTC` | Additional connection parameters | ## Setup guide [#setup-guide] ### Create the database [#create-the-database] Connect to your MySQL server. Then create a database for SkinsRestorer: ```sql CREATE DATABASE skinsrestorer; ``` ### Create a dedicated user [#create-a-dedicated-user] Create a MySQL user for SkinsRestorer: ```sql CREATE USER 'sr_user'@'localhost' IDENTIFIED BY 'your_secure_password'; GRANT ALL PRIVILEGES ON skinsrestorer.* TO 'sr_user'@'localhost'; FLUSH PRIVILEGES; ``` If MySQL is on another computer, replace `localhost` with its host name. If you must permit connections from any host, use `%`. ### Configure SkinsRestorer [#configure-skinsrestorer] Add the database credentials to `config.yml`. ### Restart your server [#restart-your-server] Restart the server. Read the console for connection errors. ## Proxy network setup [#proxy-network-setup] On a proxy network, use the **same database** on the proxy and every backend server. Backend servers need database access to use the SkinsRestorer API. Keep `server.proxyMode.api` enabled in every backend configuration. ### Example setup [#example-setup] 1. Set `database.enabled: true` on the **proxy**. 2. Add the same database credentials to **each backend server**. 3. Make sure that the proxy and every backend server can connect to MySQL. ## SSL/TLS configuration [#ssltls-configuration] The `connectionOptions` value controls the SSL connection: | SSL Mode | Use case | | ------------------------- | ------------------------------------------------------ | | `sslMode=trust` | Trust any certificate (development/internal networks) | | `sslMode=disable` | Disable SSL entirely (not recommended for production) | | `sslMode=verify-ca` | Require a server certificate from the configured CA | | `sslMode=verify-identity` | Require a valid certificate and hostname (most secure) | For production environments with SSL certificates: ```yaml connectionOptions: "sslMode=verify-ca&serverTimezone=UTC" ``` ## Migrating from file storage [#migrating-from-file-storage] SkinsRestorer does not copy local file data to MySQL. When you enable MySQL, the database starts empty. To restore custom skins: 1. Record each custom skin that you created with `/sr createcustom`. 2. Enable MySQL storage. 3. Create the custom skins again with the same commands. After players rejoin, they can select their skins again. ## Troubleshooting [#troubleshooting] ### Connection refused [#connection-refused] * Make sure that MySQL accepts connections. * Make sure that the host and port are correct. * Allow MySQL traffic on port 3306 through the firewall. ### Access denied [#access-denied] * Make sure that the username and password are correct. * Grant the MySQL user access to the database. * For a remote connection, permit the Minecraft server's IP address. ### SSL errors [#ssl-errors] * For a temporary test, use `sslMode=trust` or `sslMode=disable`. * For production, configure trusted SSL certificates. ### Timezone errors [#timezone-errors] * Add `serverTimezone=UTC` to `connectionOptions`. * To use a specific timezone, set a value such as `serverTimezone=America/New_York`. ## Performance tuning [#performance-tuning] ### Connection pool size [#connection-pool-size] The `maxPoolSize` option sets the maximum number of database connections. * **Small servers (\< 100 players)**: 5-10 connections * **Medium servers (100-500 players)**: 10-20 connections * **Large networks (500+ players)**: 20-50 connections Do not set a value that MySQL cannot support. Each connection uses resources, and MySQL limits the total number of connections. ### Table prefix [#table-prefix] If multiple SkinsRestorer installations share one database, give each installation a different `tablePrefix`. # Configuration URL: /docs/configuration Learn how to set up SkinsRestorer on your server. SkinsRestorer works with the default configuration. If your server needs different behavior, change the related options. ## Choose a guide [#choose-a-guide] Select the guide for the part that you want to change. # Locale and Translations URL: /docs/configuration/locale-translations Change or translate SkinsRestorer messages. SkinsRestorer can show messages in the language of each player's Minecraft client. ## Default values [#default-values] The default locale is `en` for English. Change the default locale in `config.yml`. ## Community translation [#community-translation] Community members translate SkinsRestorer. You can add a translation or improve an existing one. ### Contribute a translation [#contribute-a-translation] Add translations on the [SkinsRestorer Crowdin page](https://translate.skinsrestorer.net). If your locale is absent, contact us on [Discord](https://skinsrestorer.net/discord). ## Custom translations [#custom-translations] If you use BungeeCord or Velocity, copy the locale files to the proxy and every backend server. The `plugins/SkinsRestorer/locale` folder contains two folders: `repository` and `custom`. The `repository` folder contains the default locale files. SkinsRestorer uses these files when `custom` does not contain the requested locale. Do not edit files in `repository`. Updates and reloads replace these files. To change a locale: 1. Copy its file from `repository` to `custom`. 2. Edit the copy in `custom`. After an update, compare your custom file with the new default file. The update can add or change messages. ## Locale list [#locale-list] SkinsRestorer includes these locales: ### Locale codes [#locale-codes] | Locale | code | file name | | ------------------------------- | ------- | ------------------- | | Arabic | `ar` | `locale_ar.json` | | Bulgarian | `bg` | `locale_bg.json` | | Catalan | `ca` | `locale_ca.json` | | Czech | `cs` | `locale_cs.json` | | Danish | `da` | `locale_da.json` | | German | `de` | `locale_de.json` | | Argentinian Spanish | `es_ar` | `locale_es_ar.json` | | Spanish | `es` | `locale_es.json` | | Finnish | `fi` | `locale_fi.json` | | French | `fr` | `locale_fr.json` | | Canadian French | `fr_ca` | `locale_fr_ca.json` | | Hungarian | `hu` | `locale_hu.json` | | Italian | `it` | `locale_it.json` | | Japanese | `ja` | `locale_ja.json` | | Korean | `ko` | `locale_ko.json` | | Lithuanian | `lt` | `locale_lt.json` | | Dutch | `nl` | `locale_nl.json` | | Norwegian Bokmål | `no` | `locale_no.json` | | Norwegian Nynorsk | `nn_no` | `locale_nn_no.json` | | Polish | `pl` | `locale_pl.json` | | Brazilian Portuguese | `pt_br` | `locale_pt_br.json` | | Romanian | `ro` | `locale_ro.json` | | Thai | `th` | `locale_th.json` | | Turkish | `tr` | `locale_tr.json` | | Ukrainian | `uk` | `locale_uk.json` | | Simplified Chinese (China) | `zh_cn` | `locale_zh_cn.json` | | Traditional Chinese (Hong Kong) | `zh_hk` | `locale_zh_hk.json` | | Traditional Chinese (Taiwan) | `zh_tw` | `locale_zh_tw.json` | # Configuration Options URL: /docs/configuration/options Understand and change the SkinsRestorer configuration. SkinsRestorer works with the default configuration. If you need different behavior, use this page to find the correct option. After you change the configuration, run `/sr reload` or restart the server. On a proxy network, use the same `config.yml` file on the proxy and every backend server. After each change, run `/sr reload` on the proxy. Then restart every backend server. ## File structure [#file-structure] This example shows the SkinsRestorer files. Select a folder to expand it. <> ## Storage settings [#storage-settings] Choose how SkinsRestorer saves and refreshes skin data. ```yaml filename="config.yml" storage: defaultSkins: enabled: false applyForPremium: false list: - "xknat" - "pistonmaster" - "" disallowAutoUpdateSkin: false skinExpiresAfter: 15 uuidExpiresAfter: 60 ``` | Option | Default | Description | | ------------------------------ | --------------------------------------- | ----------------------------------------------------------- | | `defaultSkins.enabled` | `false` | Enable default skins for players without a set skin | | `defaultSkins.applyForPremium` | `false` | Apply default skins even to premium players | | `defaultSkins.list` | `["xknat", "pistonmaster", ""]` | List of default skins. Use `` for recommended skins | | `disallowAutoUpdateSkin` | `false` | Require players to run `/skin update` manually | | `skinExpiresAfter` | `15` | Minutes before SkinsRestorer requests skin data again | | `uuidExpiresAfter` | `60` | Minutes before SkinsRestorer requests a player UUID again | A cache expiration value of `0` requests new API data each time. This can cause rate-limit errors on production servers. ## Command settings [#command-settings] Set command cooldowns and access limits. ```yaml filename="config.yml" commands: skinChangeCooldown: 30 skinErrorCooldown: 5 skullCooldown: 30 skullErrorCooldown: 5 disabledSkins: - "steve" - "owner" restrictSkinUrls: enabled: false list: - "https://i.imgur.com" - "https://storage.googleapis.com" - "https://cdn.discordapp.com" - "https://textures.minecraft.net" perSkinPermissions: enabled: false list: [] forceDefaultPermissions: true customPlayerHistory: 18 customFavourites: 90 disableSkinCommand: false disableSkullCommand: false disableGUICommand: false ``` | Option | Default | Description | | ---------------------------- | -------------------- | ------------------------------------------------------ | | `skinChangeCooldown` | `30` | Seconds between `/skin` commands | | `skinErrorCooldown` | `5` | Seconds to wait after a failed skin change | | `skullCooldown` | `30` | Seconds between `/skull` commands | | `skullErrorCooldown` | `5` | Seconds to wait after a failed skull command | | `disabledSkins` | `["steve", "owner"]` | Skins that cannot be used | | `restrictSkinUrls.enabled` | `false` | Only allow URLs from whitelisted domains | | `restrictSkinUrls.list` | (see above) | Allowed URL domains when restriction is enabled | | `perSkinPermissions.enabled` | `false` | Require `skinsrestorer.skin.` for specific skins | | `perSkinPermissions.list` | `[]` | Skins that require permissions | | `forceDefaultPermissions` | `true` | Give all players `skinsrestorer.player` by default | | `customPlayerHistory` | `18` | Max entries in `/skin undo` history | | `customFavourites` | `90` | Max entries in `/skin favourite` list | | `disableSkinCommand` | `false` | Disable the `/skin` command registration | | `disableSkullCommand` | `false` | Disable the `/skull` command registration | | `disableGUICommand` | `false` | Disable the `/skins` command registration | ## Login settings [#login-settings] Choose how SkinsRestorer applies skins when a player joins. ```yaml filename="config.yml" login: noSkinIfLoginCanceled: true alwaysApplyPremium: false ``` | Option | Default | Description | | ----------------------- | ------- | ----------------------------------------------------------- | | `noSkinIfLoginCanceled` | `true` | Do not apply skins when another plugin cancels login | | `alwaysApplyPremium` | `false` | Apply skins even for premium players on online-mode servers | ## Server settings (Backend only) [#server-settings-backend-only] These options apply only to backend servers. They do not apply to proxies. ```yaml filename="config.yml" server: resourcePackFix: true dismountPlayerOnUpdate: true remountPlayerOnUpdate: true dismountPassengersOnUpdate: false sound: enabled: true value: "ENTITY_PLAYER_TELEPORT, 0.7" proxyMode: detection: AUTO api: true ``` | Option | Default | Description | | ---------------------------- | ------------------------------- | ------------------------------------------------- | | `resourcePackFix` | `true` | Reapply skins after resource pack loads | | `dismountPlayerOnUpdate` | `true` | Dismount player from vehicle during skin update | | `remountPlayerOnUpdate` | `true` | Remount player after skin update | | `dismountPassengersOnUpdate` | `false` | Dismount passengers riding the player | | `sound.enabled` | `true` | Play sound when skin changes | | `sound.value` | `"ENTITY_PLAYER_TELEPORT, 0.7"` | Sound to play (format: SOUND\_NAME, volume) | | `proxyMode.detection` | `AUTO` | Proxy detection: `AUTO`, `ENABLED`, or `DISABLED` | | `proxyMode.api` | `true` | Enable API on backend servers (requires database) | ## Proxy settings (Proxy only) [#proxy-settings-proxy-only] These options apply only to BungeeCord and Velocity proxies. ```yaml filename="config.yml" proxy: notAllowedCommandServers: enabled: true ifNoneBlockCommand: true allowList: false list: - "auth" ``` | Option | Default | Description | | --------------------------------------------- | ---------- | ------------------------------------------- | | `notAllowedCommandServers.enabled` | `true` | Enable server-based command restrictions | | `notAllowedCommandServers.ifNoneBlockCommand` | `true` | Block commands before joining any server | | `notAllowedCommandServers.allowList` | `false` | If true, only listed servers allow commands | | `notAllowedCommandServers.list` | `["auth"]` | Servers to block/allow commands on | ## API settings [#api-settings] Configure connections to external APIs. ```yaml filename="config.yml" api: mineSkinApiKey: "" mineSkinSecretSkins: false fetchRecommendedSkins: true mojangBatchWindowSeconds: 1 ``` | Option | Default | Description | | -------------------------- | ------- | ------------------------------------------------------------------------ | | `mineSkinApiKey` | (empty) | Your [MineSkin API key](https://mineskin.org/apikey) for faster requests | | `mineSkinSecretSkins` | `false` | Hide generated skins from MineSkin's public gallery | | `fetchRecommendedSkins` | `true` | Load curated recommended skins (required for `/skin random`) | | `mojangBatchWindowSeconds` | `1` | Batch window for Mojang API requests to avoid rate limits | Use coupon code `SKINSRESTORER10` for 10% off your first three months of MineSkin API plans (except Lite). ## GUI settings [#gui-settings] Choose what the `/skins` GUI shows and how it looks. ```yaml filename="config.yml" gui: notUnlockedSkin: "c10591e6909e6a281b371836e462d67a2c78fa0952e910f32b41a26c48c1757c" customSkins: enabled: true index: 0 onlyList: false list: - "xknat" - "pistonmaster" playerSkins: enabled: false index: 1 onlyList: false list: [] recommendations: enabled: true index: 2 onlyList: false list: - "vampire" - "space-suit" ``` | Option | Default | Description | | ------------------------- | --------------------------- | ----------------------------------------------------------- | | `notUnlockedSkin` | (texture hash) | Skin shown for locked skins (when using perSkinPermissions) | | `customSkins.enabled` | `true` | Show custom skins tab in GUI | | `customSkins.index` | `0` | Tab order (lower = first) | | `customSkins.onlyList` | `false` | Only show skins in the list | | `customSkins.list` | `["xknat", "pistonmaster"]` | Skins to show in custom tab | | `playerSkins.enabled` | `false` | Show online player skins tab | | `playerSkins.index` | `1` | Tab order | | `recommendations.enabled` | `true` | Show recommended skins tab | | `recommendations.index` | `2` | Tab order | ## Advanced settings [#advanced-settings] CAUTION: These options can cause unexpected behavior. If you do not understand an option, do not change it. ```yaml filename="config.yml" advanced: disableOnJoinSkins: false enablePaperJoinListener: true teleportRefresh: false noConnections: false playerHeadChatObjects: false ``` | Option | Default | Description | | ------------------------- | ------- | --------------------------------------------------- | | `disableOnJoinSkins` | `false` | Do not apply skins when a player joins | | `enablePaperJoinListener` | `true` | Use Paper's join event for instant skin application | | `teleportRefresh` | `false` | Use teleport instead of hiding for skin refresh | | `noConnections` | `false` | Disable all web connections (offline mode) | | `playerHeadChatObjects` | `false` | Show player heads in chat messages | ## Debug settings [#debug-settings] ```yaml filename="config.yml" dev: debug: false ``` | Option | Default | Description | | ------- | ------- | --------------------------------------------------------- | | `debug` | `false` | Enable debug logging for API requests and troubleshooting | ## Who can change skins? [#who-can-change-skins] Players use `/skin ` to change their skin. Use a permissions plugin to control access to this command. Read [Commands and Permissions](/docs/configuration/commands-permissions) for setup instructions. ## Default skins [#default-skins] By default, SkinsRestorer applies the skin from the player's Minecraft account. Players without an account skin receive a Steve skin. Default skins apply only to players who have not selected a skin with `/skin `. Use `storage.defaultSkins` in `config.yml` to select the default skins. If `applyForPremium` is `true`, default skins also replace skins from Minecraft accounts. ## Disabled skins [#disabled-skins] Add blocked skin names to `commands.disabledSkins` in `config.yml`. Use this option to block inappropriate skins or reserved names. ## Permissions per skin [#permissions-per-skin] By default, `/skin ` can apply any available skin. To restrict a skin, add it to `commands.perSkinPermissions` in `config.yml`. Give players `skinsrestorer.skin.` for each listed skin that they can use. # SkinsRestorer API URL: /docs/development/api Add the SkinsRestorer API to a Java plugin. 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 [#resources] These resources contain complete API details and an example plugin: * [Example Plugin](https://github.com/SkinsRestorer/SkinsRestorerAPIExample) * [Javadocs](https://jd.skinsrestorer.net) ## Add to your build file [#add-to-your-build-file] Select your build tool, then add the repository and dependency. Use the latest version number without the `v` prefix: ![Latest Version](https://img.shields.io/github/v/tag/SkinsRestorer/SkinsRestorer?label=version) Add the following repository and dependency to your `pom.xml` file: ```xml filename="pom.xml" codemc https://repo.codemc.org/repository/maven-public/ net.skinsrestorer skinsrestorer-api VERSION provided ``` Add the following repository and dependency to your `build.gradle` file: ```groovy filename="build.gradle" 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: ```kotlin filename="build.gradle.kts" 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 [#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: ```yml filename="plugin.yml" softdepend: [ "SkinsRestorer" ] ``` BungeeCord uses `softDepends` instead of the Bukkit `softdepend` key. Add the following dependency to your `bungee.yml` or `plugin.yml` file: ```yml filename="bungee.yml" softDepends: [ "SkinsRestorer" ] ``` Add the following dependency to your plugin entry file annotation: ```java filename="YourPluginClass.java" @Plugin(dependencies = {@Dependency(id = "skinsrestorer", optional = true)}) ``` ## Code examples [#code-examples] ### Getting the API instance [#getting-the-api-instance] ```java 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 [#setting-a-players-skin-by-name] ```java 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 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 [#setting-a-skin-from-a-url] ```java 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 [#getting-a-players-current-skin] ```java import net.skinsrestorer.api.property.SkinProperty; public SkinProperty getPlayerSkin(Player player) { PlayerStorage playerStorage = skinsRestorerAPI.getPlayerStorage(); Optional property = playerStorage.getSkinForPlayer( player.getUniqueId(), player.getName() ); return property.orElse(null); } ``` ### Creating a custom server skin [#creating-a-custom-server-skin] ```java 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 [#getting-the-texture-url-from-skin-data] ```java import net.skinsrestorer.api.property.SkinProperty; import net.skinsrestorer.api.PropertyUtils; public String getTextureUrl(SkinProperty skinProperty) { return PropertyUtils.getSkinTextureUrl(skinProperty); } ``` ### Checking API version compatibility [#checking-api-version-compatibility] ```java 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 [#use-the-api-on-a-proxy-network] On BungeeCord or Velocity, use one of these options: 1. **Call the API from the proxy:** Put your API plugin on BungeeCord or Velocity. Use plugin messages to communicate with plugins on backend servers. 2. **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 [#error-handling] Handle errors from API calls: ```java try { Optional 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 [#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();{:java}`. * Add the `private SkinsRestorer skinsRestorer;{:java}` 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. # Development URL: /docs/development Use SkinsRestorer data in your plugin or application. The SkinsRestorer API lets a plugin or application read and change skin data. ## Choose a development guide [#choose-a-development-guide] Select a guide for the API, data storage, or internal process. # How SkinsRestorer works URL: /docs/development/inner-workings Understand how SkinsRestorer requests and applies skin data. Read the [storage page](/docs/development/storage) first. It explains the skin data used on this page. This page explains how SkinsRestorer gets and applies skins. ## Recap [#recap] SkinsRestorer gets signed player skin data from Mojang. The Minecraft client accepts only skin data that Mojang signed. This rule also keeps official capes linked to approved accounts. Signed-skin restrictions apply to players, not Minecraft heads. Citizens NPCs also use the player skin rules. SkinsRestorer gets skins in two ways: 1. It gets the signed skin data of a Minecraft player. 2. It sends a custom PNG to an account service that gets signed skin data. SkinsRestorer uses [MineSkin](https://mineskin.org) for the second method. Paid MineSkin plans above Lite include higher limits and more features. Visit the MineSkin API keys page and use coupon code SKINSRESTORER10. The code gives you 10% off the first three months. SkinsRestorer does not receive a commission. ## Skin request flow [#skin-request-flow] This diagram shows a skin request by player name: ## SkinsRestorer API endpoints [#skinsrestorer-api-endpoints] SkinsRestorer uses these endpoints to cache and distribute skin data: * `eclipse.skinsrestorer.net` - Handles UUID lookups and profile data * `axolotl.skinsrestorer.net` - Handles MineSkin URL decryption * `cool-skins.skinsrestorer.net` - Provides recommended/featured skins These endpoints provide a cache between your server and Mojang. The cache reduces Mojang API requests and rate-limit errors. It can also provide cached skin data when Mojang is slow or unavailable. # How SkinsRestorer stores data URL: /docs/development/storage Understand the skin and player data that SkinsRestorer stores. SkinsRestorer stores skin data in local files or a database. Your configuration selects the storage type. ## Why SkinsRestorer stores skins [#why-skinsrestorer-stores-skins] Stored skin data is a local cache. It contains the same data that Mojang sends to an online-mode server. The cache reduces requests to the Mojang API. It can also provide skins when Mojang is unavailable. ## Stored data [#stored-data] When you run `/skin Dinnerbone`, SkinsRestorer stores the skin data for Dinnerbone. It updates the cache after that account changes its skin. When you run `/sr createcustom`, SkinsRestorer stores a fixed custom skin. ### How Minecraft stores skin PNGs [#how-minecraft-stores-skin-pngs] The Minecraft launcher and SkinsRestorer get skin images from the [Minecraft CDN](https://textures.minecraft.net). Mojang signs skin data with the Yggdrasil private key. The Minecraft client displays only data with a valid signature. The signature does not expire. However, Mojang can remove a reported skin from the CDN. If Mojang removes a skin, Minecraft clients cannot show it. A local PNG file does not bypass this restriction. SkinsRestorer copies signed data from an existing skin. It does not upload the skin to your Minecraft account. URL skins use a pool of community-provided Minecraft accounts to create signed data. ## What is skin data? [#what-is-skin-data] Skin data is a Base64-encoded profile property. It contains URLs for skin and cape textures. SkinsRestorer requests this data from the Mojang API with a player UUID. Mojang's signature lets the Minecraft client validate the data. Use a [Base64 decoder](https://www.base64decode.org/live) to read the property. The decoded data looks like this: ```json { "timestamp": 1705586820658, "profileId": "61699b2ed3274a019f1e0ea8c3f06bc6", "profileName": "Dinnerbone", "signatureRequired": true, "textures": { "SKIN": { "url": "http://textures.minecraft.net/texture/50c410fad8d9d8825ad56b0e443e2777a6b46bfa20dacd1d2f55edc71fbeb06d" }, "CAPE": { "url": "http://textures.minecraft.net/texture/5786fe99be377dfb6858859f926c4dbc995751e91cee373468c5fbf4865e7151" } } } ``` 1. `timestamp` is the creation date in [epoch time](https://www.epochconverter.com/). 2. `profileId` is the player's [Mojang UUID](https://api.mojang.com/users/profiles/minecraft/Dinnerbone). 3. `profileName` is the player name for this skin. 4. `signatureRequired` must be `true` for signed skin data. 5. `url` points to the skin or cape texture. ## How SkinsRestorer requests skin data [#how-skinsrestorer-requests-skin-data] SkinsRestorer uses two Mojang API requests: 1. The [player name endpoint](https://api.mojang.com/users/profiles/minecraft/Dinnerbone) returns the UUID for a player name. 2. The [profile endpoint](https://sessionserver.mojang.com/session/minecraft/profile/61699b2ed3274a019f1e0ea8c3f06bc6?unsigned=false) returns the Base64-encoded skin data for that UUID. ## Rate limits [#rate-limits] Mojang limits API requests. SkinsRestorer uses cached data to reduce requests and avoid this limit. ## Other resources [#other-resources] * [Mojang API](https://wiki.vg/Mojang_API) # Cape Support URL: /docs/features/capes Understand which capes SkinsRestorer can show. Capes are cosmetic items on a Minecraft player's back. They do not affect the game. ## How capes work in Minecraft [#how-capes-work-in-minecraft] Capes come from: * **Account events:** Migration capes and the Vanilla cape for linked Bedrock and Java accounts * **Events:** Minecraft Live, MINECON, and social media campaigns * **Staff or volunteer work:** Mojang employees, translators, and moderators * **Personal awards:** Capes for specific Java Edition players * **Pan Cape:** The only cape given automatically to all players You cannot create a custom cape or move a cape to another account. Each cape belongs to a Mojang or Microsoft account. ## How SkinsRestorer handles capes [#how-skinsrestorer-handles-capes] When you use `/skin `, SkinsRestorer gets the complete skin data from Mojang. The data contains: * The skin texture * The cape texture (if the player has one equipped) * Mojang's cryptographic signature If the source player has an equipped cape, your character also shows it. ### Example [#example] ``` /skin Dinnerbone ``` If Dinnerbone equips a Mojang employee cape, your character shows the same skin and cape. ## Limitations [#limitations] ### What SkinsRestorer can do [#what-skinsrestorer-can-do] * Copy skins from players who have capes (cape included) * Display the cape that comes with the copied skin data ### What SkinsRestorer cannot do [#what-skinsrestorer-cannot-do] * **Create custom capes:** Capes need Mojang's signature and belong to specific accounts. * **Add capes to URL skins:** `/skin url` creates only a skin texture. * **Remove a cape from copied data:** Copied skin data includes the skin and its cape. * **Create other capes:** Mojang does not provide an API for new capes. MineSkin creates only skin textures for `/skin url`. It cannot create capes because capes require Mojang account verification. ## Finding players with capes [#finding-players-with-capes] To copy a cape, find a player who has equipped one. Players with capes include: * Mojang employees (Mojang cape) * MINECON attendees (various years) * Minecraft Live participants * Content creators with personal capes SkinsRestorer copies the cape that the source player equips. Cached data can show the old cape until you refresh it. ## Refreshing cape data [#refreshing-cape-data] If the source player changes their cape, refresh the cached data: ``` /skin update ``` You can also clear and apply the skin again: ``` /skin clear /skin ``` ## Technical details [#technical-details] Cape data is part of Mojang's signed skin property. The Base64-encoded texture data contains URLs for the skin and cape: ```json { "textures": { "SKIN": { "url": "http://textures.minecraft.net/texture/..." }, "CAPE": { "url": "http://textures.minecraft.net/texture/..." } } } ``` The cape URL exists only when the player equips a cape. Mojang signs the complete data. Therefore, SkinsRestorer cannot create custom capes. # Custom Skins URL: /docs/features/custom-skins Create a shared skin with a custom name. Each custom skin has a name that works across the server. Players apply the skin with `/skin `. Create a custom skin with a command or a skin file. ## Choose a custom skin name [#choose-a-custom-skin-name] SkinsRestorer stores custom skins in the database or in local files. A custom skin name applies to the complete server. For example, create a custom skin named `Dinnerbone`. Then `/skin Dinnerbone` applies the custom skin instead of the Minecraft account skin. Do not use the name of a player on your server. The custom skin replaces the account skin for that name. To change another player's skin, use `/skin [name] [playername]`. Do not create a custom skin for this task. ## Create a custom skin [#create-a-custom-skin] ### Run a command [#run-a-command] Run `/sr createcustom ` to create a custom skin from a URL. ### Skinfile Generator [#skinfile-generator] The [Skinfile Generator](/generator) converts a `.png` skin file to the `.customskin` format. The Skinfile Generator works only with file storage. If you use MySQL, run `/sr createcustom` instead. Use the Skinfile Generator: 1. Save your skin as a `.png` file. 2. Open the [Skinfile Generator](/generator). 3. Select **Browse**. 4. Select the skin file. 5. Enter an optional skin name. Use lowercase letters and no spaces. 6. Select **Upload!**. 7. Download the `name.customskin` file. 8. Put the file in `plugins/SkinsRestorer/skins`. 9. If you use a proxy, put the file on the proxy. 10. Run `/skin ` to apply the skin. ## Apply custom default skins [#apply-custom-default-skins] To use a custom skin as the server default: 1. Create a custom skin with a method on this page. 2. Put the file in the skin folder on the proxy or Spigot server. 3. Enable default skins in `config.yml`. 4. Run `/sr reload`. SkinsRestorer applies the default skin to players who have not selected another skin. # Features URL: /docs/features Learn how to use SkinsRestorer's features. SkinsRestorer can apply and store skins. It also provides tools to edit and upload them. ## Features [#features] Select the feature that you want to use. # Skin Design URL: /docs/features/skin-design Create a valid Minecraft skin for SkinsRestorer. Players and administrators can apply custom skins with SkinsRestorer. A skin is a `64x64` PNG image on the Minecraft CDN. Mojang signs each skin with its Yggdrasil private key. You do not need to understand this process to create a skin. This guide explains the skin format and shows how to get or create a skin. ## Technical info [#technical-info] Minecraft skins use a specific image format. ### Skin format [#skin-format] Skins are `64x64` pixel `.png` images. Each skin has an inner layer and an outer layer. The inner layer **must** be opaque. The outer layer can use transparent pixels for hats, glasses, and other details. The Minecraft client can hide parts of the outer layer. This option also works with SkinsRestorer skins. Open the skin settings in Minecraft. Then select the outer-layer body parts that you want to show. This [video by @Jonas\_Jones](https://youtu.be/ib8SllVoRy0?t=192) shows the option. The file stores the head, body, arms, and legs in fixed locations. Some parts of the image are unused. ### Classic and slim skins [#classic-and-slim-skins] Minecraft supports two player models: * **Classic or Steve:** The arms are four pixels wide. * **Slim or Alex:** The arms are three pixels wide. If you select the wrong model, black lines can appear on the arms. ### More information [#more-information] You can read more about skins on the [Minecraft Wiki](https://minecraft.wiki/w/Skin) and the [official Minecraft website](https://help.minecraft.net/hc/en-us/articles/4408894664461-Minecraft-Skins-for-Java-Edition). Both sites provide classic and slim skin templates. ## Get or make a custom skin [#get-or-make-a-custom-skin] Download an existing skin or create a new one. ### Premade skins [#premade-skins] Find existing skins on sites such as [NameMC](https://namemc.com) or [The Skindex](https://minecraftskins.com). ### Make your own skin [#make-your-own-skin] You can use a skin editor or a general image editor. #### Use a skin editor [#use-a-skin-editor] Use a skin editor such as [Novaskin](https://novaskin.me). You can draw on a 3D model or use an existing skin as a template. #### Design your skin [#design-your-skin] You can also use [GIMP](https://www.gimp.org/), [Adobe Photoshop](https://www.adobe.com/products/photoshop.html), [Paint.net](https://getpaint.net), or [Pixlr](https://pixlr.com). Save the skin as a `64x64` pixel `.png` file. The [Minecraft website](https://help.minecraft.net/hc/en-us/articles/4408894664461-Minecraft-Skins-for-Java-Edition) provides templates. ## Skin problems [#skin-problems] Use these steps to correct common skin problems. ### Your skin looks blurry [#your-skin-looks-blurry] An image viewer can make a small skin look blurry when it enlarges the image. Open the skin in GIMP or Photoshop to inspect the pixels. ### Your skin has black lines [#your-skin-has-black-lines] Black lines usually mean that the selected player model is wrong. Select the correct model in the launcher or SkinsRestorer command. You can also edit the image for the correct model. ### An HD skin does not work [#an-hd-skin-does-not-work] The standard Minecraft client supports only `64x64` skins. It does not support HD skins. Therefore, SkinsRestorer cannot apply them. # Skin Edit URL: /docs/features/skin-edit Edit your current skin and apply the new version. Use `/skin edit` to open your current skin in an editor. Then upload the changed skin and apply it. ## Editing and uploading your skin [#editing-and-uploading-your-skin] ### Run the command [#run-the-command] Run `/skin edit` in chat. SkinsRestorer gives you a link to the skin editor. ### Edit the skin [#edit-the-skin] Change the skin in the editor. Then select **Save**. Save edited skin ### Save the skin image [#save-the-skin-image] Find the 2D skin template on the left. Right-click the image. Then select **Save image as**. Save image ### Upload using the /upload page [#upload-using-the-upload-page] Open the [/upload](/upload) page. Upload the saved skin PNG. The page creates a `/skin url` command. For more information, read the [Skin URL Upload guide](/docs/features/skin-url). ### Apply your skin [#apply-your-skin] Copy the command. Paste it into the game chat or console. Keep the URL inside quotation marks. Paid MineSkin plans above Lite include higher limits and more features. Visit the MineSkin API keys page and use coupon code SKINSRESTORER10. The code gives you 10% off the first three months. SkinsRestorer does not receive a commission. # Skin Upload URL: /docs/features/skin-upload Upload and apply a custom skin PNG. You can apply a custom skin PNG from the website or a public URL. ## In-game command [#in-game-command] Run `/skin upload` in the game to see upload information. This command requires the `skinsrestorer.command.set.url` permission. Then use one of these methods. ## Upload methods [#upload-methods] ### Method 1: Use the website [#method-1-use-the-website] Use the [/upload](/upload) page to upload a skin from your computer. 1. Open [skinsrestorer.net/upload](/upload). 2. Select your skin PNG file. 3. Select **Generate /skin url**. 4. Copy the command. 5. Paste the command into the game chat. See the [Skin URL Upload guide](/docs/features/skin-url) for detailed instructions. ### Method 2: Direct URL command [#method-2-direct-url-command] If the skin has a public URL, use `/skin url`: ``` /skin url "https://example.com/myskin.png" ``` For a slim skin, add the variant: ``` /skin url "https://example.com/myskin.png" slim ``` The URL must be public and must point directly to a PNG file. Put the URL inside quotation marks. ## Skin variants [#skin-variants] You can select the arm model: | Variant | Description | | --------- | ----------------------------------------- | | `classic` | Standard Steve-style arms (4 pixels wide) | | `slim` | Alex-style arms (3 pixels wide) | If you do not enter a variant, SkinsRestorer detects it from the skin file. ## Supported formats [#supported-formats] * **Dimensions**: 64x64 pixels (modern) or 64x32 pixels (legacy) * **Format**: PNG only * **File size**: Under 3 MB * **Transparency**: Supported for overlay layers ## How it works [#how-it-works] When you apply a skin from a URL, this process occurs: 1. SkinsRestorer sends the URL to [MineSkin](https://mineskin.org). 2. MineSkin applies the skin to an account in its Minecraft account pool. 3. MineSkin gets signed skin data from Mojang. 4. SkinsRestorer applies the data to your player. The Minecraft client shows only skin data with a valid Mojang signature. For higher limits, add a [MineSkin API key](https://mineskin.org/apikey) to `config.yml`. Code `SKINSRESTORER10` gives you 10% off the first three months of plans above Lite. ## URL restrictions [#url-restrictions] Server administrators can restrict skin upload URLs. If `commands.restrictSkinUrls.enabled` is `true`, SkinsRestorer accepts only URLs from the configured domains. The default domains are: * `https://i.imgur.com` * `https://storage.googleapis.com` * `https://cdn.discordapp.com` * `https://textures.minecraft.net` ## Troubleshooting [#troubleshooting] ### `Invalid URL` [#invalid-url] * Make sure that the URL points directly to a PNG file. * Make sure that the URL is public. * If the URL contains special characters, put it inside quotation marks. ### `Rate limited` [#rate-limited] MineSkin limits the number of skin requests. * Wait a few minutes, then try again. * For higher limits, add a MineSkin API key. ### The skin does not apply correctly [#the-skin-does-not-apply-correctly] * Make sure that the PNG is 64x64 or 64x32 pixels. * For Alex-style arms, add the `slim` variant. * Make sure that the file is a PNG, not a renamed JPG file. # Skin URL Upload URL: /docs/features/skin-url Create a /skin url command from a skin PNG. The [/upload](/upload) page converts a skin PNG into a `/skin url` command. MineSkin processes the uploaded file. Paid MineSkin plans above Lite include higher limits and more features. Visit the MineSkin API keys page and use coupon code SKINSRESTORER10. The code gives you 10% off the first three months. SkinsRestorer does not receive a commission. ## Before you start [#before-you-start] Save a valid Minecraft skin PNG on your computer. The image must be 64x64 or 64x32 pixels. If you need a skin, follow the [skin design guide](/docs/features/skin-design). ## Generate the command with /upload [#generate-the-command-with-upload] ### Open the /upload page [#open-the-upload-page] Open the [/upload](/upload) page. The page shows an upload area and a **Generate /skin url** button. ### Select your skin PNG [#select-your-skin-png] Drag the file into the upload area. You can also select **Choose file**. Make sure that the preview shows the correct skin. ### Copy the generated command [#copy-the-generated-command] Select **Generate /skin url**. The site uploads the PNG and creates a command. Use the copy button. You can also copy the `/skin url "https://..."` text manually. Paste the command into the game chat or console. Keep the URL inside quotation marks. ## Troubleshooting [#troubleshooting] * **The upload fails:** Make sure that the PNG is smaller than 3 MB. Use standard Minecraft skin dimensions. * **The command has no quotation marks:** Put the URL inside quotation marks. * **You changed the skin:** Upload it again to create a new URL. You do not need a separate image host. SkinsRestorer and MineSkin process the upload. # Installation on Bukkit/Spigot/Paper URL: /docs/installation/bukkit Learn how to install SkinsRestorer on your Bukkit/Spigot/Paper server. Before you start, read the [main installation page](/docs/installation). If you use BungeeCord or Velocity, use the [BungeeCord guide](/docs/installation/bungeecord) or the [Velocity guide](/docs/installation/velocity) instead. ## Install the plugin [#install-the-plugin] ### Download the plugin [#download-the-plugin] Download the latest version from [Modrinth](https://modrinth.com/plugin/skinsrestorer). ### Add the plugin [#add-the-plugin] Put `SkinsRestorer.jar` in the `plugins` folder. ### Restart the server [#restart-the-server] Restart the server with `/restart` or `/stop`. CAUTION: Do not use `/reload` or PlugMan. These tools can break SkinsRestorer. ### Make sure that the plugin works [#make-sure-that-the-plugin-works] Run `/plugins`. SkinsRestorer must appear in green. If SkinsRestorer is red or absent, read the server log for errors. ### Configure the plugin [#configure-the-plugin] Continue to the [configuration guide](/docs/configuration). # Installation on BungeeCord URL: /docs/installation/bungeecord Learn how to install SkinsRestorer on your BungeeCord proxy. Before you start, read the [main installation page](/docs/installation). ## Install the plugin [#install-the-plugin] Install SkinsRestorer on the proxy and every backend server. Some features do not work without the backend installation. Waterfall uses the same installation process. SkinsRestorer does not support FlameCord, Aegis, or other BungeeCord-like proxies. ### Download the plugin [#download-the-plugin] Download the latest version from [Modrinth](https://modrinth.com/plugin/skinsrestorer). ### Install the proxy plugin [#install-the-proxy-plugin] Put `SkinsRestorer.jar` in the `plugins` folder of the **BungeeCord proxy**. ### Install the backend plugin [#install-the-backend-plugin] Put `SkinsRestorer.jar` in the `plugins` folder of **every Spigot server**. ### Configure player information forwarding [#configure-player-information-forwarding] Follow the [BungeeCord forwarding guide](https://www.spigotmc.org/wiki/bungeecord-installation/#post-installation). SkinsRestorer needs forwarding to communicate with backend servers. Make sure that these values are set: ```yaml filename="spigot.yml" /true/ settings: bungeecord: true ``` ```properties filename="server.properties" /false/ online-mode=false ``` ### Restart the network [#restart-the-network] Restart all Spigot servers and the BungeeCord proxy. Use `/restart`, `/stop`, or `/end`. ### Make sure that Proxy Mode is active [#make-sure-that-proxy-mode-is-active] Find this message in the log of each Spigot server: ```ansi filename="logs/latest.log" [SkinsRestorer] ---------------------------------------------- [SkinsRestorer]  +==================+ [SkinsRestorer]  | SkinsRestorer | [SkinsRestorer]  |------------------| [SkinsRestorer]  | Proxy Mode | [SkinsRestorer]  +==================+ [SkinsRestorer] ---------------------------------------------- ``` If the message is absent, make sure that player information forwarding is correct. ### Configure the plugin [#configure-the-plugin] [Configure SkinsRestorer](/docs/configuration) on the BungeeCord proxy. ### Copy the configuration [#copy-the-configuration] Copy the same `plugins/SkinsRestorer/config.yml` file to the proxy and every backend server. ### Restart the network again [#restart-the-network-again] Restart all Spigot servers and the BungeeCord proxy. ### Read the logs [#read-the-logs] Read the proxy and server logs. If you find an error, send it to us on [Discord](https://skinsrestorer.net/discord). ### Test the plugin [#test-the-plugin] Join the network and use `/skin Notch`. # Installation on Fabric URL: /docs/installation/fabric Learn how to install the SkinsRestorer mod on Fabric-based Minecraft servers. Before you start, read the [main installation page](/docs/installation). The Fabric mod supports **only the latest Minecraft release**. It does not support older versions. On a supported version, the Fabric mod works like the Bukkit plugin. It uses the same commands, configuration, and permissions. ## Install the mod [#install-the-mod] ### Prepare your server [#prepare-your-server] Install [Fabric Loader](https://fabricmc.net/use/server/) for the latest Minecraft version. If Fabric is already installed, update it to the latest release. ### Install dependencies [#install-dependencies] Download the matching [Fabric API](https://modrinth.com/mod/fabric-api) version. Put the file in the server's `mods` folder. ### Add SkinsRestorer [#add-skinsrestorer] Download the latest SkinsRestorer mod from [Modrinth](https://modrinth.com/mod/skinsrestorer). Put it in the same `mods` folder. ### Start the server [#start-the-server] Start or restart the Fabric server. Read the console for warnings or missing dependencies. ### Make sure that the mod works [#make-sure-that-the-mod-works] Join the server and run `/skinsrestorer status`. ### Configure SkinsRestorer [#configure-skinsrestorer] Edit the files in `config/SkinsRestorer/`. The [configuration guide](/docs/configuration) explains each option. ## Need help? [#need-help] If you need help, save the latest server log. Send the log and your Fabric Loader version on our [Discord server](https://skinsrestorer.net/discord). # Installation URL: /docs/installation Learn how to install SkinsRestorer on your Minecraft server. Use these guides to install SkinsRestorer on your server or proxy. If you need help, ask a question on our [Discord server](https://skinsrestorer.net/discord). ## Requirements [#requirements] Before you install SkinsRestorer, make sure that your server has: Most Minecraft hosting providers meet these requirements. * Java 17 or newer * Network access to the [required domains](/docs/troubleshooting/firewall) * A [supported Minecraft version and platform](https://github.com/SkinsRestorer/SkinsRestorer/blob/HEAD/README.md#telescope-compatibility) ## Select your platform [#select-your-platform] Select the platform that runs your server or proxy. The Fabric and NeoForge releases support **only the latest Minecraft version**. They provide the same features as the Bukkit plugin on that version. # Installation on NeoForge URL: /docs/installation/neoforge Learn how to install the SkinsRestorer mod on NeoForge-based Minecraft servers. Before you start, read the [main installation page](/docs/installation). The NeoForge mod supports **only the latest Minecraft release**. It does not support older versions. On a supported version, the NeoForge mod works like the Bukkit plugin. It uses the same features and configuration. ## Install the mod [#install-the-mod] These steps also apply to Forge forks that can load NeoForge mods. ### Install NeoForge [#install-neoforge] Download the latest NeoForge installer from [neoforged.net](https://neoforged.net/). Install it for the newest Minecraft version. ### Create or update the mods folder [#create-or-update-the-mods-folder] Run the generated `run.bat` or `run.sh` file once. NeoForge creates its folders, including `mods`. If NeoForge is already installed, update it to the latest build. ### Add SkinsRestorer [#add-skinsrestorer] Download the latest SkinsRestorer mod from [Modrinth](https://modrinth.com/mod/skinsrestorer). Put it in the server's `mods` folder. ### Start the server [#start-the-server] Start the server. Read the console for errors or missing dependencies. ### Make sure that the mod works [#make-sure-that-the-mod-works] Run `/skinsrestorer status` or `/sr status` in the game or server console. ### Configure SkinsRestorer [#configure-skinsrestorer] Edit the files in `config/SkinsRestorer/`. The [configuration guide](/docs/configuration) explains each option. ## Need help? [#need-help] If you need help, send the latest server log on our [Discord server](https://skinsrestorer.net/discord). # Quick Start Guide URL: /docs/installation/quick-start Install SkinsRestorer on a single server or proxy network. Select your server setup. Then complete the steps in that tab. ## Choose your setup [#choose-your-setup] ### Single Server Setup [#single-server-setup] Use this setup for one Bukkit, Spigot, or Paper server without a proxy. 1. Download SkinsRestorer from [Modrinth](https://modrinth.com/plugin/skinsrestorer). 2. Put `SkinsRestorer.jar` in the `plugins` folder. 3. Restart the server. The default configuration works for a single server. **Optional configuration changes:** ```yaml filename="plugins/SkinsRestorer/config.yml" # Optional: Set default skins for players without Mojang accounts storage: defaultSkins: enabled: true list: - "" # Optional: Reduce cooldown for smaller servers commands: skinChangeCooldown: 15 ``` **Test the plugin:** Run this command in the game. ``` /skin Notch ``` ### Small Network Setup [#small-network-setup] Use this setup for a BungeeCord or Velocity network with two to five backend servers. 1. Download SkinsRestorer. 2. Place `SkinsRestorer.jar` in: * The proxy's `plugins` folder. * Each backend server's `plugins` folder. 3. Configure player information forwarding. 4. Restart all servers. **Proxy configuration:** ```yaml filename="plugins/SkinsRestorer/config.yml" # Default config works well for small networks # No database needed - file storage is fine ``` **Backend server configuration:** ```yaml filename="plugins/SkinsRestorer/config.yml" # Should auto-detect proxy mode # Verify by checking logs for "Proxy Mode" ``` **Test the network:** * Find "Proxy Mode" in the startup log of each backend server. * Run `/skin Notch`. * Switch to another server. The skin must stay active. Copy the same `config.yml` file to the proxy and all backend servers. ### Large Network Setup [#large-network-setup] Use this setup for five or more servers, many players, or backend API access. This setup requires: * MySQL database * BungeeCord or Velocity proxy 1. Create a MySQL database. 2. Install SkinsRestorer on the proxy and all backend servers. 3. Configure the same database on all servers. 4. Restart the network. **Proxy configuration:** ```yaml filename="plugins/SkinsRestorer/config.yml" database: enabled: true host: your-mysql-host port: 3306 database: skinsrestorer username: sr_user password: secure_password maxPoolSize: 20 # Optional: Get a MineSkin API key for high volume api: mineSkinApiKey: "your-key-here" ``` **Backend server configuration:** ```yaml filename="plugins/SkinsRestorer/config.yml" # Same database config as proxy database: enabled: true host: your-mysql-host port: 3306 database: skinsrestorer username: sr_user password: secure_password maxPoolSize: 10 # API will work on backends with shared database server: proxyMode: detection: AUTO api: true ``` This setup provides: * One shared skin database * API access on all servers * Better performance for large networks * Skin access for plugins such as BedWars and Dynmap ## Post-installation checklist [#post-installation-checklist] After the installation, make sure that each item works: * [ ] `/skin Notch` changes your skin * [ ] `/skins` opens the GUI * [ ] Skins stay active after players rejoin * [ ] On a proxy network, skins stay active when players switch servers * [ ] The console logs contain no errors ## Common quick fixes [#common-quick-fixes] | Issue | Solution | | ------------------------ | ------------------------------------------------------------------------------ | | Commands do not work | Grant permission: `/lp user permission set skinsrestorer.player true` | | A skin does not apply | Allow connections to `*.skinsrestorer.net` through the firewall | | Proxy Mode is not active | Configure player information forwarding | | Database errors occur | Make sure that the credentials are correct and MySQL is available | ## Next steps [#next-steps] * [Full configuration options](/docs/configuration/options) * [Commands and permissions](/docs/configuration/commands-permissions) * [Troubleshooting guide](/docs/troubleshooting/common-issues) # Installation on Velocity URL: /docs/installation/velocity Learn how to install SkinsRestorer on your Velocity proxy. Before you start, read the [main installation page](/docs/installation). ## Install the plugin [#install-the-plugin] Install SkinsRestorer on the proxy and every backend server. Some features do not work without the backend installation. Use Paper or a Paper fork for the backend servers. ### Download the plugin [#download-the-plugin] Download the latest version from [Modrinth](https://modrinth.com/plugin/skinsrestorer). ### Install the proxy plugin [#install-the-proxy-plugin] Put `SkinsRestorer.jar` in the `plugins` folder of the **Velocity proxy**. ### Install the backend plugin [#install-the-backend-plugin] Put `SkinsRestorer.jar` in the `plugins` folder of **every Spigot server**. ### Configure player information forwarding [#configure-player-information-forwarding] Follow the [Velocity forwarding guide](https://docs.papermc.io/velocity/player-information-forwarding). SkinsRestorer needs forwarding to communicate with backend servers. ### Restart the network [#restart-the-network] Restart all Spigot servers and the Velocity proxy. Use `/restart`, `/stop`, or `/end`. ### Make sure that Proxy Mode is active [#make-sure-that-proxy-mode-is-active] Find this message in the log of each Spigot server: ```ansi filename="logs/latest.log" [SkinsRestorer] ---------------------------------------------- [SkinsRestorer]  +==================+ [SkinsRestorer]  | SkinsRestorer | [SkinsRestorer]  |------------------| [SkinsRestorer]  | Proxy Mode | [SkinsRestorer]  +==================+ [SkinsRestorer] ---------------------------------------------- ``` If the message is absent, make sure that player information forwarding is correct. ### Configure the plugin [#configure-the-plugin] [Configure SkinsRestorer](/docs/configuration) on the Velocity proxy. ### Copy the configuration [#copy-the-configuration] Copy the same `plugins/SkinsRestorer/config.yml` file to the proxy and every backend server. ### Restart the network again [#restart-the-network-again] Restart all Spigot servers and the Velocity proxy. ### Read the logs [#read-the-logs] Read the proxy and server logs. If you find an error, send it to us on [Discord](https://skinsrestorer.net/discord). ### Test the plugin [#test-the-plugin] Join the network and use `/skin Notch`. # Avatar URL URL: /docs/integrations/avatar-url Show SkinsRestorer avatars in another plugin. Use a SkinsRestorer placeholder to show a player's current head in another plugin. For Discord messages, use the guide for [DiscordSRV](/docs/integrations/discordsrv) or [Discord-MC-Chat](/docs/integrations/discord-mc-chat). ### Prepare your server [#prepare-your-server] Install the latest version of [SkinsRestorer](/docs/installation). Then install the latest version of [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/). Make sure that the other plugin accepts PlaceholderAPI placeholders in avatar URLs. ### Configure the plugin [#configure-the-plugin] Find the avatar URL in the plugin's configuration or message file. Replace it with: ```yaml https://mc-heads.net/avatar/%skinsrestorer_texture_id_or_steve%.png ``` ### Reload the plugin [#reload-the-plugin] Reload the plugin to apply the change. ### Test the avatar [#test-the-avatar] Send a message that uses the avatar. It must show the player's SkinsRestorer skin. # Discord-MC-Chat URL: /docs/integrations/discord-mc-chat Show SkinsRestorer avatars in Discord-MC-Chat. Use the texture placeholder to show SkinsRestorer skins in Discord-MC-Chat messages. ## Setup instructions [#setup-instructions] ### Prepare your server [#prepare-your-server] Install the latest version of [SkinsRestorer](/docs/installation). Then install the latest version of [Discord-MC-Chat](https://modrinth.com/mod/discord-mc-chat). ### Configure Discord-MC-Chat [#configure-discord-mc-chat] Open `./config/discord-mc-chat.json`. Find the `avatarApi` value: ```json filename="config/discord-mc-chat.json" "avatarApi": "https://mc-heads.net/avatar/{player_uuid}.png", ``` Replace it with: ```json filename="config/discord-mc-chat.json" "avatarApi": "https://mc-heads.net/avatar/{player_textures}.png", ``` ### Reload Discord-MC-Chat [#reload-discord-mc-chat] Run `/dmcc reload` in the game or console. You can also run `/reload` in Discord. ### Test the avatar [#test-the-avatar] Send a message. Discord-MC-Chat must show the player's SkinsRestorer skin. # DiscordSRV URL: /docs/integrations/discordsrv Show SkinsRestorer avatars in DiscordSRV. Use PlaceholderAPI to show SkinsRestorer skins in DiscordSRV messages. ## Setup instructions [#setup-instructions] ### Prepare your server [#prepare-your-server] Install the latest version of [SkinsRestorer](/docs/installation). Then install [DiscordSRV](https://www.spigotmc.org/resources/discordsrv.18494/). Also install [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/). ### Configure DiscordSRV [#configure-discordsrv] Open the DiscordSRV `config.yml` file. Find the `Embed & webhook image/avatar url format` section: ```yaml filename="plugins/DiscordSRV/config.yml" AvatarUrl: https://crafatar.com/avatars/{uuid - nodashes}.png?size={size}&overlay#{texture} ``` Replace it with: ```yaml filename="plugins/DiscordSRV/config.yml" AvatarUrl: https://mc-heads.net/avatar/%skinsrestorer_texture_id_or_steve%.png#{username} ``` ### Reload DiscordSRV [#reload-discordsrv] Run `/discord reload`. ### Test the avatar [#test-the-avatar] Send a message. DiscordSRV must show the player's SkinsRestorer skin. # Integrations URL: /docs/integrations Learn how to integrate third-party software with SkinsRestorer. SkinsRestorer can share skin data with other plugins and services. ## Integrations [#integrations] Select the plugin or service that you want to configure. # MineSkin Integration URL: /docs/integrations/mineskin Add a MineSkin API key for higher upload limits. SkinsRestorer uses [MineSkin](https://mineskin.org) to convert custom PNG files into valid Minecraft skins. MineSkin works without an API key. An API key provides higher limits and more features. ## Why use a MineSkin API key? [#why-use-a-mineskin-api-key] | Feature | Without API Key | With API Key | | -------------- | --------------- | ------------------------ | | Request limit | Low | Higher (depends on plan) | | Request speed | Slower | Faster | | Secret skins | No | Yes | | Priority queue | No | Yes | ## Getting an API key [#getting-an-api-key] 1. Open [mineskin.org/apikey](https://mineskin.org/apikey). 2. Create an account or sign in. 3. Select a plan. 4. Create an API key. Code `SKINSRESTORER10` gives you 10% off the first three months of plans above Lite. SkinsRestorer does not receive a commission. ## Configuring your API key [#configuring-your-api-key] Add your API key to `config.yml`: ```yaml filename="config.yml" api: mineSkinApiKey: "your-api-key-here" ``` Then reload SkinsRestorer: ``` /sr reload ``` ## Secret skins [#secret-skins] If `mineSkinSecretSkins` is enabled, MineSkin does not show generated skins in its public gallery. ```yaml filename="config.yml" api: mineSkinApiKey: "your-api-key-here" mineSkinSecretSkins: true ``` Use this option for: * Custom server skins that must stay private * Event-specific skins * Private branding ## Rate limits and batching [#rate-limits-and-batching] SkinsRestorer can group Mojang API requests. This reduces rate-limit errors. ```yaml filename="config.yml" api: mojangBatchWindowSeconds: 1 ``` The value sets the request window in seconds. The default value of one second works for most servers. For a server with heavy traffic: * Increase the request window to two or three seconds. * Use a MineSkin plan with higher limits. * Monitor the MineSkin usage dashboard. ## What MineSkin does [#what-mineskin-does] MineSkin applies your PNG to an account in its Minecraft account pool. Mojang then creates signed skin data for SkinsRestorer. MineSkin creates only skin textures. It cannot create capes because Mojang assigns capes to specific accounts. Read [Cape Support](/docs/features/capes) for more information. ## Troubleshooting [#troubleshooting] ### `Rate limited` [#rate-limited] * The API key can be above its request limit. * Wait a few minutes, then try again. * For higher limits, select a different MineSkin plan. ### `Invalid API key` [#invalid-api-key] * Make sure that you copied the complete key. * Make sure that the key did not expire. * Create a new key on the MineSkin website. ### Slow skin generation [#slow-skin-generation] * Read the queue status on the MineSkin dashboard. * Plans with higher limits get priority. * High server load can make generation slower. ## MineSkin plans comparison [#mineskin-plans-comparison] | Plan | Best for | | ------------- | ----------------------------- | | Free (no key) | Testing, very low volume | | Lite | Small servers, basic features | | Standard | Medium servers, higher limits | | Pro | Large networks, high volume | Visit [mineskin.org/apikey](https://mineskin.org/apikey) for current pricing and features. # PlaceholderAPI URL: /docs/integrations/placeholderapi Use SkinsRestorer data in PlaceholderAPI placeholders. SkinsRestorer provides PlaceholderAPI placeholders. It registers them automatically when both plugins are installed. ## SkinsRestorer placeholders [#skinsrestorer-placeholders] The following placeholders are available. If a database error occurs, a placeholder returns `Error` and records the error in the log. | Placeholder | Description | | ------------------------------------------ | ------------------------------------------------------------------ | | `%skinsrestorer_skin_name%` | Selected skin name, or `Error` when no skin is set. | | `%skinsrestorer_skin_name_or_empty%` | Selected skin name, or an empty string when no skin is set. | | `%skinsrestorer_skin_name_or_player_name%` | Selected skin name, or the player name when no skin is set. | | `%skinsrestorer_texture_url%` | Applied texture URL, or `Error` when no skin exists. | | `%skinsrestorer_texture_url_or_empty%` | Applied texture URL, or an empty string when no skin exists. | | `%skinsrestorer_texture_url_or_steve%` | Applied texture URL, or the Steve texture URL when no skin exists. | | `%skinsrestorer_texture_url_or_alex%` | Applied texture URL, or the Alex texture URL when no skin exists. | | `%skinsrestorer_texture_id%` | Applied texture ID, or `Error` when no skin exists. | | `%skinsrestorer_texture_id_or_empty%` | Applied texture ID, or an empty string when no skin exists. | | `%skinsrestorer_texture_id_or_steve%` | Applied texture ID, or the Steve texture ID when no skin exists. | | `%skinsrestorer_texture_id_or_alex%` | Applied texture ID, or the Alex texture ID when no skin exists. | ## Texture IDs and URLs [#texture-ids-and-urls] A texture ID identifies a skin on the Minecraft Content Delivery Network (CDN). The Minecraft client uses the texture URL to download the skin. For example, the Steve skin URL ends with its texture ID: * URL: `https://textures.minecraft.net/texture/6d3b06c38504ffc0229b9492147c69fcf59fd2ed7885f78502152f77b4d50de1` * Texture ID: `6d3b06c38504ffc0229b9492147c69fcf59fd2ed7885f78502152f77b4d50de1` # Common issues URL: /docs/troubleshooting/common-issues Find the cause of a common SkinsRestorer problem. This page lists common causes of SkinsRestorer problems. ## Host-specific issues [#host-specific-issues] Your Minecraft hosting provider can block some SkinsRestorer functions. ### Servers with a forced proxy [#servers-with-a-forced-proxy] Some providers, such as Minehut, put each server behind a proxy. Customers cannot always configure this proxy. If the proxy manages skins and capes, it can override SkinsRestorer. Ask the hosting provider if it can disable the proxy skin system. ### Servers with a misconfigured firewall [#servers-with-a-misconfigured-firewall] A hosting firewall can block the SkinsRestorer APIs. If `/sr status` reports connection errors, use the [firewall guide](/docs/troubleshooting/firewall). ## Platform-specific issues [#platform-specific-issues] Unsupported server software can cause errors. ### Supported platforms [#supported-platforms] We only support the following platforms: * Bukkit * Spigot * Paper and supported forks, such as Purpur and Pufferfish * Folia * BungeeCord (and forks like Waterfall) * Velocity * Latest Fabric * Latest NeoForge Hybrid platforms such as Magma, Mohist, and Cardboard are not supported. ## Plugin-specific issues [#plugin-specific-issues] Other plugins can change player profiles. These changes can override SkinsRestorer. ### Plugins with known issues [#plugins-with-known-issues] Read the [incompatibility list](/docs/troubleshooting/incompatibility-list). If a plugin is listed, contact its developer. ## Client-specific issues [#client-specific-issues] Some launchers include a skin system that overrides server skins. Use the [launcher guide](/docs/troubleshooting/launcher-issues) to disable that system. ## Get more help [#get-more-help] If these guides do not correct the problem, contact the SkinsRestorer team: * [Discord](https://skinsrestorer.net/discord) * [GitHub Issues](https://github.com/SkinsRestorer/SkinsRestorer/issues) # Debugging and Logs URL: /docs/troubleshooting/debugging Use logs and debug tools to find SkinsRestorer problems. SkinsRestorer provides commands and logs that show errors and connection problems. ## Debug mode [#debug-mode] Enable debug logging to record API requests and internal actions. ```yaml filename="config.yml" dev: debug: true ``` Then restart the server or reload the plugin: ``` /sr reload ``` Debug mode records: * All API requests to Mojang/MineSkin/SkinsRestorer endpoints * Skin data processing steps * Cache hits and misses * Plugin messaging channel communication CAUTION: Debug mode writes many log messages. Enable it only while you collect information. Then disable it. ## Using /sr dump [#using-sr-dump] Run `/sr dump` to collect support information: ``` /sr dump ``` The command uploads: * Server and plugin version information * Your configuration (sensitive data redacted) * Recent relevant log entries * Installed plugins list * System information The command returns a URL such as `https://bytebin.lucko.me/xxxxx`. Send this URL to support. ## Using /sr status [#using-sr-status] Use this command to show the connection status of required API endpoints: ``` /sr status ``` The command shows: * `eclipse.skinsrestorer.net` - UUID and profile lookups * `axolotl.skinsrestorer.net` - MineSkin URL decryption * `cool-skins.skinsrestorer.net` - Recommended skins * Mojang API endpoints * MineSkin API (if configured) If an endpoint is unavailable, use the [firewall guide](/docs/troubleshooting/firewall). ## Understanding log messages [#understanding-log-messages] ### Startup messages [#startup-messages] **Healthy startup:** ``` [SkinsRestorer] +==================+ [SkinsRestorer] | SkinsRestorer | [SkinsRestorer] |------------------| [SkinsRestorer] | Server Mode | [SkinsRestorer] +==================+ ``` or for proxy networks: ``` [SkinsRestorer] | Proxy Mode | ``` **Warning messages:** ``` [SkinsRestorer] Proxy mode files are deprecated, please use the config file instead. ``` This warning means that old `.txt` configuration files exist. Move their values to `config.yml`. ### Common log errors [#common-log-errors] **Connection errors:** ``` [SkinsRestorer] Failed to connect to eclipse.skinsrestorer.net ``` Make sure that the firewall permits the required connections. **Rate limit errors:** ``` [SkinsRestorer] Rate limited by Mojang API ``` SkinsRestorer sends this request again automatically. **Database errors:** ``` [SkinsRestorer] Failed to connect to database ``` Make sure that MySQL is available and the credentials are correct. ## Log file locations [#log-file-locations] | Platform | Log location | | ------------------- | ----------------- | | Bukkit/Spigot/Paper | `logs/latest.log` | | BungeeCord | `proxy.log.0` | | Velocity | `logs/latest.log` | | Fabric/NeoForge | `logs/latest.log` | ## Filtering logs for SkinsRestorer [#filtering-logs-for-skinsrestorer] Use the command for your operating system to find SkinsRestorer messages. **Linux/Mac:** ```bash grep -i skinsrestorer logs/latest.log ``` **Windows PowerShell:** ```powershell Select-String -Path logs/latest.log -Pattern "skinsrestorer" -CaseSensitive:$false ``` ## Common debugging scenarios [#common-debugging-scenarios] ### Skin not applying [#skin-not-applying] 1. Enable debug mode. 2. Run `/skin `. 3. Find these messages in the log: * "Fetching skin data for...": The API request started * "Received skin data...": SkinsRestorer received the data * "Applying skin to...": SkinsRestorer started to apply the skin * Any error messages ### Proxy mode issues [#proxy-mode-issues] 1. Find "Proxy Mode" or "Server Mode" in the startup log. 2. Run `/sr status`. 3. Make sure that security plugins permit SkinsRestorer plugin messages. ### API connectivity issues [#api-connectivity-issues] 1. Run `/sr status`. 2. If an endpoint is unavailable, examine: * Firewall rules * DNS resolution * Proxy/VPN interference ## Getting support [#getting-support] When you ask for help: 1. Run `/sr dump` and include the link. 2. Describe the expected result and the actual result. 3. Include the error messages from the log. 4. Include the server platform and version. **Support channels:** * [Discord](https://skinsrestorer.net/discord) * [GitHub Issues](https://github.com/SkinsRestorer/SkinsRestorer/issues) # Firewall URL: /docs/troubleshooting/firewall Permit the network connections that SkinsRestorer requires. This guide applies when `/sr status` shows this red message: `> Plugin currently can't fetch new skins. You might check out our Discord at ...` This message means that the server cannot connect to an API that SkinsRestorer requires. ## Permit the required connections [#permit-the-required-connections] This list can change. If the problem returns, compare your firewall rules with this page. Allow outgoing connections to these domains and ports: > All required rules are **outgoing**. SkinsRestorer does not need new incoming connections. > Your firewall only needs to accept response traffic for established connections. | Domain | Port | | ------------------------------- | ----- | | `axolotl.skinsrestorer.net` | `443` | | `eclipse.skinsrestorer.net` | `443` | | `cool-skins.skinsrestorer.net` | `443` | | `api.mojang.com` | `443` | | `sessionserver.mojang.com` | `443` | | `api.mineskin.org` | `443` | | `bytebin.lucko.me` | `443` | | `github.com` | `443` | | `api.github.com` | `443` | | `objects.githubusercontent.com` | `443` | Permit outgoing connections to port `53` on your DNS server. ## Ask your hosting provider [#ask-your-hosting-provider] If you cannot change the firewall, send this message to your hosting provider: ```ansi Title: Firewall issues Dear Mc-Service provider, I believe that your firewall setup is restricting one of my plugins to work properly, namely, SkinsRestorer. In order to allow it to function properly, I need to be able to open new outgoing connections to specific HTTP REST API services. You can see the list of required traffic at: https://skinsrestorer.net/docs/troubleshooting/firewall I kindly request that you permit such traffic for all Minecraft hosting services associated with my account. If you have any questions, feel free to contact SkinsRestorer's team via: Discord - https://skinsrestorer.net/discord Email - support@skinsrestorer.net Kind regards ``` # Incompatibility list URL: /docs/troubleshooting/incompatibility-list Find software that can conflict with SkinsRestorer. Plugins, mods, launchers, and server platforms can conflict with SkinsRestorer. This page lists known conflicts. ## Incompatible clients [#incompatible-clients] Some launchers include skin mods that override SkinsRestorer. Use the [launcher guide](/docs/troubleshooting/launcher-issues) to disable these skin systems. ## Plugin types that can cause problems [#plugin-types-that-can-cause-problems] Plugins that change player profiles can override SkinsRestorer. A world reload can then restore the old skin. * Other skin plugins like `MySKin` * `Skript` scripts that change skins * Custom world plugins * Some TabList plugins To find a plugin conflict: 1. Start a test server with only SkinsRestorer. 2. Apply a skin. 3. Add one plugin. 4. Apply the skin again. 5. Repeat steps 3 and 4 until the problem returns. The last plugin that you added is the most likely cause. ## Plugins that need a configuration change [#plugins-that-need-a-configuration-change] * **FastLogin:** Set `forwardSkin: false{:yaml}` in the FastLogin `config.yml` file. * **MundoSK:** Set `usecustomskins: false{:yaml}` in the MundoSK `config.yml` file. ## Incompatible plugins [#incompatible-plugins] These plugins have known conflicts with SkinsRestorer: * `AntiBotDeluxe` * `Nicknamer` * `OldCombatMechanics` (older versions) * `Tablisknu` * `WorldChangeScreenRemover` ## Incompatible server software [#incompatible-server-software] Some Paper and BungeeCord forks change the platform API. SkinsRestorer does not support these platforms: * `Aegis` * `FlameCord` * `Magma` * `Mohist` * `Cardboard` If you develop one of these platforms, you can submit a fix on [GitHub](https://github.com/SkinsRestorer/SkinsRestorer). # Troubleshooting URL: /docs/troubleshooting Find and correct common SkinsRestorer problems. If SkinsRestorer does not work as expected, use these guides. ## Choose a guide [#choose-a-guide] Select the guide that matches your problem. # Launcher skin issues URL: /docs/troubleshooting/launcher-issues Stop third-party launchers from replacing server skins. Some Minecraft launchers use their own skin system. That system can replace skins from SkinsRestorer. ## TLauncher [#tlauncher] Disable TLauncher skins to show server skins. ### CAUTION: TLauncher can contain malware [#caution-tlauncher-can-contain-malware] Do not use TLauncher. It can expose your account or computer to malware. For more information, watch the [video by TheMisterEpic](https://www.youtube.com/watch?v=SBTH9n6lz9o). ### How to fix [#how-to-fix] If you continue to use TLauncher, disable its skin feature. #### Watch this YouTube clip [#watch-this-youtube-clip]