# SkinsRestorer: one Java plugin, seven server platforms

> SkinsRestorer is a GPL-3.0 Java plugin that manages player skins across Bukkit-family servers, BungeeCord and Velocity proxies, and a mod target, built as a multi-module Gradle project with a published API. It is actively pushed, but the setup documentation is thin and delegates most installation detail to an external site.

**SkinsRestorer/SkinsRestorer** — 🎨 The most popular skin plugin for Minecraft

- Repository: https://github.com/SkinsRestorer/SkinsRestorer
- Website: https://skinsrestorer.net
- Stars: 717 · Forks: 210
- Language: Java
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/skinsrestorer-skinsrestorer

## A single Java codebase aimed at seven Minecraft server runtimes

SkinsRestorer exists to solve one problem: player skins should keep working on a server, whether that server is a vanilla-flavoured Bukkit build, a proxy sitting in front of several backends, or a modded environment. The compatibility badges in the project README name bukkit, spigot, paper, purpur, velocity, bungeecord and waterfall. That list is the practical shape of the project. Rather than one plugin with scattered platform checks, the source tree is split by runtime, with separate top-level directories for bukkit, bungee, velocity, mod, multiver, universal, shared and api.

The primary language is Java and the licence is GPL-3.0, which matters for anyone planning to fork or redistribute a build. The default branch is dev, not main or master, so cloning the project and expecting a released artefact is a mistake. The homepage is skinsrestorer.net, and the repository is not archived. The last push was on 2026-10-18, so this is a codebase that is still being moved rather than one left resting.

The topic list adds sponge-plugin alongside the usual spigot and bungeecord tags, and the presence of a mod directory plus a multiver directory suggests the team is not treating Minecraft's modded ecosystem as out of scope. The universal and shared modules are the obvious places to put logic that is supposed to behave identically no matter which server implementation is hosting it.

## Gradle modules decide which build artefact you actually receive

The build system is Gradle with Kotlin DSL, which is visible in the top-level entries build.gradle.kts and settings.gradle.kts. A buildSrc directory and a gradle wrapper checked into the repository mean contributors are expected to build with ./gradlew rather than a system Gradle install, and the wrapper keeps every contributor on the same Gradle version. The gradle.properties file, the lombok.config file and the mappings directory suggest the compilation setup is tuned for a specific Minecraft server API mapping set, which is a normal but real constraint: the code is tied to particular server internals and cannot be recompiled against arbitrary forks without mapping work.

Other top-level files tell you how the project is operated rather than what it does. changelog.sh is a script for generating changelog entries. crowdin.yml plus a Crowdin badge and a translate.skinsrestorer.net link show that player-facing strings are translated through Crowdin rather than edited directly in the source. renovate.json indicates dependency updates are automated. jitpack.yml is present, which is what makes the api/ module consumable by other Java projects from a Git repository instead of a published artefact repository. A SECURITY.md and a CODE_OF_CONDUCT.md sit alongside the contribution guide, and the README points contributors to CONTRIBUTING.md for development and review and to SUPPORT.md for issue routing.

The scissors directory and the api directory together point to a two audience design: server operators get a plugin, and developers get a supported entry point rather than reverse engineering internals.

## Distribution happens on Modrinth, Hangar and SpigotMC, not through a build command

There is no install command to copy here, and inventing one would be misleading. The project documentation sends installers to its own website, at skinsrestorer.net/docs/installation, with the instruction to follow all steps before reporting issues. The build link in the repository points at a Jenkins job on ci.codemc.io, so continuous integration exists, but the published plugin downloads come from the public distribution platforms listed in the project links: Modrinth at modrinth.com/plugin/skinsrestorer, Hangar at hangar.papermc.io/SRTeam/SkinsRestorer, and SpigotMC at the resource page www.spigotmc.org/resources/2124.

For a first real use, the sequence is short. Pick the platform that matches your server from those three sources, drop the jar into the plugins directory of the target, and check the server console for the plugin loading. Because the plugin targets proxies as well as backends, there is a decision to make before installing anything: if you run a proxy in front of your servers, the velocity or bungee variant is the one that sees players first, and the backend variant still runs for the Minecraft server itself.

