Configuration Options

The plugin should be able to run without extra configuration needed, but if you need to change the plugin behavior, you're in the right place here.

After changing the configuration, you need to either reload the plugin with the command /sr reload or restart the server.

If you run a proxy network (BungeeCord/Velocity), you need to have the exact same config.yml file on the proxy and all servers. If you make a change to the config on the proxy, you need to make the same change on all servers. Make sure to reload the plugin on the proxy and all servers after changing the configuration. The /sr reload command is only available on the proxy (because all backend servers are in Proxy Mode), you'll need to restart the servers to use the new config.

File structure

Below is an example of what the file structure of the SkinsRestorer plugin looks like. Click a folder to expand it.

config.yml

Storage settings

Configure how skin data is cached and stored.

storage:
  defaultSkins:
    enabled: false
    applyForPremium: false
    list:
      - "xknat"
      - "pistonmaster"
      - "<random>"
  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", "<random>"]`	List of default skins. Use `<random>` for recommended skins
`disallowAutoUpdateSkin`	`false`	Require players to run `/skin update` manually
`skinExpiresAfter`	`15`	Minutes before re-fetching skin data from API
`uuidExpiresAfter`	`60`	Minutes before re-fetching player UUID from API

Setting cache expiration to 0 will always request fresh data from the API. This is not recommended for production servers.

Command settings

Configure command behavior, cooldowns, and restrictions.

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.<name>` 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

Configure skin behavior during player login.

login:
  noSkinIfLoginCanceled: true
  alwaysApplyPremium: false

Option	Default	Description
`noSkinIfLoginCanceled`	`true`	Don't apply skins if login is canceled (e.g., by AntiBot)
`alwaysApplyPremium`	`false`	Apply skins even for premium players on online-mode servers

Server settings (Backend only)

These settings only apply to backend servers, not proxies.

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)

These settings only apply to proxy servers (BungeeCord/Velocity).

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

Configure external API integrations.

api:
  mineSkinApiKey: ""
  mineSkinSecretSkins: false
  fetchRecommendedSkins: true
  mojangBatchWindowSeconds: 1

Option	Default	Description
`mineSkinApiKey`	(empty)	Your MineSkin API key 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

Configure the /skins GUI appearance and content.

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

These settings are in the "Danger Zone". Only modify if you understand the implications.

advanced:
  disableOnJoinSkins: false
  enablePaperJoinListener: true
  teleportRefresh: false
  noConnections: false
  playerHeadChatObjects: false

Option	Default	Description
`disableOnJoinSkins`	`false`	Don't apply skins on player join
`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

dev:
  debug: false

Option	Default	Description
`debug`	`false`	Enable debug logging for API requests and troubleshooting

Who can change skins?

With SkinsRestorer, players can use /skin <skin> to change their look. You will have to use a permissions plugin to control who can change their skin.

You can read the commands and permissions guide to learn how to control who can change skins.

Default skins

By default, SkinsRestorer applies players the skin that belongs to their Minecraft account that was set via the launcher. Some players who join your server may not own their own Minecraft account where they can set their skin. So for those cases, SkinsRestorer will set their skin to a steve skin.

Default skins are base skins set for players who did not explicitly set a skin using /skin <skin>. If a player joins the server and did set a skin using /skin <skin>, SkinsRestorer will not set their skin to a default skin and instead use the skin they set.

If you want to change this behavior, you can do so by changing the storage.defaultSkins configuration in the config.yml file. Changing it allows you to set what skin players will have when they join your server and don't have a Minecraft account associated with their username.

Additionally, if you set applyForPremium to true, SkinsRestorer will apply default skins for every player, even if they own a Minecraft account.

Disabled skins

If you want to disable certain skins from being used on your server using /skin <skin>, you can do so by changing the commands.disabledSkins configuration in the config.yml file.

This feature is useful if you want to prevent players from using, for example, explicit or inappropriate skins.

Permissions per skin

By default, SkinsRestorer allows players to set any skin when they have access to the /skin <skin> command. You can override this behavior by setting up commands.perSkinPermissions in the config.yml file. Any skin in that list will force the player to have the permissions skinsrestorer.skin.<name> to use that skin.

Configuration Options

On this page