⚔️ WeaponSkin
一款 Minecraft 插件,允许玩家为武器应用和移除装饰性皮肤——而无需替换物品本身。
支持 Oraxen 以及完全内置的资源包系统(无需额外依赖)。
✨ 功能
- 通过拖放(库存交互)应用自定义武器皮肤
- 使用专用的皮肤移除器物品移除皮肤
- 在应用前按住 Shift + 右键点击预览皮肤
- 内置资源包构建器、HTTP 主机服务器,并自动推送给玩家
- 支持将 Oraxen 作为替代提供者
auto 提供者检测 —— 如果可用则使用 Oraxen,否则自动回退到内置方案
- 多语言支持 —— 可配置的语言文件(英语、越南语)
- 细粒度权限控制 —— 每个子命令都有独立的权限节点
? 文档
完整文档请访问:
? 要求
| 依赖项 |
类型 |
备注 |
| PacketEvents |
必需 |
用于处理装备数据包 |
| Oraxen |
可选 |
仅在 provider: oraxen 时需要 |
| Minecraft |
1.21+ |
API 版本 1.21,item_model 提供者需要 1.21.4+ |
? 安装
- 下载
WeaponSkin.jar 并将其放入你的 plugins/ 文件夹
- 下载 PacketEvents 同样放入
plugins/
- 启动服务器 —— 配置文件将自动生成
- 编辑
plugins/WeaponSkin/config.yml 和 skins.yml
- 运行
/weaponskin pack build(或 /ws pack build)以生成并托管资源包
⚙️ 配置
config.yml
# 所有插件消息的前缀
prefix: "&7[&eWeaponSkin&7] "
# ============================================
# 更新检查器
# ============================================
# 启动时自动检查更新
update-checker: true
# ============================================
# 语言配置
# ============================================
# 语言设置:en | vi
language: en
# 应用/移除皮肤时的声音(全局设置,无单个皮肤的覆盖选项)
apply-sound: ENTITY_PLAYER_LEVELUP
remove-sound: ENTITY_ITEM_BREAK
# 提供者:auto | oraxen | item_model
provider: auto
# 资源包元数据(由内置包构建器使用)
pack:
description: "WeaponSkin resource pack"
namespace: "weaponskin"
# 自动托管配置(仅在 provider = item_model 时使用)
host:
enabled: true # 启用/禁用 HTTP 服务器
required: true # 客户端是否必须接受该资源包
type: "self-host" # self-host | external-host
self-host:
ip: "localhost" # 服务器的公共 IP 或域名
port: 8765
external-host:
url: "https://example.com/packs"
skins.yml
rivers_of_blood:
model_id: riversofblood_sword
allowed_materials:
- DIAMOND_SWORD
- NETHERITE_SWORD
每种皮肤都需要一个 model_id(与 skins/*/items.yml 中的键匹配)以及一个 allowed_materials 列表。
? 提供者模式
| 提供者 |
描述 |
auto |
如果安装了 Oraxen 则使用它,否则回退到 item_model |
item_model |
内置系统 —— 管理资源包的生成和托管 |
oraxen |
将皮肤模型查找完全委托给 Oraxen |
?️ 添加自定义皮肤(内置提供者)
将你的皮肤资产放在 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 格式:
items:
# 情况 1:提供模型(你有自定义 JSON 模型)
my_sword:
model: item/my_sword
# 情况 2:隐式模型生成(仅提供纹理)
my_simple_sword:
parent_model: item/handheld
texture: item/my_simple_texture
然后在 skins.yml 中注册该皮肤,并运行 /weaponskin pack build(或 /ws pack build)。
? 命令
| 命令 |
描述 |
/weaponskin give <player> <skinId> [amount] |
向玩家发放皮肤物品 |
/weaponskin remove <player> [amount] |
向玩家发放皮肤移除器物品 |
/weaponskin remover <player> [amount] |
/weaponskin remove 的别名 |
/weaponskin list |
列出所有已注册的皮肤 |
/weaponskin reload |
重载配置、皮肤、语言和主机设置 |
/weaponskin pack build |
从皮肤资产构建资源包 |
/weaponskin pack apply <url> |
应用托管在外部 URL 上的已构建包 |
别名: 可以使用 /ws 作为 /weaponskin 的快捷方式(例如 /ws give <player> <skinId>)
? 权限
| 权限 |
描述 |
默认值 |
weaponskin.admin |
对所有命令的完全访问权限(父节点) |
OP |
weaponskin.give |
发放皮肤物品 |
OP |
weaponskin.remove |
发放移除器物品 |
OP |
weaponskin.list |
列出所有皮肤 |
OP |
weaponskin.reload |
重载配置 |
OP |
weaponskin.pack |
构建和应用资源包 |
OP |
weaponskin.admin 会自动授予所有子权限。
? 工作原理(玩家端)
| 操作 |
结果 |
| 在库存中将皮肤物品拖放到武器上 |
应用皮肤 |
| 将皮肤移除器拖放到有皮肤的武器上 |
移除皮肤 |
| Shift + 右键点击皮肤物品 |
在你的装备武器上预览皮肤 |
? 资源包托管
自托管(默认)
插件会在配置的端口上启动内部 HTTP 服务器。玩家加入时会自动接收该资源包。
请确保防火墙已开放该端口,并且可以从互联网访问。
外部主机
使用 /weaponskin pack build(或 /ws pack build)构建整合包,然后将 plugins/WeaponSkin/pack/WeaponSkin-pack.zip 上传至你的 CDN 或文件托管服务。最后运行:
/weaponskin pack apply https://your-cdn.com/WeaponSkin-pack.zip
? 多语言支持
该插件支持所有面向用户的消息的多语言显示。
可用语言
| 语言 |
代码 |
文件 |
| 英语 |
en |
langs/en.yml |
| 越南语 |
vi |
langs/vi.yml |
如何更改语言
- 打开
plugins/WeaponSkin/config.yml
- 将
language: 设置为你想要的语言代码(例如 language: vi)
- 运行
/weaponskin reload(或 /ws reload)
添加自定义语言
- 在
plugins/WeaponSkin/langs/ 中创建一个新文件(例如法语的 fr.yml)
- 从现有的语言文件中复制结构
- 翻译所有消息
- 在
config.yml 中设置 language: fr
?️ 从源代码构建
git clone https://github.com/k4han/WeaponSkin.git
cd WeaponSkin
./gradlew build
输出:build/libs/WeaponSkin-*.jar
? 许可证
本项目采用 MIT 许可证授权。
☕ 支持
如果你觉得本插件有用并想支持其开发,可以考虑请我喝杯咖啡!
⚔️ 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:
? 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
- Download
WeaponSkin.jar and place it in your plugins/ folder
- Download PacketEvents and place it in
plugins/ as well
- Start the server — config files will be generated automatically
- Edit
plugins/WeaponSkin/config.yml and skins.yml
- 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
- Open
plugins/WeaponSkin/config.yml
- Set
language: to your desired language code (e.g., language: vi)
- Run
/weaponskin reload (or /ws reload)
Adding Custom Languages
- Create a new file in
plugins/WeaponSkin/langs/ (e.g., fr.yml for French)
- Copy the structure from an existing language file
- Translate all messages
- 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!
评论 0
登录后参与评分
还没有评论,来抢沙发吧