Two resources matter after that. The documentation site at skinsrestorer.net/docs covers configuration and usage, and the Discord server at skinsrestorer.net/discord is where the community and support questions are handled. The README asks that installation steps be followed in full before an issue is filed, which is a reasonable request but also an admission that the setup has more than one step, probably one step per platform family.

## Local development wires MariaDB or Postgres through docker-compose

The one file in the repository that can be quoted verbatim is docker-compose.yml, and it defines two database services for development. Both use the latest image tag, both create a database named skinsrestorer, and both set the same development credentials, with MariaDB exposing port 3306 and Postgres exposing port 5432. The compose file is a development convenience, not a documented production deployment guide, and the credential values in it are plainly throwaway.

Here is the service block exactly as the repository defines it:

```yaml
services:
  mariadb:
    image: mariadb:latest
    environment:
      MYSQL_ROOT_PASSWORD: dev_root_password
      MYSQL_DATABASE: skinsrestorer
      MYSQL_USER: dev_user
      MYSQL_PASSWORD: dev_password
    ports:
      - "3306:3306"
    volumes:
      - mariadb_data:/var/lib/mysql
  postgres:
    image: postgres:latest
    environment:
      POSTGRES_DB: skinsrestorer
      POSTGRES_USER: dev_user
      POSTGRES_PASSWORD: dev_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
```

Two things follow from reading this. First, the plugin has a storage layer with a SQL backend, which raises the operational question of where skin data lives on a production network. Second, the presence of both a MariaDB and a Postgres service suggests the data layer is expected to work against more than one engine, but the compose file alone does not tell you which one the released build prefers or how the connection is configured. You would have to confirm that in the configuration documentation on the website before choosing.

## The api/ module and published Javadocs are the developer-facing surface

SkinsRestorer is not only a plugin you install and forget. The README documents a SkinsRestorer API, with usage instructions hosted on the website under skinsrestorer.net/docs/development/api, and it publishes Javadocs at jd.skinsrestorer.net. The api/ directory at the top of the tree is the module that backs this, and the presence of jitpack.yml means other projects can depend on it straight from the repository rather than waiting for a Maven Central release.

The practical value of that arrangement is concrete: a network running several plugins that need to change or read a player skin has a documented entry point instead of a fragile internal call. The cost is a version negotiation problem. The public API is only as stable as the plugin release it ships with, so any plugin that depends on it inherits the upgrade schedule described below.

A second detail in the tree is worth noting for anyone planning an extension. The shared/ and universal/ modules sit above the platform modules, which is where code that must behave the same on Spigot, Paper and the proxies would live. The multiver/ directory hints at multi-version server support, and the mappings/ directory is where version specific mappings are kept. Together they describe a project that expects to track Minecraft server releases, which is the main source of recurring upgrade work for operators.

## Three tagged releases between June and September 2026

The recorded release history is short and recent. Version 15.12.6 was published on 2026-09-20, version 15.12.5 on 2026-07-21, and version 15.12.4 on 2026-06-28. The numbers follow a year.month.patch pattern, so 15.12.x is a minor line rather than a major-version bump, which tells you that breaking changes are not expected inside that line, though the documentation does not spell out a compatibility matrix for each one.

The gap between 15.12.6 and the last push on 2026-10-18 is roughly a month. That gap means the code on the dev branch is ahead of the latest published build, so an operator who compiles from source and an operator who downloads 15.12.6 from Modrinth are running different code. For most network operators that is not a problem, since the platform distributions are the supported path, but it does mean that bug reports and code references can point at different states of the project.

Two channels exist for release information. The website hosts the documentation, and the Jenkins job at ci.codemc.io is the build pipeline that produces artifacts. The changelog.sh script in the repository root suggests release notes are generated automatically during that pipeline, so per-change detail is likely to be shorter than the version list.

## Where the documentation runs out: setup, configuration and rollback

This is the honest limitation of the project as a public artefact. The project README is a landing page. It links to the website for installation, to the website again for API usage, and it lists badges and community links. It does not contain a configuration file example, a list of config keys, a description of what the plugin stores about players, a command reference, a permission list, or any statement about what happens to stored data when a player is removed or when the server is migrated to a new database.

