Configuration - Suiranoil/SkinRestorer GitHub Wiki

The configuration file is located at ./config/skinrestorer/config.json and is automatically created after the first launch.

A complete configuration example is provided below.

language

  • Description: Sets the language used on the server and displayed for players who do not have the mod installed.
  • Default: "en_us"
  • Possible values: Refer to the supported languages.

join

join.refreshSkin

  • Description: Determines if the player's skin should be refetched every time they join the server.
  • Default: true
  • Possible values: true (enabled), false (disabled).

join.skipRefreshProviders

  • Description: A list of provider IDs whose skins should not be refetched when a player joins the server. If a player's current skin was set by a provider in this list, the skin refresh is skipped on join. Only applies when join.refreshSkin is true.
  • Default: []
  • Possible values: A list of provider ID strings (e.g., "mojang", "ely.by", "web", "collection", or any custom provider name).

join.applyDelay

  • Description: Sets a delay (in server ticks) before applying a saved skin after a player joins. This may help with compatibility with other mods by waiting until the player is fully loaded.
  • Default: 0
  • Possible values: Any non-negative number.

join.autoFetch

join.autoFetch.enabled

  • Description: Determines if the server fetches a skin for a player the first time they join (or after a skin reset) based on their username. Only works if no skin is saved yet.
  • Default: true
  • Possible values: true (enabled), false (disabled).
  • Note: This option is relevant only for offline or insecure servers.

join.autoFetch.overrideExisting

  • Description: Forces the server to fetch a skin from join.autoFetch.provider even when the server is in online mode (when the player already has an official skin). Only applies when join.autoFetch.provider is not set to MOJANG.
  • Default: false
  • Possible values: true (enabled), false (disabled).

join.autoFetch.provider

  • Description: Specifies which skin provider to use when join.autoFetch.enabled is set to true.
  • Default: "mojang"
  • Possible values:
    • "mojang" (or MOJANG)
    • "ely.by" (or ely_by, ELY.BY, ELY_BY)
    • "collection" (or COLLECTION)
    • Any custom provider name.
  • Note: Built-in provider names (mojang, ely.by, collection) are case-insensitive. Custom provider names are case-sensitive.

request

request.proxy

  • Description: Specifies a proxy server address for making HTTP requests.
  • Possible values: Any string formatted as hostname:port.
  • Default: ""

request.timeout

  • Description: Sets the maximum duration (in seconds) that a request for a skin can take before timing out.
  • Default: 10
  • Possible values: Any positive integer.

request.userAgent

  • Description: Sets a custom User-Agent header for outgoing HTTP requests.
  • Default: ""
  • Possible values: Any string.

providers

Provider Fields:

  • enabled
    • Description: Determines whether the skin provider is active. If a provider is disabled (false), it will not appear as an option in the /skin set command.
    • Possible Values: true (enabled), false (disabled).
    • Note: Requires a server restart to apply changes.
  • name
    • Description: Specifies how the provider is displayed in the /skin set command.
    • Possible Values: Any non-empty string, except "empty", "mojang", "ely.by", "web", "collection", "skinshuffle".
    • Note: Requires a server restart to apply changes.
  • cache
    • Description: Specifies the cache settings for the skin provider.
    • Fields
      • enabled
        • Description: Enables or disables caching for skins fetched from this provider.
        • Possible Values: true (enabled), false (disabled).
      • duration
        • Description: Specifies how long the skin should be cached (in seconds).
        • Possible Values: Any positive integer.

providers.mojang

  • Description: Configuration for the Mojang skin provider. Fetches skins from Mojang's official API by resolving a username to UUID and retrieving the player's profile.
  • Default:
    • enabled: true
    • name: "mojang"
    • cache.enabled: true
    • cache.duration: 60

providers.ely_by

  • Description: Configuration for the Ely.by skin provider. Fetches skins from the Ely.by skin system API by username.
  • Default:
    • enabled: true
    • name: "ely.by"
    • cache.enabled: true
    • cache.duration: 60

providers.mineskin

  • Description: Configuration for the Mineskin skin provider. Converts skin image URLs into game skin data using the Mineskin API. Supports both URLs and variant selection (classic/slim).
  • Additional fields
    • apiKey
      • Description: Specifies the API key for requests to the Mineskin API.
      • Possible Values: Any string.
    • proxyUrlUpload
      • Description: When enabled, the server downloads the skin image first and uploads it to the Mineskin API, instead of having Mineskin fetch the URL directly. The download will use the configured request.proxy if set.
      • Possible Values: true (enabled), false (disabled).
  • Default:
    • enabled: true
    • name: "web"
    • cache.enabled: true
    • cache.duration: 300
    • apiKey: ""
    • proxyUrlUpload: false

providers.collection

  • Description: Configuration for the Collection skin provider. Allows serving skins from local files or URLs. Uses the Mineskin API under the hood to convert skin files/URLs into game skin data.
  • Additional fields
    • sources
      • Description: List of skin sources to use as the collection pool. Skins are randomly selected from this list.
      • Possible Values:
        • File source (local file):
          • path: Path to the skin image file relative to the config directory.
          • variant: Skin variant type. classic (standard) or slim (slim arms).
        • URL source (remote):
          • url: URL to the skin image.
          • variant: Skin variant type. classic (standard) or slim (slim arms).
  • Default:
    • enabled: false
    • name: "collection"
    • cache.enabled: true
    • cache.duration: 604800
    • sources: []

