🎨 Custom Skins

Learn how to create and add your own custom weapon skins to WeaponSkin.

🗂 Overview

WeaponSkin allows you to add custom weapon skins using the built-in resource pack system. This guide will walk you through creating and adding your own skins.

💡 Requirements

Custom skins require the item_model provider (Minecraft 1.21.4+) or Oraxen. This guide focuses on the built-in item_model provider.

📁 Directory Structure

Skin assets are placed in the plugins/WeaponSkin/pack/skins/ directory. Each skin set has its own folder with the following structure:

📁 pack/skins/
📁 <namespace>/
📄 items.yml
📁 models/
📁 item/
📄 <model_name>.json
📁 textures/
📁 item/
🎨 <texture_name>.png

File Descriptions

File Purpose
items.yml Defines the skin items and their properties (namespace, model path, texture path)
models/item/<model_name>.json Minecraft model JSON files for the custom items (can be 3D custom models)
textures/item/<texture_name>.png Texture files for the models (PNG format, typically 16x16 or 32x32)

🔧 Creating a Custom Skin

Create Skin Folder

Create a new folder in pack/skins/ with your <namespace>:

pack/skins/<namespace>/
Create the Texture

Create a PNG texture file (typically 16x16 or 32x32 pixels for Minecraft items) and place it in:

pack/skins/<namespace>/textures/item/<texture_name>.png
💡 Tip

You can use tools like Blockbench to create and export Minecraft item textures and models.

Create the Model JSON

Create a model JSON file in:

pack/skins/<namespace>/models/item/<model_name>.json

Example custom 3D model file:

{
    "credit": "Made by <your_name>",
    "texture_size": [ 32, 32 ],
    "textures": {
        "0": "<namespace>:item/<texture_name>",
        "particle": "<namespace>:item/<texture_name>"
    },
    "elements": [
        {
            "from": [ 7.4, -8.65, 6.4 ],
            "to": [ 8.6, -5.45, 9.6 ],
            "rotation": { "angle": -45, "axis": "x", "origin": [ 8, -7.05, 8 ] },
            "faces": {
                "north": { "uv": [ 1, 9, 1.5, 10.5 ], "texture": "#0" },
                "east": { "uv": [ 5, 0, 6.5, 1.5 ], "texture": "#0" },
                "south": { "uv": [ 1.5, 9, 2, 10.5 ], "texture": "#0" },
                "west": { "uv": [ 5, 1.5, 6.5, 3 ], "texture": "#0" },
                "up": { "uv": [ 2.5, 10.5, 2, 9 ], "texture": "#0" },
                "down": { "uv": [ 3, 9, 2.5, 10.5 ], "texture": "#0" }
            }
        }
        // ... more elements
    ],
    "display": {
        "thirdperson_righthand": { "translation": [ 0, 9, 1.5 ] },
        "thirdperson_lefthand": { "translation": [ 0, 9, 1.5 ] },
        "firstperson_righthand": { "translation": [ 0, 9, 1.5 ] },
        "firstperson_lefthand": { "translation": [ 0, 9, 1.5 ] },
        "ground": { "rotation": [ 90, 90, 0 ] },
        "gui": { "rotation": [ 90, 45, -90 ], "translation": [ 2, 2, 0 ] }
    }
}
💡 Note

The texture reference uses the format <namespace>:item/<texture_name> where <namespace> matches your folder name and items.yml namespace.

Create items.yml

Create the items.yml file in your skin folder:

# plugins/WeaponSkin/pack/skins/<namespace>/items.yml
namespace: <namespace>

items:
  <item_id>:
    # Case 1: Model provided
    # The system will copy the model and automatically scan its textures.
    model: item/<model_name>

  <item_id_2>:
    # Case 2: Model NOT provided
    # The system will automatically generate a JSON model (1 layer0).
    parent_model: item/handheld  # (Optional) Defaults to item/handheld
    texture: item/<texture_name>

Field Descriptions

Field Required Description
namespace Yes Unique namespace for your skin set (must match folder name)
base No Base material for Oraxen or legacy support (not needed for item_model provider)
model No Path to model JSON (without .json extension). If omitted, the plugin auto-generates a model.
parent_model No Parent model for auto-generation. Default: item/handheld. Only used if 'model' is omitted.
texture Depends Path to texture PNG (without .png extension). REQUIRED if 'model' is omitted to auto-generate the single layer.
Register in skins.yml

Add your skin to plugins/WeaponSkin/skins.yml:

<skin_id>:
  model_id: <item_id>
  allowed_materials:
    - DIAMOND_SWORD
    - NETHERITE_SWORD

The model_id must match the <item_id> key in your items.yml file.

💡 Note

The <skin_id> is the identifier for the skin in skins.yml (used for commands, permissions, etc.), while <namespace> is for resource pack asset organization. They can be the same or different.

Build the Resource Pack

Run the build command to generate the resource pack:

/ws pack build