Rollback is not addressed at all. There is no documented answer to what a server operator should do if version 15.12.6 misbehaves on a specific platform, and the release list alone cannot tell you whether the previous build is safe to restore over the current data directory. The same gap applies to upgrade cost. Because the plugin runs on the server process itself, an upgrade means replacing a jar and restarting, and the SQL schema implications of a version change are exactly the kind of thing an operator would want stated before shipping it to a live network.

None of this makes the project unsafe. It makes it dependent on an external documentation site that this repository does not mirror, and that is a real cost when you are deciding whether to adopt something for a network you care about.

## Proxy level or backend level: two deployment routes with different behaviour

The most useful comparison here is not against another plugin but between the two places SkinsRestorer can sit in a Minecraft network. A backend install places the plugin inside the Spigot, Paper or Purpur server that holds player sessions, and it is the simplest arrangement for a single server network. A proxy install places it on Velocity, BungeeCord or Waterfall, in front of those backends, and it becomes the single place where a skin is handled for every player the network routes, including players on different backend servers.

The difference in approach is the difference in blast radius. On a proxy, one plugin instance governs skin behaviour for the whole network, which is easier to reason about when a player moves between servers and avoids a per-backend configuration that could drift. It also means a proxy level mistake is a network wide mistake. On a backend, the fault is contained to one server, and a mixed deployment, where both the proxy and the backends run the plugin, is the configuration most likely to surprise an operator who has not read the setup documentation closely.

The repository structure supports both readings. Separate bungee/ and velocity/ modules exist next to bukkit/, and the compatibility badges list the corresponding forks. The waterfall badge matters for anyone on a BungeeCord fork, since the plugin claims support there but the fork will have its own patch level.

## Conclusion

SkinsRestorer fits server operators who want skin handling handled by the same process that runs their network, and it is a poor fit for anyone who needs offline, self-contained setup instructions because installation lives on an external documentation site. Before adopting it, verify the exact target you run (Paper, Spigot, Purpur, Velocity, BungeeCord or Waterfall), check that the api/ module exposes what your own plugins need, and confirm your database decision against the mariadb and postgres services defined in docker-compose.yml. The last push was on 2026-10-18 and release 15.12.6 shipped on 2026-09-20, so the tree you pull today is a moving target.

## FAQ

### Which Minecraft server platforms does SkinsRestorer support?

The compatibility badges in the project README list bukkit, spigot, paper, purpur, velocity, bungeecord and waterfall, and the repository contains separate modules for bukkit, bungee and velocity targets. The project topic list also includes sponge-plugin and a mod directory exists in the source tree.

### Where do I download the SkinsRestorer plugin jar?

The project points to three distribution platforms: Modrinth at modrinth.com/plugin/skinsrestorer, Hangar at hangar.papermc.io/SRTeam/SkinsRestorer, and SpigotMC at www.spigotmc.org/resources/2124. Installation steps themselves are hosted on skinsrestorer.net/docs/installation rather than in the repository, and the README asks that all steps be followed before reporting issues.

### Is SkinsRestorer still actively developed?

The repository is not archived and the last push was on 2026-10-18. Three releases came out in 2026: 15.12.4 on 2026-06-28, 15.12.5 on 2026-07-21 and 15.12.6 on 2026-09-20.

### Does SkinsRestorer expose an API for other plugins?

Yes. There is an api/ module in the source tree, usage instructions at skinsrestorer.net/docs/development/api and published Javadocs at jd.skinsrestorer.net. The repository also includes jitpack.yml, which allows other Java projects to depend on the module directly from the repository.

## Sources

- [License: GPL-3.0](https://github.com/SkinsRestorer/SkinsRestorer/blob/dev/LICENSE)
- [Project website](https://skinsrestorer.net)
- [README](https://github.com/SkinsRestorer/SkinsRestorer/blob/dev/README.md)
- [Releases](https://github.com/SkinsRestorer/SkinsRestorer/releases)
- [SkinsRestorer/SkinsRestorer on GitHub](https://github.com/SkinsRestorer/SkinsRestorer)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/skinsrestorer-skinsrestorer