Skip to main content

Item Binding

SigmaTools allows you to bind custom items to tools, enabling you to use ItemsAdder custom items or different vanilla materials as the base for your tools.

Overview​

The item binding feature allows administrators to customize which items are used when creating SigmaTools. Instead of always using the default item-material from config, you can bind specific items (including ItemsAdder custom items) to each tool type.

How It Works​

  1. Bind an Item: Use /sigmatools bind <tool> to open the binding GUI
  2. Select Item: Click a valid item from your inventory
  3. Save Binding: The binding is automatically saved to config.yml
  4. Use Bound Item: Future tool creation uses the bound item instead of default

Command Usage​

Basic Usage​

# Bind a custom pickaxe
/sigmatools bind pickaxe

# Bind a custom axe
/sigmatools bind axe

# Bind a custom bucket
/sigmatools bind bucket

# Bind a custom hoe
/sigmatools bind hoe

What Happens​

  1. Command opens a GUI showing your inventory items
  2. Valid items are highlighted in green
  3. Invalid items are highlighted in red
  4. Click a valid item to bind it
  5. Binding is saved to config automatically

Supported Item Types​

Vanilla Items​

You can bind any vanilla item that matches the tool type:

  • Pickaxe: Any pickaxe material (WOODEN_PICKAXE, IRON_PICKAXE, etc.)
  • Axe: Any axe material (WOODEN_AXE, IRON_AXE, etc.)
  • Hoe: Any hoe material (WOODEN_HOE, IRON_HOE, etc.)
  • Bucket: Any bucket material (BUCKET, WATER_BUCKET, etc.)

ItemsAdder Custom Items​

If ItemsAdder is installed, you can bind custom ItemsAdder items:

  • ItemsAdder items are automatically detected
  • Custom item ID is stored in config
  • Falls back to material if ItemsAdder item not found

Configuration​

After binding an item, the configuration is automatically updated:

Vanilla Item Binding​

tools:
  pickaxe:
    bound-item:
      type: "vanilla"
      material: "IRON_PICKAXE"

ItemsAdder Item Binding​

tools:
  pickaxe:
    bound-item:
      type: "itemsadder"
      itemsadder-id: "namespace:custom_pickaxe"
      material: "IRON_PICKAXE"  # Fallback material

Binding GUI​

The binding GUI provides:

  • Visual Feedback: Green items are valid, red items are invalid
  • Item Validation: Only items matching the tool type can be bound
  • Inventory Display: Shows items from your inventory
  • Cancel Option: Cancel button to exit without binding

GUI Features​

  • Valid items show: ✓ Valid - Click to bind
  • Invalid items show: ✗ Invalid item type
  • Instruction book explains the process
  • Cancel button to exit

Use Cases​

Custom ItemsAdder Tools​

Bind ItemsAdder custom pickaxes, axes, etc. to use custom textures/models:

# Bind an ItemsAdder custom pickaxe
/sigmatools bind pickaxe
# Select your ItemsAdder pickaxe from inventory

Different Material Types​

Use different vanilla materials for variety:

# Use iron pickaxe instead of diamond
/sigmatools bind pickaxe
# Select IRON_PICKAXE from inventory

Server Branding​

Bind custom items that match your server's theme or branding.

How Bound Items Work​

  1. Priority: Bound items take priority over item-material setting
  2. Tool Creation: When giving tools, the bound item is used as the base
  3. NBT Addition: SigmaTools NBT data is added to the bound item
  4. Fallback: If bound item not found, falls back to item-material

Clearing Bindings​

To remove a binding and use the default item-material:

  1. Edit config.yml manually
  2. Remove or comment out the bound-item section: 
    tools:
      pickaxe:
        # bound-item:
        #   type: "vanilla"
        #   material: "IRON_PICKAXE"
  3. Reload: /sigmatools reload

Validation​

The plugin validates bound items:

  • Type Check: Item must match tool type (pickaxe for pickaxe tool)
  • Material Check: Vanilla materials must be valid
  • ItemsAdder Check: ItemsAdder items must exist and be valid
  • Fallback: Invalid bindings fall back to default item-material

Examples​

Example 1: Bind ItemsAdder Custom Pickaxe​

# 1. Have ItemsAdder custom pickaxe in inventory
# 2. Run command
/sigmatools bind pickaxe

# 3. GUI opens showing your inventory
# 4. Click the ItemsAdder pickaxe (highlighted in green)
# 5. Success message appears
# 6. Config is updated automatically

Example 2: Bind Iron Pickaxe​

# 1. Have IRON_PICKAXE in inventory
# 2. Run command
/sigmatools bind pickaxe

# 3. Click IRON_PICKAXE in GUI
# 4. Binding saved

Troubleshooting​

"Invalid item! You must select a pickaxe."​

Cause: Selected item doesn't match the tool type

Solution: Select an item that matches the tool type (pickaxe for pickaxe tool, etc.)

Binding Not Working​

Causes:

  • ItemsAdder not installed (for ItemsAdder items)
  • Invalid item type
  • Permission issues

Solutions:

  1. Check you have sigmatools.admin permission
  2. Verify item type matches tool type
  3. For ItemsAdder items, ensure ItemsAdder is installed
  4. Check console for error messages

Bound Item Not Used​

Causes:

  • Config not reloaded after binding
  • Binding removed from config
  • ItemsAdder item not found

Solutions:

  1. Reload config: /sigmatools reload
  2. Verify binding exists in config.yml
  3. For ItemsAdder items, ensure ItemsAdder is loaded

Best Practices​

  1. Test Bindings: Test bound items before using in production
  2. Backup Config: Backup config.yml before binding
  3. ItemsAdder Items: Ensure ItemsAdder items are properly configured
  4. Documentation: Document your bindings for reference
  5. Validation: Always validate bound items work correctly

Technical Details​

Binding Storage​

Bindings are stored in config.yml:

tools:
  <tool-name>:
    bound-item:
      type: "vanilla" | "itemsadder"
      material: "MATERIAL_NAME"
      itemsadder-id: "namespace:id"  # Only for ItemsAdder

Binding Priority​

  1. Check for bound item
  2. If bound item exists and is valid, use it
  3. Otherwise, use item-material from config
  4. Fallback to default material if both fail

ItemsAdder Integration​

  • Automatically detects ItemsAdder items
  • Stores custom item ID for retrieval
  • Falls back to material if ItemsAdder item not found
  • Works seamlessly with ItemsAdder updates

Next Steps​