** SkinsMC Plugin
Complete Plugin Documentation
---
Overview
**SkinsMC** is a comprehensive skin management plugin designed specifically for **offline-mode (cracked) Minecraft servers**. It allows players to customize their appearance by setting skins from Mojang usernames, image URLs, or a pre-loaded catalog of 50+ popular skins.
Unlike premium servers where skins are automatically loaded from Mojang, offline-mode servers display all players as Steve or Alex. SkinsMC solves this problem by fetching, storing, and applying skins locally, ensuring players retain their chosen appearance across sessions.
---
✨ Key Features
Offline Mode Support
| Feature | Description |
|---------|-------------|
| **Local Storage** | Skins stored in SQLite database, mapped to offline UUIDs |
| **Persistence** | Skins survive server restarts and player reconnects |
| **Auto-Restore** | Skins automatically applied when players join |
| **Original Skin Backup** | First-join skin saved for easy restoration |
Multiple Skin Sources
| Source | Command | Description |
|--------|---------|-------------|
| **Mojang Username** | `/skin set <name>` | Copy any premium player's skin |
| **Image URL** | `/skin url <link>` | Use custom skin from image hosting |
| **Catalog** | GUI Selection | Choose from 50+ pre-loaded popular skins |
Skin Catalog
| Feature | Description |
|---------|-------------|
| **50+ Popular Skins** | YouTubers, streamers, Mojang staff, Hermitcraft members |
| **Categorized** | Dream SMP, Hermitcraft, Mojang, YouTubers |
| **Paginated GUI** | Easy browsing with navigation buttons |
| **One-Click Apply** | Instantly apply any catalog skin |
| **Auto-Cached** | Fetched on first startup, stored locally |
️ User-Friendly GUI
| Menu | Description |
|------|-------------|
| **Profile Menu** | View current skin, reset options, access catalog |
| **Catalog Menu** | Browse all available skins with pagination |
| **Visual Feedback** | Sound effects, color-coded buttons, informative lore |
⚡ Performance Optimized
| Feature | Description |
|---------|-------------|
| **Async API Calls** | All web requests run off main thread |
| **Database Caching** | Minimal API calls after initial fetch |
| **Efficient Refresh** | Smart hide/show for texture updates |
| **Rate Limiting** | Prevents Mojang API abuse |
---
Commands
Player Commands
| Command | Permission | Description |
|---------|------------|-------------|
| `/skin set <username>` | `skinsmc.use` | Set your skin to match a Mojang account |
| `/skin url <url>` | `skinsmc.use` | Set skin from a direct image URL (.png) |
| `/skin update` | `skinsmc.use` | Force refresh your skin for all players |
| `/skin reset` | `skinsmc.use` | Restore your original skin from first join |
| `/skin help` | `skinsmc.use` | Display help information |
| `/skins` | `skinsmc.use` | Open the skin management GUI |
Command Aliases
- `/skin` → `/sk`, `/setskin`
- `/skins` → `/skinmenu`, `/skingui`, `/skinsmenu`
---
Permissions
Player Permissions
| Permission | Default | Description |
|------------|---------|-------------|
| `skinsmc.use` | `true` | Access to all basic skin commands |
| `skinsmc.catalog` | `true` | Access to browse skin catalog |
Admin Permissions
| Permission | Default | Description |
|------------|---------|-------------|
| `skinsmc.admin` | `op` | Administrative commands and notifications |
| `skinsmc.bypass.cooldown` | `op` | Bypass skin change cooldown |
| `skinsmc.*` | `op` | All SkinsMC permissions |
---
️ GUI Menus
Profile Menu (`/skins`)
```
┌─────────────────────────────────┐
│ [≡] [Reset] [HEAD] [Catalog] [≡] │ Row 1
│ [≡] [≡] [Refresh] [≡] [≡] │ Row 2
│ [≡] [≡] [Info] [≡] [Close] │ Row 3
└─────────────────────────────────┘
[HEAD] = Your current skin (player head)
[Reset] = Reset to original skin (Totem of Undying)
[Catalog] = Open skin catalog (Bookshelf)
[Refresh] = Force skin refresh (Ender Eye)
[Info] = Command information (Sign)
[Close] = Close menu (Barrier)
[≡] = Decorative glass pane
```
Catalog Menu (Paginated)
```
┌─────────────────────────────────────────────┐
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 1
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 2
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 3
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 4
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 5
│ [Back] [≡] [≡] [◀] [Page] [▶] [≡] [≡] [Close] │ Row 6
└─────────────────────────────────────────────┘
[Skin] = Clickable player head with skin
[Back] = Return to profile menu
[◀] = Previous page
[Page] = Current page info
[▶] = Next page
[Close] = Close menu
```
---
Included Skins (50+)
Categories & Skins
| Category | Skins Included |
|----------|----------------|
| **Dream SMP** | Dream, Technoblade, TommyInnit, Tubbo, Ranboo, GeorgeNotFound, Sapnap, BadBoyHalo, Skeppy, Ph1LzA, Wilbur, Quackity, KarlJacobs, awesamdude, Purpled, Punz, Foolish_Gamers |
| **Hermitcraft** | Grian, MumboJumbo, Xisuma, Docm77, EthosLab, VintageBeef, BdoubleO100, Keralis, iskall85, Renthedog, GoodTimesWithScar, Tango, ImpulseSV, ZombieCleo, FalseSymmetry, Stressmonster, JoeHills, PearlescentMoon |
| **Mojang Staff** | Notch, jeb_, Dinnerbone, Grumm, _jeb, marc_irl, Searge |
| **YouTubers** | CaptainSparklez, DanTDM, PopularMMOs, SSundee, JeromeASF, BajanCanadian, SkyDoesMinecraft, Logdotzip, PrestonPlayz, UnspeakableGaming, AntVenom, Hypixel, ConnorEatsPants, Ludwig |
---
⚙️ Configuration
config.yml Structure
```yaml
General Settings
settings:
debug-mode: false Enable verbose logging
auto-fetch-on-join: true Fetch Mojang skin for new players
restore-skin-on-join: true Apply saved skin on login
skin-cooldown-seconds: 30 Cooldown between skin changes
api-timeout-seconds: 10 API request timeout
api-max-retries: 3 Retry failed requests
GUI Settings
gui:
catalog-items-per-page: 45 Skins per catalog page
sounds-enabled: true Play GUI sounds
open-sound: "BLOCK_CHEST_OPEN"
click-sound: "UI_BUTTON_CLICK"
success-sound: "ENTITY_PLAYER_LEVELUP"
error-sound: "ENTITY_VILLAGER_NO"
Catalog Settings
catalog:
enabled: true Enable skin catalog
load-on-startup: true Load catalog on server start
refresh-interval-hours: 24 Auto-refresh interval (0 = disabled)
URL Skin Settings
url-skins:
enabled: true Allow URL-based skins
allowed-domains: [] Whitelist domains (empty = all)
blocked-domains: Blacklist domains
- "example.com"
Messages (customizable)
messages:
prefix: "&8[&bSkinsMC&8] &7"
skin-changed: "&aSkin changed successfully!"
skin-reset: "&aSkin reset to original!"
... more messages
```
---
How It Works
Skin Application Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ SKIN APPLICATION PROCESS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. PLAYER REQUESTS SKIN │
│ └─► /skin set Dream │
│ │
│ 2. ASYNC FETCH FROM MOJANG API │
│ └─► api.mojang.com/users/profiles/minecraft/Dream │
│ └─► sessionserver.mojang.com/session/minecraft/profile/{uuid}│
│ │
│ 3. EXTRACT TEXTURE DATA │
│ └─► Base64 encoded texture value │
│ └─► Mojang signature (for authenticity) │
│ │
│ 4. SAVE TO DATABASE │
│ └─► SQLite: player_skins table │
│ └─► Mapped to player's offline UUID │
│ │
│ 5. APPLY TO PLAYER PROFILE │
│ └─► Paper API: PlayerProfile.setProperty() │
│ │
│ 6. VISUAL REFRESH (The "Blink") │
│ └─► Hide player from all observers │
│ └─► Wait 2 ticks │
│ └─► Show player to all observers │
│ └─► Client reloads new texture │
│ │
└─────────────────────────────────────────────────────────────────┘
```
On Player Join
```
┌─────────────────────────────────────────────────────────────────┐
│ PLAYER JOIN PROCESS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AsyncPlayerPreLoginEvent │
│ ├─► Check database for existing skin │
│ ├─► If found: Cache skin data for quick apply │
│ └─► If not found + auto-fetch enabled: │
│ └─► Try fetch from Mojang using username │
│ └─► Save as "original" skin if found │
│ │
│ PlayerJoinEvent (5 tick delay) │
│ ├─► Retrieve cached/stored skin data │
│ ├─► Apply skin to player profile │
│ └─► Trigger visual refresh for nearby players │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
Database Schema
SQLite Tables
```sql
-- Player skin storage
CREATE TABLE player_skins (
uuid TEXT PRIMARY KEY, -- Player's offline UUID
player_name TEXT NOT NULL, -- Last known username
texture_value TEXT, -- Current skin texture (Base64)
texture_signature TEXT, -- Mojang signature
original_texture_value TEXT, -- First-join skin (for reset)
original_texture_signature TEXT, -- Original signature
last_updated TIMESTAMP -- Last modification time
);
-- Catalog skins cache
CREATE TABLE catalog_skins (
id INTEGER PRIMARY KEY, -- Auto-increment ID
skin_name TEXT UNIQUE, -- Lowercase identifier
display_name TEXT, -- Display name in GUI
texture_value TEXT, -- Skin texture (Base64)
texture_signature TEXT, -- Mojang signature
category TEXT, -- Category for organization
added_date TIMESTAMP -- When skin was cached
);
```
---
Requirements
Server Requirements
| Requirement | Version |
|-------------|---------|
| **Minecraft** | 1.21.1 - 1.21.4 |
| **Server Software** | Paper (recommended) or Spigot |
| **Java** | 21 or higher |
| **Server Mode** | Offline Mode (online-mode=false) |
Dependencies
| Dependency | Type | Purpose |
|------------|------|---------|
| **Paper API** | Required | Core functionality, PlayerProfile API |
| **SQLite JDBC** | Bundled | Database storage (included in JAR) |
| **Gson** | Provided | JSON parsing (included in server) |
Optional Dependencies
| Dependency | Purpose |
|------------|---------|
| **ProtocolLib** | Enhanced packet manipulation (future) |
| **PlaceholderAPI** | Placeholder support (future) |
---
Installation
Step-by-Step Guide
```
1. DOWNLOAD
└─► Download SkinsMC-1.0.0.jar
2. INSTALL
└─► Place JAR in server's /plugins folder
3. CONFIGURE SERVER
└─► Ensure server.properties has: online-mode=false
4. START SERVER
└─► Plugin will generate config files
└─► Catalog skins will begin loading (takes 1-3 minutes first time)
5. VERIFY
└─► Check console for "SkinsMC enabled successfully!"
└─► Check for "Skin catalog loading complete!"
6. CONFIGURE (Optional)
└─► Edit plugins/SkinsMC/config.yml
└─► Reload server or use plugin reload
```
File Structure After Installation
```
plugins/
└── SkinsMC/
├── config.yml Plugin configuration
└── skins.db SQLite database
```
---
Usage Examples
For Players
```
Set skin to a famous YouTuber
/skin set Dream
Set skin from custom image
/skin url https://i.imgur.com/abc123.png
Open skin menu
/skins
Refresh skin if others see Steve/Alex
/skin update
Go back to original skin
/skin reset
```
For Admins
```
Monitor loading in console
[SkinsMC] Loading catalog skins...
[SkinsMC] Progress: 10/56 skins processed
[SkinsMC] Progress: 20/56 skins processed
...
[SkinsMC] Skin catalog loading complete!
[SkinsMC] Successful: 52
[SkinsMC] Failed: 4
[SkinsMC] Total loaded: 52
```
---
❓ FAQ
General Questions
**Q: Does this work on premium servers?**
> No, this plugin is designed specifically for offline-mode servers. Premium servers automatically load skins from Mojang.
**Q: Will Mojang ban me for using this?**
> No, fetching public skin data is allowed. The plugin uses official Mojang APIs.
**Q: Can players steal paid/exclusive skins?**
> Players can only copy skins from existing Mojang accounts. If a skin is on a Mojang account, it can be copied.
Technical Questions
**Q: Why do I see Steve/Alex briefly when joining?**
> The skin is applied after the player fully connects. A small delay is normal.
**Q: Can I add custom skins to the catalog?**
> Currently, the catalog is built from Mojang usernames. Custom additions would require code modification.
**Q: How often does the catalog refresh?**
> By default, every 24 hours. Configure with `catalog.refresh-interval-hours`.
**Q: Does this use a lot of server resources?**
> No, all API calls are asynchronous. The SQLite database is lightweight.
Troubleshooting
**Q: Skin not showing to other players?**
> Try `/skin update` to force a visual refresh.
**Q: "Could not find skin for that player"**
> The username doesn't exist on Mojang servers, or the API is temporarily unavailable.
**Q: Catalog shows "Loading..."**
> Wait for initial fetch to complete. Check console for progress.
**Q: Plugin not loading on Spigot?**
> Some features require Paper API. Consider switching to Paper for full compatibility.
---
Performance
Resource Usage
| Metric | Value |
|--------|-------|
| **Memory** | ~5-10 MB (depends on catalog size) |
| **Disk** | ~2-5 MB (database + config) |
| **CPU** | Minimal (async operations) |
| **Network** | Initial: ~50 API calls; Runtime: As needed |
API Rate Limits
| API | Limit | Plugin Behavior |
|-----|-------|-----------------|
| **Mojang UUID API** | ~600/10min | 100ms delay between requests |
| **Mojang Session API** | ~200/min | Cached results reduce calls |
| **Mineskin API** | ~10/min (free) | Used only for URL skins |
---
Version History
| Version | Date | Changes |
|---------|------|---------|
| **1.0.0** | 2024 | Initial release |
Planned Features
- [ ] Admin commands (`/skin reload`, `/skin clear <player>`)
- [ ] PlaceholderAPI support
- [ ] Custom catalog skins from config
- [ ] Skin history/favorites system
- [ ] Skin preview before applying
- [ ] Bedrock player support (via Floodgate)
---
Support
Getting Help
1. Check the FAQ section above
2. Review console logs for errors
3. Ensure you're using Paper server
4. Verify Java 21+ is installed
Credits
- **Mojang** - For the public API
- **Mineskin** - For URL-to-skin conversion API
- **Paper Team** - For the enhanced server API
- **Content Creators** - Whose skins are featured in the catalog
---
```
███████╗██╗ ██╗██╗███╗ ██╗███████╗███╗ ███╗ ██████╗
██╔════╝██║ ██╔╝██║████╗ ██║██╔════╝████╗ ████║██╔════╝
███████╗█████╔╝ ██║██╔██╗ ██║███████╗██╔████╔██║██║
╚════██║██╔═██╗ ██║██║╚██╗██║╚════██║██║╚██╔╝██║██║
███████║██║ ██╗██║██║ ╚████║███████║██║ ╚═╝ ██║╚██████╗
╚══════╝╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═╝ ╚═════╝
Skin Management for Offline-Mode Servers
```**
Complete Plugin Documentation
---
Overview
**SkinsMC** is a comprehensive skin management plugin designed specifically for **offline-mode (cracked) Minecraft servers**. It allows players to customize their appearance by setting skins from Mojang usernames, image URLs, or a pre-loaded catalog of 50+ popular skins.
Unlike premium servers where skins are automatically loaded from Mojang, offline-mode servers display all players as Steve or Alex. SkinsMC solves this problem by fetching, storing, and applying skins locally, ensuring players retain their chosen appearance across sessions.
---
✨ Key Features
Offline Mode Support
| Feature | Description |
|---------|-------------|
| **Local Storage** | Skins stored in SQLite database, mapped to offline UUIDs |
| **Persistence** | Skins survive server restarts and player reconnects |
| **Auto-Restore** | Skins automatically applied when players join |
| **Original Skin Backup** | First-join skin saved for easy restoration |
Multiple Skin Sources
| Source | Command | Description |
|--------|---------|-------------|
| **Mojang Username** | `/skin set <name>` | Copy any premium player's skin |
| **Image URL** | `/skin url <link>` | Use custom skin from image hosting |
| **Catalog** | GUI Selection | Choose from 50+ pre-loaded popular skins |
Skin Catalog
| Feature | Description |
|---------|-------------|
| **50+ Popular Skins** | YouTubers, streamers, Mojang staff, Hermitcraft members |
| **Categorized** | Dream SMP, Hermitcraft, Mojang, YouTubers |
| **Paginated GUI** | Easy browsing with navigation buttons |
| **One-Click Apply** | Instantly apply any catalog skin |
| **Auto-Cached** | Fetched on first startup, stored locally |
️ User-Friendly GUI
| Menu | Description |
|------|-------------|
| **Profile Menu** | View current skin, reset options, access catalog |
| **Catalog Menu** | Browse all available skins with pagination |
| **Visual Feedback** | Sound effects, color-coded buttons, informative lore |
⚡ Performance Optimized
| Feature | Description |
|---------|-------------|
| **Async API Calls** | All web requests run off main thread |
| **Database Caching** | Minimal API calls after initial fetch |
| **Efficient Refresh** | Smart hide/show for texture updates |
| **Rate Limiting** | Prevents Mojang API abuse |
---
Commands
Player Commands
| Command | Permission | Description |
|---------|------------|-------------|
| `/skin set <username>` | `skinsmc.use` | Set your skin to match a Mojang account |
| `/skin url <url>` | `skinsmc.use` | Set skin from a direct image URL (.png) |
| `/skin update` | `skinsmc.use` | Force refresh your skin for all players |
| `/skin reset` | `skinsmc.use` | Restore your original skin from first join |
| `/skin help` | `skinsmc.use` | Display help information |
| `/skins` | `skinsmc.use` | Open the skin management GUI |
Command Aliases
- `/skin` → `/sk`, `/setskin`
- `/skins` → `/skinmenu`, `/skingui`, `/skinsmenu`
---
Permissions
Player Permissions
| Permission | Default | Description |
|------------|---------|-------------|
| `skinsmc.use` | `true` | Access to all basic skin commands |
| `skinsmc.catalog` | `true` | Access to browse skin catalog |
Admin Permissions
| Permission | Default | Description |
|------------|---------|-------------|
| `skinsmc.admin` | `op` | Administrative commands and notifications |
| `skinsmc.bypass.cooldown` | `op` | Bypass skin change cooldown |
| `skinsmc.*` | `op` | All SkinsMC permissions |
---
️ GUI Menus
Profile Menu (`/skins`)
```
┌─────────────────────────────────┐
│ [≡] [Reset] [HEAD] [Catalog] [≡] │ Row 1
│ [≡] [≡] [Refresh] [≡] [≡] │ Row 2
│ [≡] [≡] [Info] [≡] [Close] │ Row 3
└─────────────────────────────────┘
[HEAD] = Your current skin (player head)
[Reset] = Reset to original skin (Totem of Undying)
[Catalog] = Open skin catalog (Bookshelf)
[Refresh] = Force skin refresh (Ender Eye)
[Info] = Command information (Sign)
[Close] = Close menu (Barrier)
[≡] = Decorative glass pane
```
Catalog Menu (Paginated)
```
┌─────────────────────────────────────────────┐
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 1
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 2
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 3
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 4
│ [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] [Skin] │ Row 5
│ [Back] [≡] [≡] [◀] [Page] [▶] [≡] [≡] [Close] │ Row 6
└─────────────────────────────────────────────┘
[Skin] = Clickable player head with skin
[Back] = Return to profile menu
[◀] = Previous page
[Page] = Current page info
[▶] = Next page
[Close] = Close menu
```
---
Included Skins (50+)
Categories & Skins
| Category | Skins Included |
|----------|----------------|
| **Dream SMP** | Dream, Technoblade, TommyInnit, Tubbo, Ranboo, GeorgeNotFound, Sapnap, BadBoyHalo, Skeppy, Ph1LzA, Wilbur, Quackity, KarlJacobs, awesamdude, Purpled, Punz, Foolish_Gamers |
| **Hermitcraft** | Grian, MumboJumbo, Xisuma, Docm77, EthosLab, VintageBeef, BdoubleO100, Keralis, iskall85, Renthedog, GoodTimesWithScar, Tango, ImpulseSV, ZombieCleo, FalseSymmetry, Stressmonster, JoeHills, PearlescentMoon |
| **Mojang Staff** | Notch, jeb_, Dinnerbone, Grumm, _jeb, marc_irl, Searge |
| **YouTubers** | CaptainSparklez, DanTDM, PopularMMOs, SSundee, JeromeASF, BajanCanadian, SkyDoesMinecraft, Logdotzip, PrestonPlayz, UnspeakableGaming, AntVenom, Hypixel, ConnorEatsPants, Ludwig |
---
⚙️ Configuration
config.yml Structure
```yaml
General Settings
settings:
debug-mode: false Enable verbose logging
auto-fetch-on-join: true Fetch Mojang skin for new players
restore-skin-on-join: true Apply saved skin on login
skin-cooldown-seconds: 30 Cooldown between skin changes
api-timeout-seconds: 10 API request timeout
api-max-retries: 3 Retry failed requests
GUI Settings
gui:
catalog-items-per-page: 45 Skins per catalog page
sounds-enabled: true Play GUI sounds
open-sound: "BLOCK_CHEST_OPEN"
click-sound: "UI_BUTTON_CLICK"
success-sound: "ENTITY_PLAYER_LEVELUP"
error-sound: "ENTITY_VILLAGER_NO"
Catalog Settings
catalog:
enabled: true Enable skin catalog
load-on-startup: true Load catalog on server start
refresh-interval-hours: 24 Auto-refresh interval (0 = disabled)
URL Skin Settings
url-skins:
enabled: true Allow URL-based skins
allowed-domains: [] Whitelist domains (empty = all)
blocked-domains: Blacklist domains
- "example.com"
Messages (customizable)
messages:
prefix: "&8[&bSkinsMC&8] &7"
skin-changed: "&aSkin changed successfully!"
skin-reset: "&aSkin reset to original!"
... more messages
```
---
How It Works
Skin Application Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ SKIN APPLICATION PROCESS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. PLAYER REQUESTS SKIN │
│ └─► /skin set Dream │
│ │
│ 2. ASYNC FETCH FROM MOJANG API │
│ └─► api.mojang.com/users/profiles/minecraft/Dream │
│ └─► sessionserver.mojang.com/session/minecraft/profile/{uuid}│
│ │
│ 3. EXTRACT TEXTURE DATA │
│ └─► Base64 encoded texture value │
│ └─► Mojang signature (for authenticity) │
│ │
│ 4. SAVE TO DATABASE │
│ └─► SQLite: player_skins table │
│ └─► Mapped to player's offline UUID │
│ │
│ 5. APPLY TO PLAYER PROFILE │
│ └─► Paper API: PlayerProfile.setProperty() │
│ │
│ 6. VISUAL REFRESH (The "Blink") │
│ └─► Hide player from all observers │
│ └─► Wait 2 ticks │
│ └─► Show player to all observers │
│ └─► Client reloads new texture │
│ │
└─────────────────────────────────────────────────────────────────┘
```
On Player Join
```
┌─────────────────────────────────────────────────────────────────┐
│ PLAYER JOIN PROCESS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AsyncPlayerPreLoginEvent │
│ ├─► Check database for existing skin │
│ ├─► If found: Cache skin data for quick apply │
│ └─► If not found + auto-fetch enabled: │
│ └─► Try fetch from Mojang using username │
│ └─► Save as "original" skin if found │
│ │
│ PlayerJoinEvent (5 tick delay) │
│ ├─► Retrieve cached/stored skin data │
│ ├─► Apply skin to player profile │
│ └─► Trigger visual refresh for nearby players │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
Database Schema
SQLite Tables
```sql
-- Player skin storage
CREATE TABLE player_skins (
uuid TEXT PRIMARY KEY, -- Player's offline UUID
player_name TEXT NOT NULL, -- Last known username
texture_value TEXT, -- Current skin texture (Base64)
texture_signature TEXT, -- Mojang signature
original_texture_value TEXT, -- First-join skin (for reset)
original_texture_signature TEXT, -- Original signature
last_updated TIMESTAMP -- Last modification time
);
-- Catalog skins cache
CREATE TABLE catalog_skins (
id INTEGER PRIMARY KEY, -- Auto-increment ID
skin_name TEXT UNIQUE, -- Lowercase identifier
display_name TEXT, -- Display name in GUI
texture_value TEXT, -- Skin texture (Base64)
texture_signature TEXT, -- Mojang signature
category TEXT, -- Category for organization
added_date TIMESTAMP -- When skin was cached
);
```
---
Requirements
Server Requirements
| Requirement | Version |
|-------------|---------|
| **Minecraft** | 1.21.1 - 1.21.4 |
| **Server Software** | Paper (recommended) or Spigot |
| **Java** | 21 or higher |
| **Server Mode** | Offline Mode (online-mode=false) |
Dependencies
| Dependency | Type | Purpose |
|------------|------|---------|
| **Paper API** | Required | Core functionality, PlayerProfile API |
| **SQLite JDBC** | Bundled | Database storage (included in JAR) |
| **Gson** | Provided | JSON parsing (included in server) |
Optional Dependencies
| Dependency | Purpose |
|------------|---------|
| **ProtocolLib** | Enhanced packet manipulation (future) |
| **PlaceholderAPI** | Placeholder support (future) |
---
Installation
Step-by-Step Guide
```
1. DOWNLOAD
└─► Download SkinsMC-1.0.0.jar
2. INSTALL
└─► Place JAR in server's /plugins folder
3. CONFIGURE SERVER
└─► Ensure server.properties has: online-mode=false
4. START SERVER
└─► Plugin will generate config files
└─► Catalog skins will begin loading (takes 1-3 minutes first time)
5. VERIFY
└─► Check console for "SkinsMC enabled successfully!"
└─► Check for "Skin catalog loading complete!"
6. CONFIGURE (Optional)
└─► Edit plugins/SkinsMC/config.yml
└─► Reload server or use plugin reload
```
File Structure After Installation
```
plugins/
└── SkinsMC/
├── config.yml Plugin configuration
└── skins.db SQLite database
```
---
Usage Examples
For Players
```
Set skin to a famous YouTuber
/skin set Dream
Set skin from custom image
/skin url https://i.imgur.com/abc123.png
Open skin menu
/skins
Refresh skin if others see Steve/Alex
/skin update
Go back to original skin
/skin reset
```
For Admins
```
Monitor loading in console
[SkinsMC] Loading catalog skins...
[SkinsMC] Progress: 10/56 skins processed
[SkinsMC] Progress: 20/56 skins processed
...
[SkinsMC] Skin catalog loading complete!
[SkinsMC] Successful: 52
[SkinsMC] Failed: 4
[SkinsMC] Total loaded: 52
```
---
❓ FAQ
General Questions
**Q: Does this work on premium servers?**
> No, this plugin is designed specifically for offline-mode servers. Premium servers automatically load skins from Mojang.
**Q: Will Mojang ban me for using this?**
> No, fetching public skin data is allowed. The plugin uses official Mojang APIs.
**Q: Can players steal paid/exclusive skins?**
> Players can only copy skins from existing Mojang accounts. If a skin is on a Mojang account, it can be copied.
Technical Questions
**Q: Why do I see Steve/Alex briefly when joining?**
> The skin is applied after the player fully connects. A small delay is normal.
**Q: Can I add custom skins to the catalog?**
> Currently, the catalog is built from Mojang usernames. Custom additions would require code modification.
**Q: How often does the catalog refresh?**
> By default, every 24 hours. Configure with `catalog.refresh-interval-hours`.
**Q: Does this use a lot of server resources?**
> No, all API calls are asynchronous. The SQLite database is lightweight.
Troubleshooting
**Q: Skin not showing to other players?**
> Try `/skin update` to force a visual refresh.
**Q: "Could not find skin for that player"**
> The username doesn't exist on Mojang servers, or the API is temporarily unavailable.
**Q: Catalog shows "Loading..."**
> Wait for initial fetch to complete. Check console for progress.
**Q: Plugin not loading on Spigot?**
> Some features require Paper API. Consider switching to Paper for full compatibility.
---
Performance
Resource Usage
| Metric | Value |
|--------|-------|
| **Memory** | ~5-10 MB (depends on catalog size) |
| **Disk** | ~2-5 MB (database + config) |
| **CPU** | Minimal (async operations) |
| **Network** | Initial: ~50 API calls; Runtime: As needed |
API Rate Limits
| API | Limit | Plugin Behavior |
|-----|-------|-----------------|
| **Mojang UUID API** | ~600/10min | 100ms delay between requests |
| **Mojang Session API** | ~200/min | Cached results reduce calls |
| **Mineskin API** | ~10/min (free) | Used only for URL skins |
---
Version History
| Version | Date | Changes |
|---------|------|---------|
| **1.0.0** | 2024 | Initial release |
Planned Features
- [ ] Admin commands (`/skin reload`, `/skin clear <player>`)
- [ ] PlaceholderAPI support
- [ ] Custom catalog skins from config
- [ ] Skin history/favorites system
- [ ] Skin preview before applying
- [ ] Bedrock player support (via Floodgate)
---
Support
Getting Help
1. Check the FAQ section above
2. Review console logs for errors
3. Ensure you're using Paper server
4. Verify Java 21+ is installed
Credits
- **Mojang** - For the public API
- **Mineskin** - For URL-to-skin conversion API
- **Paper Team** - For the enhanced server API
- **Content Creators** - Whose skins are featured in the catalog
---
```
███████╗██╗ ██╗██╗███╗ ██╗███████╗███╗ ███╗ ██████╗
██╔════╝██║ ██╔╝██║████╗ ██║██╔════╝████╗ ████║██╔════╝
███████╗█████╔╝ ██║██╔██╗ ██║███████╗██╔████╔██║██║
╚════██║██╔═██╗ ██║██║╚██╗██║╚════██║██║╚██╔╝██║██║
███████║██║ ██╗██║██║ ╚████║███████║██║ ╚═╝ ██║╚██████╗
╚══════╝╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═╝ ╚═════╝
Skin Management for Offline-Mode Servers
```**
Quick facts
- Edition: Minecraft Java
- File type: .jar
- Minecraft version listed: 1.21
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Spigot — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
SkinsMC is a free Minecraft Java mod. Compatible with Minecraft 1.21. Downloaded 135 times (via Spigot). Download it and open it directly in the game.