Installation

This guide walks you through setting up Custom Skin on your Minecraft server.

Requirements

Java 17 or newer
Paper 1.20+ or Spigot 1.20+
A Custom Skin API instance

Download

Download the latest release from GitHub:


# Using curl
curl -L -o plugins/CustomSkin.jar https://github.com/th0rgal/customskin/releases/latest/download/customskin.jar
 
# Or manually download from:
# https://github.com/th0rgal/customskin/releases

Server Setup

Stop your server if it’s running
Place the JAR in your plugins/ folder
Start your server to generate the default config
Configure the plugin (see below)
Restart the server to apply changes

First Configuration

After the first start, edit plugins/CustomSkin/config.yml:


api:
  # URL of your Custom Skin API instance
  url: https://ccapi.thomas.md
  
  # Your server's API key (get this from the API admin)
  plugin_api_key: your-api-key-here
  
  # Unique identifier for your server
  server_id: my-server
  
  # Request timeout in seconds
  timeout_seconds: 30
 
skin:
  # Send dashboard link when players join
  send_link_on_join: true

Verify Installation

After restarting, you should see in the console:


[CustomSkin] SQLite skin storage initialized
[CustomSkin] WebSocket connecting to: wss://ccapi.thomas.md/ws/plugin
[CustomSkin] Custom Skin enabled! API: https://ccapi.thomas.md

Test the plugin:


/skin status

This should show the WebSocket connection status.

Troubleshooting

”Failed to initialize skin storage”

Make sure your server has write permissions to the plugins/CustomSkin/ folder.

WebSocket disconnected

Check that:

Your plugin_api_key is correct
The API URL is reachable from your server
No firewall is blocking WebSocket connections

Skins not applying

Verify that:

The player has customskin.use permission
The API is reachable and returning valid skin data
On Spigot (non-Paper), ensure you’re running Java 17+