📥 Installation

Step-by-step guide to install and set up WeaponSkin on your Minecraft server.

📋 Requirements

Before installing WeaponSkin, make sure your server meets the following requirements:

Requirement Details
Minecraft Server 1.21 or higher (API version 1.21)
PacketEvents Required dependency for equipment packet handling
Oraxen Optional Only needed if using provider: oraxen
item_model Provider Requires Minecraft 1.21.4+ for built-in resource pack system
⚠ Important

The item_model provider (built-in resource pack system) requires Minecraft 1.21.4 or higher. If you're running an older version, you'll need to use Oraxen as the provider.

🚀 Installation Steps

Download WeaponSkin

Download the latest WeaponSkin.jar from the GitHub Releases page.

Download PacketEvents

Download PacketEvents from the official releases page. This is a required dependency.

Place Files in plugins Folder

Place both JAR files in your server's plugins/ folder:

📁 plugins/
📄 WeaponSkin.jar
📄 packetevents-x.x.x.jar
Start the Server

Start your Minecraft server. The plugin will automatically generate configuration files in plugins/WeaponSkin/.

Configure the Plugin

Edit the configuration files to customize the plugin:

  • config.yml - Main configuration (provider, sounds, host settings)
  • skins.yml - Skin definitions
  • langs/en.yml - Language file (English)
  • langs/vi.yml - Language file (Vietnamese)
Build the Resource Pack

Run the following command to generate and host the resource pack:

/weaponskin pack build

Or use the alias:

/ws pack build

✅ Post-Installation

After completing the installation:

  • Players will automatically receive the resource pack when joining (if host.enabled: true)
  • Use /ws give to give skin items to players
  • Use /ws remove to give Skin Remover items
  • Use /ws list to see all registered skins

🔧 Building from Source

If you want to build the plugin from source:

git clone https://github.com/k4han/WeaponSkin.git
cd WeaponSkin
./gradlew build

The compiled JAR will be available at build/libs/WeaponSkin-*.jar.

🔧 Troubleshooting

❌ Plugin doesn't load

Make sure PacketEvents is installed. Check the server console for any error messages.

❌ Resource pack not loading for players

Check that host.enabled: true in config.yml and the port specified in host.self-host.port is open and accessible from the internet.

❌ Skins not appearing

Make sure you've run /ws pack build after adding skins. Check that model_id in skins.yml matches a key in items.yml.

❌ Port already in use

Change the port in host.self-host.port to an available port. Make sure to update your firewall rules accordingly.

📖 Next Steps

⚙
Configuration
Learn how to configure the plugin for your server.
🎨
Custom Skins
Create and add your own custom weapon skins.
💻
Commands
View all available commands and their usage.