BetterSkin

Browser-based skin management for Paper/Purpur 1.21.x offline-mode servers

Version 1.0.0 · Minecraft 1.21.x · Java 21 · Server-side

BetterSkin lets players on offline-mode servers set a custom skin without a premium Minecraft account. The plugin hosts a small web page inside your server: players click a link in chat, open it in their browser, and pick, import or upload a skin. Skins are signed through the free MineSkin service and applied to the player's profile, so everyone on the server sees them.

Features

• Built-in web UI: no extra software to install. The plugin serves an HTML interface and a REST API on a configurable port.
• Multiple skin sources: import by Minecraft username (reuses the existing Mojang signature), import by image URL, or upload a 64x64 / 64x32 PNG.
• 3D preview of the skin in the browser before applying.
• Presets so players can save and re-apply skins.
• Token-based sessions: clicking /skin issues a short-lived link with a high-entropy token; the token, not the URL, identifies the player (no IDOR).
• Apply modes: update the skin instantly or on the next join.
• In-memory skin cache to reduce database reads.
• SQLite storage (betterskin.db), no external database required.
• Configurable join behaviour: send the skin link always, on first join, or never (players use /skin).
• English and Portuguese language files.

Commands

Command	Description	Permission
/skin	Get your browser link to manage your skin	betterskin.use
/skin status	Show your current skin status	betterskin.use
/skin reload	Reload the plugin configuration	betterskin.admin

Permissions

Node	Description	Default
betterskin.use	Use the /skin command	true
betterskin.admin	Admin commands (/skin status, /skin reload)	op

Configuration

# ---- Web Server ----
server:
  port: 4567
  # The public URL players see in chat. Use YOUR IP/domain, and https://
  # if you put the web server behind a TLS reverse proxy.
  public-url: "http://localhost:4567"

# ---- MineSkin API (required for skins to work) ----
# Get a free key at https://account.mineskin.org/keys
mineskin:
  api-key: ""
  api-url: "https://api.mineskin.org"

# ---- Token settings ----
token:
  expiry-seconds: 300       # how long the browser link is valid
  bind-ip: false

# ---- Join behaviour ----
join:
  send-link-mode: "ALWAYS"  # ALWAYS | FIRST_JOIN | NEVER
  link-delay-ticks: 40

# ---- Skin settings ----
skin:
  apply-mode: "INSTANT"     # INSTANT | ON_JOIN
  cache-ttl-seconds: 600

locale: "pt_PT"             # en_US | pt_PT (shipped default is pt_PT — set en_US here
                            # or let players pick per-player via PlayerSettings)

Web server

The plugin runs an HTTP server (default port 4567) that serves the skin management page and API.

• server.port — the TCP port the web page listens on. Pick a free port; your Minecraft server already uses 25565.
• server.public-url — the URL shown in the chat link. Set it to your server's public IP or domain.

Recommended hardening: the web server speaks plain HTTP and session tokens travel in the link. For any public deployment, put it behind a reverse proxy that terminates HTTPS (as in https://skin.example.com), set public-url to the https:// address, and consider restricting the plugin's bind so the raw HTTP port is not reachable directly from the internet. Serving it over HTTP on a public IP exposes tokens to interception.

MineSkin API key

A free MineSkin API key is required for skins to be signed and accepted by Minecraft. Create an account at https://account.mineskin.org/keys, generate a key, and set it under mineskin.api-key.

Installation

1. Requires Paper or Purpur 1.21.x and Java 21.
2. Drop the JAR into plugins/ and start the server once to generate config.yml.
3. Set mineskin.api-key, server.public-url and (for production) put the web server behind an HTTPS reverse proxy.
4. Reload with /skin reload or restart.

Dependencies

No plugin dependencies. Requires an internet connection and a MineSkin API key (free) for skin signing. The SQLite driver and JSON library are bundled.

Support / Source

Source code: https://github.com/henriquescrrrr/carrageis-betterskin