Overview#
Custom Skin Loader (CSL) is a powerful client-side utility designed to give players full control over their in-game appearance. By default, Minecraft only loads skins from official Mojang servers. This mod expands that functionality, allowing the game to fetch textures from third-party skin servers (such as LittleSkin, Blessing Skin, or Ely.by) and local files stored on the user's computer.
Key Features
- Multi-Source Loading: Load skins from Mojang, third-party APIs, or local folders simultaneously.
- HD Skin Support: Renders high-definition skins and capes even without OptiFine or MCPatcher.
- Skull Support: Fixes issues with player skulls, allowing them to display custom skins dynamically.
- Transparent Skin Support: Correctly renders skins with transparent layers.
- Profile Caching: Saves loaded skins locally to reduce network usage and allow skins to load in offline mode.
- Spectator Menu Fix: Ensures player avatars in the spectator menu display correctly.
Configuration#
The mod is primarily managed through a JSON configuration file located at .minecraft/CustomSkinLoader/CustomSkinLoader.json. This file defines the behavior of the mod and the priority of skin sources.
Global Settings
| Option | Type | Description |
|---|---|---|
enable |
Boolean | Enables or disables the mod entirely. |
loadLogs |
Boolean | Whether to generate detailed logs in CustomSkinLoader.log. |
loadCape |
Boolean | Enables or disables the loading of capes. |
cacheExpiry |
Integer | Time in seconds before the local skin cache expires. |
ignoreHttpsCertificate |
Boolean | If true, the mod will ignore SSL certificate errors when connecting to skin servers. |
enableTransparentSkin |
Boolean | Enables support for semi-transparent skin textures. |
The Load List
The loadlist is an array of objects that determines where the mod looks for skins and in what order. The mod will check each source from top to bottom and stop once a skin is found.
"loadlist": [
{
"name": "LocalSkin",
"type": "Legacy",
"root": "LocalSkin/"
},
{
"name": "Mojang",
"type": "MojangAPI"
}
]Skin Loaders (APIs)#
Custom Skin Loader supports several API types to communicate with different skin server implementations.
| API Type | Description | Required Parameters |
|---|---|---|
| MojangAPI | Fetches skins from the official Minecraft servers. | name |
| CustomSkinAPI | The standard JSON-based API used by modern third-party skin servers. | name, root (URL) |
| UniSkinAPI | A legacy API format used by older skin systems like SkinMe. | name, root (URL) |
| ElyByAPI | Specifically designed for the Ely.by skin system. | name |
| Legacy | Loads skins directly from a URL pattern or local path. | name, root (URL/Path) |
ExtraList System
Skin server owners can provide an ExtraList JSON file. When users place this file into the .minecraft/CustomSkinLoader/ExtraList folder, the mod automatically adds that server to the loading priority without requiring manual editing of the main config file.
Local Skin System#
One of the most popular features of the mod is the ability to use skins stored locally on your hard drive. This is ideal for testing new skins or playing in offline mode.
Directory Structure
Local textures must be placed in the following subfolders within .minecraft/CustomSkinLoader/LocalSkin/:
- Skins:
LocalSkin/skins/{username}.png - Capes:
LocalSkin/capes/{username}.png - Elytras:
LocalSkin/elytras/{username}.png
Usage Example
If your in-game name is Steve, place your skin file at .minecraft/CustomSkinLoader/LocalSkin/skins/Steve.png. Ensure that LocalSkin is at the top of your loadlist in the configuration file to prioritize it over online sources.
Commands#
The mod provides several in-game commands for management and troubleshooting. Commands can be prefixed with either /csl or /customskinloader.
| Command | Description |
|---|---|
/csl reload |
Reloads the CustomSkinLoader.json config and refreshes all player skins in the current world. |
/csl report |
Generates a diagnostic report file to help identify why a skin is not loading. |
/csl clear |
Clears the local skin cache, forcing the mod to re-download textures from the web. |
/csl help |
Displays a list of available subcommands and their usage. |
Advanced Mechanics#
Profile Caching
To improve performance and reliability, the mod caches player profiles and textures. This prevents the mod from making constant network requests to skin servers. If a server is down, the mod will attempt to use the cached version of the skin.
Dynamic Skull Loading
In vanilla Minecraft, player skulls often fail to load skins correctly in certain versions or environments. Custom Skin Loader intercepts the skull rendering process, applying the same loadlist logic to skulls as it does to player entities. This ensures that decorative heads in builds or player-head items always show the correct skin.
Spectator Menu Fix
In the Spectator Mode menu, player icons often default to the standard Steve or Alex textures. This mod patches the menu to ensure that the actual custom skins are rendered in the player list.