providers.custom

  • Description: A list of custom skin providers. Each entry defines a provider with a specific type. Multiple custom providers can be configured simultaneously.
  • Default: []
  • Note: Requires a server restart to apply changes.

Common custom provider fields:

  • type
    • Description: Specifies the type of the custom provider.
    • Possible Values: "yggdrasil", "authlib-injector", "username-url".
  • enabled
    • Description: Determines whether the custom provider is active.
    • Possible Values: true (enabled), false (disabled).
    • Default: true
  • name
    • Description: Specifies how the provider is displayed in the /skin set command. Must be unique across all providers.
    • Possible Values: Any non-empty string, except built-in provider names.
    • Note: Custom providers with empty or duplicate names are skipped.
  • useProviderSignature
    • Description: When enabled, the skin signature from the custom provider is used instead of being re-signed using MineSkin.
    • Possible Values: true (enabled), false (disabled).
    • Default: false
  • cache
    • Description: Specifies the cache settings for the custom provider.
    • Default: enabled: true, duration: 300

yggdrasil

  • Description: Fetches skins from a Yggdrasil-compatible authentication server by resolving a username to UUID and retrieving the player's profile.
  • Additional fields:
    • baseUrl
      • Description: Base URL of the Yggdrasil server. Used as a fallback for servicesUrl and sessionUrl if they are not specified.
      • Possible Values: Any valid URL.
      • Default: ""
    • servicesUrl
      • Description: The services endpoint URL of the Yggdrasil server. If empty, falls back to baseUrl.
      • Possible Values: Any valid URL.
      • Default: ""
    • sessionUrl
      • Description: The session endpoint URL of the Yggdrasil server. If empty, falls back to baseUrl.
      • Possible Values: Any valid URL.
      • Default: ""
  • Note: Both servicesUrl and sessionUrl must be configured (either directly or through baseUrl) for the provider to work.

authlib-injector

  • Description: Fetches skins from an authlib-injector-compatible server. The server's API endpoints are automatically resolved from the base URL.
  • Additional fields:
    • baseUrl
      • Description: Base URL of the authlib-injector server.
      • Possible Values: Any valid URL.
      • Default: ""
  • Note: baseUrl must be configured for the provider to work.

username-url

  • Description: Fetches skins from a URL constructed by substituting the player's username into a URL template. The resulting URL should point to a skin image.
  • Additional fields:
    • urlTemplate
      • Description: URL template with a {username} placeholder that gets replaced with the player's username.
      • Possible Values: Any valid absolute URL containing {username}.
      • Default: ""
  • Note: urlTemplate must contain {username} and be a valid absolute URI for the provider to work.

Full Configuration Example

{
  "language": "en_us",
  "join": {
    "refreshSkin": true,
    "skipRefreshProviders": ["web", "collection"],
    "applyDelay": 0,
    "autoFetch": {
      "enabled": true,
      "overrideExisting": false,
      "provider": "mojang"
    }
  },
  "request": {
    "proxy": "proxy.example.com:8080",
    "timeout": 10,
    "userAgent": "SkinRestorer/1.0"
  },
  "providers": {
    "mojang": {
      "enabled": true,
      "name": "mojang",
      "cache": {"enabled": true, "duration": 60}
    },
    "ely_by": {
      "enabled": true,
      "name": "ely.by",
      "cache": {"enabled": true, "duration": 60}
    },
    "mineskin": {
      "enabled": true,
      "name": "web",
      "apiKey": "your_mineskin_api_key_here",
      "proxyUrlUpload": false,
      "cache": {"enabled": true, "duration": 300}
    },
    "collection": {
      "enabled": false,
      "name": "collection",
      "sources": [
        {"path": "skins/steve.png", "variant": "classic"},
        {"path": "skins/alex.png", "variant": "slim"},
        {"url": "https://example.com/custom_skin.png", "variant": "classic"}
      ],
      "cache": {"enabled": true, "duration": 604800}
    },
    "custom": [
      {
        "type": "yggdrasil",
        "enabled": true,
        "name": "my-yggdrasil",
        "baseUrl": "https://yggdrasil.example.com",
        "servicesUrl": "https://yggdrasil.example.com/api/services",
        "sessionUrl": "https://yggdrasil.example.com/api/session",
        "useProviderSignature": false,
        "cache": {"enabled": true, "duration": 60}
      },
      {
        "type": "authlib-injector",
        "enabled": true,
        "name": "my-authlib",
        "baseUrl": "https://authlib.example.com",
        "useProviderSignature": false,
        "cache": {"enabled": true, "duration": 60}
      },
      {
        "type": "username-url",
        "enabled": true,
        "name": "my-skin-server",
        "urlTemplate": "https://skins.example.com/skin/{username}.png",
        "useProviderSignature": false,
        "cache": {"enabled": true, "duration": 300}
      }
    ]
  }
}