This will:

  • Process all skin folders in pack/skins/
  • Generate the resource pack with all models and textures
  • Host the pack (if self-host is enabled)
  • Push the pack to online players

📝 Complete Example: Leaf Weapon Skin

Here's a complete example of the included leaf_weapon skin:

Directory Structure

📁 pack/skins/leaf_weapon/
📄 items.yml
📁 models/item/
📄 diamond_sword.json
📁 textures/item/
🎨 diamond_sword.png

items.yml

# plugins/WeaponSkin/pack/skins/leaf_weapon/items.yml
namespace: leaf_weapon

items:
  leaf_diamond_sword:
    model: item/diamond_sword

  item_without_model:
    parent_model: item/handheld
    texture: item/short_diamond_sword

models/item/diamond_sword.json

{
    "credit": "Made by leaf studio",
    "texture_size": [ 32, 32 ],
    "textures": {
        "0": "leaf_weapon:item/diamond_sword",
        "particle": "leaf_weapon:item/diamond_sword"
    },
    "elements": [
        {
            "from": [ 7.4, -8.65, 6.4 ],
            "to": [ 8.6, -5.45, 9.6 ],
            "rotation": { "angle": -45, "axis": "x", "origin": [ 8, -7.05, 8 ] },
            "faces": {
                "north": { "uv": [ 1, 9, 1.5, 10.5 ], "texture": "#0" },
                "east": { "uv": [ 5, 0, 6.5, 1.5 ], "texture": "#0" },
                "south": { "uv": [ 1.5, 9, 2, 10.5 ], "texture": "#0" },
                "west": { "uv": [ 5, 1.5, 6.5, 3 ], "texture": "#0" },
                "up": { "uv": [ 2.5, 10.5, 2, 9 ], "texture": "#0" },
                "down": { "uv": [ 3, 9, 2.5, 10.5 ], "texture": "#0" }
            }
        }
        // ... more elements for the full 3D sword model
    ],
    "display": {
        "thirdperson_righthand": { "translation": [ 0, 9, 1.5 ] },
        "thirdperson_lefthand": { "translation": [ 0, 9, 1.5 ] },
        "firstperson_righthand": { "translation": [ 0, 9, 1.5 ] },
        "firstperson_lefthand": { "translation": [ 0, 9, 1.5 ] },
        "ground": { "rotation": [ 90, 90, 0 ] },
        "gui": { "rotation": [ 90, 45, -90 ], "translation": [ 2, 2, 0 ] },
        "fixed": { "rotation": [ -90, 45, 90 ], "translation": [ -2, 2, 0 ] }
    },
    "groups": [
        {
            "name": "sword",
            "origin": [ 7.99, 1.07322, 5.33421 ],
            "color": 0,
            "children": [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ]
        }
    ]
}

skins.yml Entry

leaf_weapon:
  model_id: leaf_diamond_sword
  allowed_materials:
    - DIAMOND_SWORD
    - NETHERITE_SWORD

short_diamond_sword:
  model_id: item_without_model
  allowed_materials:
    - DIAMOND_SWORD
💡 Key Points
  • skin_id (in skins.yml): leaf_weapon - used for commands, permissions, and identifying the skin
  • namespace (in items.yml): leaf_weapon - used for resource pack asset organization and texture references
  • item_id: leaf_diamond_sword - the key in items.yml, referenced by model_id in skins.yml
  • Texture references in the model JSON use leaf_weapon:item/diamond_sword format (namespace:path)
  • The model is a custom 3D model with multiple elements, not a simple parent-based model

👍 Best Practices

🎯 Use Unique Namespaces

Each skin set should have a unique namespace to avoid conflicts with other skins or resource packs.

🔧 Optimize Textures

Keep texture files small (16x16 or 32x32 for most items) to minimize resource pack size and download time.

✅ Test Before Deploying

Always test your skins on a development server before deploying to production. Check for:

  • Correct texture display
  • Proper model positioning in hand
  • No console errors
💾 Backup Your Work

Keep backups of your skin files outside the plugin directory to prevent loss during updates.

🔧 Troubleshooting

❌ Skin not appearing in-game
  • Make sure you ran /ws pack build after adding the skin
  • Check that players have accepted the resource pack
  • Verify the model_id in skins.yml matches a key in items.yml
  • Check server console for any error messages
❌ Texture shows as missing (purple/black checkerboard)
  • Verify the texture path in items.yml matches the actual file location
  • Check that the PNG file is valid and not corrupted
  • Ensure the namespace in items.yml matches the folder structure
❌ Build fails with validation error
  • Check that all model_ids in skins.yml exist in items.yml files
  • Verify YAML syntax in items.yml and skins.yml
  • Check for duplicate model IDs across different skin sets

🛠 Tools & Resources

📦
Blockbench
Free 3D modeling tool for Minecraft. Create custom models and textures.
📖
Minecraft Wiki
Official documentation for Minecraft model JSON format.
📦
Resource Pack Guide
Learn about Minecraft resource pack structure and format.