BetterSkin

Browser-based skin management for Paper/Purpur 26.3 offline-mode servers

Version 2.1.0 · Minecraft 26.3 · Java 25 · 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 26.3** and **Java 25** (2.0.0 runs on 26.2, 1.x on 1.21.x).
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>