# \u2694\ufe0f WeaponSkin<\/p>\n
A Minecraft plugin that lets players apply and remove cosmetic skins on weapons \u2014 without replacing the item itself.<\/p>\n
> Supports **Oraxen** and a fully **built-in resource pack system** (no dependencies required).<\/p>\n
—<\/p>\n
## \u2728 Features<\/p>\n
– Apply custom weapon skins via drag-and-drop (inventory interaction)
\n– Remove skins with a dedicated **Skin Remover** item
\n– Preview skins before applying with **Shift + Right Click**
\n– Built-in resource pack builder, HTTP host server, and auto-push to players
\n– Supports **Oraxen** as an alternative provider
\n– `auto` provider detection \u2014 uses Oraxen if available, falls back to built-in automatically
\n– **Multi-language support** \u2014 configurable language files (English, Vietnamese)
\n– **Granular permissions** \u2014 individual permission nodes for each sub-command<\/p>\n
—<\/p>\n
## \ud83d\udcda Documentation<\/p>\n
Full documentation is available at: **https:\/\/k4han.github.io\/WeaponSkin\/**<\/p>\n
—<\/p>\n
## \ud83d\udccb Requirements<\/p>\n
| Dependency | Type | Notes |
\n|—|—|—|
\n| PacketEvents | Required | For equipment packet handling |
\n| Oraxen | Optional | Only needed if `provider: oraxen` |
\n| Minecraft | 1.21+ | API version `1.21`, `item_model` provider requires 1.21.4+ |<\/p>\n
—<\/p>\n
## \ud83d\ude80 Installation<\/p>\n
1. Download `WeaponSkin.jar` and place it in your `plugins\/` folder
\n2. Download PacketEvents and place it in `plugins\/` as well
\n3. Start the server \u2014 config files will be generated automatically
\n4. Edit `plugins\/WeaponSkin\/config.yml` and `skins.yml`
\n5. Run `\/weaponskin pack build` (or `\/ws pack build`) to generate and host the resource pack<\/p>\n
—<\/p>\n
## \u2699\ufe0f Configuration<\/p>\n
### `config.yml`<\/p>\n
“`yaml
\n# Prefix for all plugin messages
\nprefix: “&7[&eWeaponSkin&7] ”<\/p>\n
# ============================================
\n# Update Checker
\n# ============================================
\n# Automatically check for updates on startup
\nupdate-checker: true<\/p>\n
# ============================================
\n# Language Configuration
\n# ============================================
\n# Language setting: en | vi
\nlanguage: en<\/p>\n
# Sounds for applying\/removing skins (global, no per-skin override)
\napply-sound: ENTITY_PLAYER_LEVELUP
\nremove-sound: ENTITY_ITEM_BREAK<\/p>\n
# Provider: auto | oraxen | item_model
\nprovider: auto<\/p>\n
# Resource Pack metadata (used by built-in pack builder)
\npack:
\n description: “WeaponSkin resource pack”
\n namespace: “weaponskin”<\/p>\n
# Auto-Host Configuration (only used when provider = item_model)
\nhost:
\n enabled: true # Enable\/disable HTTP server
\n required: true # Whether clients MUST accept the resource pack
\n type: “self-host” # self-host | external-host<\/p>\n
self-host:
\n ip: “localhost” # Public IP or domain of your server
\n port: 8765<\/p>\n
external-host:
\n url: “https:\/\/example.com\/packs”
\n“`<\/p>\n
### `skins.yml`<\/p>\n
“`yaml
\nrivers_of_blood:
\n model_id: riversofblood_sword
\n allowed_materials:
\n – DIAMOND_SWORD
\n – NETHERITE_SWORD
\n“`<\/p>\n
> Each skin requires a `model_id` (matching a key in `skins\/*\/items.yml`) and a list of `allowed_materials`.<\/p>\n
—<\/p>\n
## \ud83d\udce6 Provider Modes<\/p>\n
| Provider | Description |
\n|—|—|
\n| `auto` | Uses Oraxen if installed, otherwise falls back to `item_model` |
\n| `item_model` | Built-in system \u2014 manages resource pack generation and hosting |
\n| `oraxen` | Delegates skin model lookup entirely to Oraxen |<\/p>\n
—<\/p>\n
## \ud83d\uddc2\ufe0f Adding Custom Skins (Built-in Provider)<\/p>\n
Place your skin assets inside `plugins\/WeaponSkin\/pack\/skins\/ “` **`items.yml` format:** # Case 2: Implicit Model Generation (only texture provided) Then register the skin in `skins.yml` and run `\/weaponskin pack build` (or `\/ws pack build`).<\/p>\n —<\/p>\n ## \ud83d\udd27 Commands<\/p>\n | Command | Description | > **Alias:** `\/ws` can be used as a shortcut for `\/weaponskin` (e.g., `\/ws give —<\/p>\n ## \ud83d\udd10 Permissions<\/p>\n | Permission | Description | Default | > `weaponskin.admin` grants all child permissions automatically.<\/p>\n —<\/p>\n ## \ud83c\udfae How It Works (Player Side)<\/p>\n | Action | Result | —<\/p>\n ## \ud83c\udf10 Resource Pack Hosting<\/p>\n ### Self-host (default) > Make sure the port is open in your firewall and accessible from the internet.<\/p>\n ### External host —<\/p>\n ## \ud83c\udf0d Multi-Language Support<\/p>\n The plugin supports multiple languages for all user-facing messages.<\/p>\n ### Available Languages<\/p>\n | Language | Code | File | ### How to Change Language<\/p>\n 1. Open `plugins\/WeaponSkin\/config.yml` ### Adding Custom Languages<\/p>\n 1. Create a new file in `plugins\/WeaponSkin\/langs\/` (e.g., `fr.yml` for French) —<\/p>\n ## \ud83d\udee0\ufe0f Building from Source<\/p>\n “`bash Output: `build\/libs\/WeaponSkin-*.jar`<\/p>\n —<\/p>\n ## \ud83d\udcc4 License<\/p>\n This project is licensed under the MIT License.<\/p>\n —<\/p>\n ## \u2615 Support<\/p>\n If you find this plugin helpful and want to support its development, consider buying me a coffee!<\/p>\n <\/p>\n","protected":false},"excerpt":{"rendered":" Minecraft plugin for applying custom cosmetic skins to weapons<\/p>\n","protected":false},"featured_media":169260,"template":"","meta":{"_minecraft_slug":"weaponskin","_minecraft_project_id":"o8dhTE2h","_minecraft_author":"k4han","_minecraft_license":"MIT","_minecraft_downloads":165,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"weaponskin.zip","_minecraft_size_bytes":123441,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-16T13:14:21.746142Z","_minecraft_date_created":"2026-03-04T05:13:54.410215Z","_minecraft_date_modified":"2026-02-24T18:01:08.211810Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/weaponskin","_minecraft_icon_attachment_id":169260,"_minecraft_imported_at":"2026-06-09T20:07:54+00:00","_minecraft_import_hash":"5bdd41b05eb0960dc3f9509643b6f648","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,88,127,129,92],"mod_loader":[130,132,134],"minecraft_version":[40,41,38,78,79,80,81,82],"class_list":["post-169259","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-equipment","mod_category-paper","mod_category-spigot","mod_category-utility","mod_loader-bukkit","mod_loader-paper","mod_loader-spigot","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\npack\/skins\/my_skin\/
\n\u251c\u2500\u2500 items.yml
\n\u251c\u2500\u2500 models\/item\/
\n\u2502 \u2514\u2500\u2500 my_sword.json
\n\u2514\u2500\u2500 textures\/item\/
\n \u2514\u2500\u2500 my_sword.png
\n“`<\/p>\n
\n“`yaml
\nitems:
\n # Case 1: Model provided (you have a custom JSON model)
\n my_sword:
\n model: item\/my_sword<\/p>\n
\n my_simple_sword:
\n parent_model: item\/handheld
\n texture: item\/my_simple_texture
\n“`<\/p>\n
\n|—|—|
\n| `\/weaponskin give
\n| `\/weaponskin remove
\n| `\/weaponskin remover
\n| `\/weaponskin list` | List all registered skins |
\n| `\/weaponskin reload` | Reload config, skins, language, and host settings |
\n| `\/weaponskin pack build` | Build the resource pack from skin assets |
\n| `\/weaponskin pack apply
\n|—|—|—|
\n| `weaponskin.admin` | Full access to all commands (parent node) | OP |
\n| `weaponskin.give` | Give skin items | OP |
\n| `weaponskin.remove` | Give remover items | OP |
\n| `weaponskin.list` | List all skins | OP |
\n| `weaponskin.reload` | Reload configuration | OP |
\n| `weaponskin.pack` | Build and apply resource packs | OP |<\/p>\n
\n|—|—|
\n| Drag skin item onto a weapon in inventory | Applies the skin |
\n| Drag Skin Remover onto a skinned weapon | Removes the skin |
\n| Shift + Right Click a skin item | Preview the skin on your equipped weapon |<\/p>\n
\nThe plugin starts an internal HTTP server on the configured port. Players automatically receive the pack on join.<\/p>\n
\nBuild 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:
\n“`
\n\/weaponskin pack apply https:\/\/your-cdn.com\/WeaponSkin-pack.zip
\n“`<\/p>\n
\n|—|—|—|
\n| English | `en` | `langs\/en.yml` |
\n| Vietnamese | `vi` | `langs\/vi.yml` |<\/p>\n
\n2. Set `language:` to your desired language code (e.g., `language: vi`)
\n3. Run `\/weaponskin reload` (or `\/ws reload`)<\/p>\n
\n2. Copy the structure from an existing language file
\n3. Translate all messages
\n4. Set `language: fr` in `config.yml`<\/p>\n
\ngit clone https:\/\/github.com\/k4han\/WeaponSkin.git
\ncd WeaponSkin
\n.\/gradlew build
\n“`<\/p>\n