module dismantle

🛠️ Dismantle Module

The Dismantle module allows players to break down gear into materials using configurable tools and reward definitions. This system supports gear recycling, crafting loops, and economy balancing.

---

📦 How It Works

Players use a Dismantle Tool to destroy another item and receive materials or rewards.

The system requires two components:

1. A dismantle tool item
   ➤ Defined in: plugins/Divinity/modules/dismantle/items

2. A matching dismantle source file
   ➤ Defined in: plugins/Divinity/modules/dismantle/source

These must be configured together — a dismantle item will not work without a valid source file.

---

🧰 Dismantle Tool Format

A dismantle tool is a regular item that includes target-requirements to restrict what it can dismantle.

material: SHEARS
name: Armor Dismantle Tool
tier: common
item-flags:
  - '*'

uses-by-level:
  '1': 1
  '2': 2
  '3': 3

level:
  min: 1
  max: 3

target-requirements:
  type:
    - ARMOR
  level:
    '1': 1
  module:
    - '*'

Save this in plugins/Divinity/modules/dismantle/items/.

---

📁 Source Files (Reward Definitions)

Each dismantle tool must be paired with a source file, which defines:

• Which items (by module, ID, or level) it can dismantle
• What rewards can be generated
• The cost, if any (e.g., XP or currency)
• The GUI preview items

Save source files in:
plugins/Divinity/modules/dismantle/source/

Example

input-module: gems

output-by-item-id-level:
  default:
    '1':
      cost: 15
      output:
        emeralds:
          chance: 10.0
          item:
            material: EMERALD
            amount: 17
            name: '&aEmerald'
          preview:
            material: EMERALD
            amount: 17
            name: '&aEmerald &7(10%)'

        sulphur:
          chance: 100.0
          item:
            material: GUNPOWDER
          preview:
            material: GUNPOWDER
            name: '&8Sulphur &7(100%)'

        nugget:
          chance: 15.0
          commands:
            - '[CONSOLE] eco give %player% 10'
          preview:
            material: GOLD_NUGGET
            name: '&e10$ &7(15%)'

---

🎁 Reward Types

You can define two types of rewards:

• item: → Gives a vanilla Minecraft item using material, amount, name, and lore
• commands: → Executes commands to give custom items or trigger effects

You can combine both in a single reward entry if needed.

---

⚠️ GUI Preview Behavior

The dismantle GUI shows all potential rewards, but they are not guaranteed.

Each reward entry has a chance: — only entries that succeed their roll are granted.

The GUI preview shows the maximum possible reward pool, not the actual result.

To help players understand this:

• Add % indicators to preview names (e.g., &7(15%))
• Use lore or tutorial items to explain dismantling behavior

---

🔐 Permissions

divinity.dismantle.use      # Allows using dismantle tools
divinity.dismantle.bypass   # Bypasses restrictions or requirements

---

🧪 Tips

• You must define matching source files or dismantle tools will do nothing.
• Use target-requirements to restrict dismantling by item type, module, or level.
• Combine with Loot, Crafting, and Essences for full RPG item loops.
• Use preview names to show reward chances and reduce confusion.

---

📚 Related Pages

• Modules Hub
• Actions System Hub