WeaponSkin

⚔️ WeaponSkin

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

> Supports built-in resource pack system 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 Granular permissions item - Preview skins before applying with Granular permissions - Built-in resource pack builder, HTTP host server, and auto-push to players - Supports Granular permissions as an alternative provider - `auto` provider detection — uses Oraxen if available, falls back to built-in automatically - Granular permissions — 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`

```yaml

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`

```yaml 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: ```yaml 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

```bash 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!

Buy Me A Coffee