⚔️ WeaponSkin

A Minecraft plugin that lets players apply and remove cosmetic skins on weapons — without replacing the item itself.

Supports Oraxen and a fully built-in resource pack system (no dependencies required).

---

✨ Features

• Apply custom weapon skins via drag-and-drop (inventory interaction)
• Remove skins with a dedicated Skin Remover item
• Preview skins before applying with Shift + Right Click
• Built-in resource pack builder, HTTP host server, and auto-push to players
• Supports Oraxen as an alternative provider
• auto provider detection — uses Oraxen if available, falls back to built-in automatically
• Multi-language support — configurable language files (English, Vietnamese)
• Granular permissions — individual permission nodes for each sub-command

---

📚 Documentation

Full documentation is available at: https://k4han.github.io/WeaponSkin/

---

📋 Requirements

Dependency	Type	Notes
PacketEvents	Required	For equipment packet handling
Oraxen	Optional	Only needed if provider: oraxen
Minecraft	1.21+	API version 1.21, item_model provider requires 1.21.4+

---

🚀 Installation

1. Download WeaponSkin.jar and place it in your plugins/ folder
2. Download PacketEvents and place it in plugins/ as well
3. Start the server — config files will be generated automatically
4. Edit plugins/WeaponSkin/config.yml and skins.yml
5. Run /weaponskin pack build (or /ws pack build) to generate and host the resource pack

---

⚙️ Configuration

config.yml

# Prefix for all plugin messages
prefix: "&7[&eWeaponSkin&7] "

# ============================================
# Update Checker
# ============================================
# Automatically check for updates on startup
update-checker: true

# ============================================
# Language Configuration
# ============================================
# Language setting: en | vi
language: en

# Sounds for applying/removing skins (global, no per-skin override)
apply-sound: ENTITY_PLAYER_LEVELUP
remove-sound: ENTITY_ITEM_BREAK

# Provider: auto | oraxen | item_model
provider: auto

# Resource Pack metadata (used by built-in pack builder)
pack:
  description: "WeaponSkin resource pack"
  namespace: "weaponskin"

# Auto-Host Configuration (only used when provider = item_model)
host:
  enabled: true          # Enable/disable HTTP server
  required: true         # Whether clients MUST accept the resource pack
  type: "self-host"      # self-host | external-host

  self-host:
    ip: "localhost"      # Public IP or domain of your server
    port: 8765

  external-host:
    url: "https://example.com/packs"

skins.yml

rivers_of_blood:
  model_id: riversofblood_sword
  allowed_materials:
    - DIAMOND_SWORD
    - NETHERITE_SWORD

Each skin requires a model_id (matching a key in skins/*/items.yml) and a list of allowed_materials.

---

📦 Provider Modes

Provider	Description
auto	Uses Oraxen if installed, otherwise falls back to item_model
item_model	Built-in system — manages resource pack generation and hosting
oraxen	Delegates skin model lookup entirely to Oraxen

---

🗂️ Adding Custom Skins (Built-in Provider)

Place your skin assets inside plugins/WeaponSkin/pack/skins/<skin_set_name>/:

pack/skins/my_skin/
├── items.yml
├── models/item/
│   └── my_sword.json
└── textures/item/
    └── my_sword.png

items.yml format:

items:
  # Case 1: Model provided (you have a custom JSON model)
  my_sword:
    model: item/my_sword

  # Case 2: Implicit Model Generation (only texture provided)
  my_simple_sword:
    parent_model: item/handheld
    texture: item/my_simple_texture

Then register the skin in skins.yml and run /weaponskin pack build (or /ws pack build).

---

🔧 Commands

Command	Description
/weaponskin give <player> <skinId> [amount]	Give a skin item to a player
/weaponskin remove <player> [amount]	Give a Skin Remover item to a player
/weaponskin remover <player> [amount]	Alias for /weaponskin remove
/weaponskin list	List all registered skins
/weaponskin reload	Reload config, skins, language, and host settings
/weaponskin pack build	Build the resource pack from skin assets
/weaponskin pack apply <url>	Apply a built pack hosted on an external URL

Alias: /ws can be used as a shortcut for /weaponskin (e.g., /ws give <player> <skinId>)

---

🔐 Permissions

Permission	Description	Default
weaponskin.admin	Full access to all commands (parent node)	OP
weaponskin.give	Give skin items	OP
weaponskin.remove	Give remover items	OP
weaponskin.list	List all skins	OP
weaponskin.reload	Reload configuration	OP
weaponskin.pack	Build and apply resource packs	OP

weaponskin.admin grants all child permissions automatically.

---

🎮 How It Works (Player Side)

Action	Result
Drag skin item onto a weapon in inventory	Applies the skin
Drag Skin Remover onto a skinned weapon	Removes the skin
Shift + Right Click a skin item	Preview the skin on your equipped weapon

---

🌐 Resource Pack Hosting

Self-host (default)

The plugin starts an internal HTTP server on the configured port. Players automatically receive the pack on join.

Make sure the port is open in your firewall and accessible from the internet.

External host

Build the pack with /weaponskin pack build (or /ws pack build), then upload plugins/WeaponSkin/pack/WeaponSkin-pack.zip to your CDN or file host. Finally run:

/weaponskin pack apply https://your-cdn.com/WeaponSkin-pack.zip

---

🌍 Multi-Language Support

The plugin supports multiple languages for all user-facing messages.

Available Languages

Language	Code	File
English	en	langs/en.yml
Vietnamese	vi	langs/vi.yml

How to Change Language

1. Open plugins/WeaponSkin/config.yml
2. Set language: to your desired language code (e.g., language: vi)
3. Run /weaponskin reload (or /ws reload)

Adding Custom Languages

1. Create a new file in plugins/WeaponSkin/langs/ (e.g., fr.yml for French)
2. Copy the structure from an existing language file
3. Translate all messages
4. Set language: fr in config.yml

---

🛠️ Building from Source

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

Output: build/libs/WeaponSkin-*.jar

---

📄 License

This project is licensed under the MIT License.

---

☕ Support

If you find this plugin helpful and want to support its development, consider buying me a coffee!