BetterSkin

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

Permissions

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