Configuration - WeaponSkin Documentation

🗂 config.yml

The main configuration file controls global plugin settings.

Full Configuration Example

# ============================================
# WeaponSkin Configuration
# ============================================

# Prefix for all plugin messages
# Use Minecraft color codes (&a, &c, &e, ...)
prefix: "&7[&eWeaponSkin&7] "

# Language file to use (without .yml extension)
# Available options: en, vi
language: en

# Global Sounds - Applied to ALL skins. No per-skin override.
apply-sound: ENTITY_PLAYER_LEVELUP
remove-sound: ENTITY_ITEM_BREAK

# Provider Configuration
# Global provider applied to ALL skins.
#
# Options:
#   - auto: Prefer Oraxen if available, fallback item_model (default)
#   - oraxen: Use Oraxen provider (requires Oraxen plugin)
#   - item_model: Use item_model component (1.21.4+) - recommended
provider: auto

# Resource Pack Metadata
# Description shown in pack.mcmeta.
pack:
  description: "WeaponSkin resource pack"
  namespace: "weaponskin"

# Auto-Host Configuration
# Settings for automatic HTTP hosting and push to players
# Only used when provider = item_model
host:
  # Enable/disable auto-host feature
  enabled: true

  # Whether accepting this resource pack is required.
  required: true

  # Host type: "self-host" or "external-host"
  type: "self-host"

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

  # Self-host configuration
  self-host:
    ip: "localhost"
    port: 8765

🗂 Configuration Options

Option	Type	Default	Description
`prefix`	String	`&7[&eWeaponSkin&7]`	Prefix for all chat messages. Supports color codes.
`language`	String	`en`	Language file to use. Options: `en`, `vi`
`apply-sound`	String	`ENTITY_PLAYER_LEVELUP`	Sound played when a skin is applied.
`remove-sound`	String	`ENTITY_ITEM_BREAK`	Sound played when a skin is removed.
`provider`	String	`auto`	Skin provider mode. See Provider Modes section.

📦 Provider Modes

The provider setting determines how skins are handled:

✅ auto (Recommended)

Automatically detects and uses Oraxen if installed, otherwise falls back to the built-in item_model system. This is the most flexible option.

🔧 item_model

Uses the built-in resource pack system. Requires Minecraft 1.21.4+. The plugin handles resource pack generation, hosting, and distribution automatically.

🔥 oraxen

Delegates all skin handling to the Oraxen plugin. Requires Oraxen to be installed. Use this if you already use Oraxen for custom items.

🌐 Resource Pack Hosting

When using provider: item_model, you can configure how the resource pack is distributed to players.

Self-Host (Default)

The plugin runs an internal HTTP server to host the resource pack:

host:
  enabled: true
  required: true
  type: "self-host"
  self-host:
    ip: "localhost"    # Your server's public IP or domain
    port: 8765         # Port for HTTP server

⚠ Warning

Make sure the specified port is open in your firewall and accessible from the internet. Players won't be able to download the resource pack if the port is blocked.

External Host

Upload the resource pack to a CDN or file hosting service:

host:
  enabled: true
  required: true
  type: "external-host"
  external-host:
    url: "https://your-cdn.com/packs"

After building the pack with /ws pack build, upload the generated ZIP file to your host, then run:

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

🗂 skins.yml

This file defines which skins are available and what weapons they can be applied to.

Example Configuration

# Each skin requires:
#   - model_id: must match a key in skins/*/items.yml
#   - allowed_materials: list of materials this skin can be applied to

leaf_weapon:
  model_id: leaf_diamond_sword
  allowed_materials:
    - DIAMOND_SWORD
    - NETHERITE_SWORD

rivers_of_blood:
  model_id: riversofblood_sword
  allowed_materials:
    - DIAMOND_SWORD
    - NETHERITE_SWORD

Skin Definition Fields

Field	Required	Description
`model_id`	Required	The model identifier that matches a key in `skins/*/items.yml`
`allowed_materials`	Required	List of Minecraft material types this skin can be applied to