Getting Started

Requirements

• Java: Java 21 or newer, also meeting your server’s own Java requirement.
• Server: The build targets Paper 1.20.4 API, and Command Framework 1.6.5 directly calls Paper Adventure audiences. Spigot and Folia compatibility are not established.

The descriptor retains api-version: 1.13. Neither that value nor legacy compatibility helpers establish a tested Minecraft version range. Validate the exact server release and custom-item provider versions before using valuable items.

Optional Integrations

• Vault plus an economy provider Optional: Required only for paid upgrades.
• PlaceholderAPI Optional: Allows external placeholders inside supported player messages.
• Oraxen, ItemsAdder, or EcoItems Optional: Install only the custom-item providers used by your recipes.

Installation

1. Download Item Upgrader from its official Hub, SpigotMC or BuiltByBit page.
2. Place item-upgrader-x.x.x.jar in the server’s plugins/ directory.
3. Install Vault, an economy provider, or any custom-item plugin required by your configuration.
4. Restart the server to generate /plugins/ItemUpgrader/.
5. Hold a source item from the default recipes and run /itemupgrader.

Generated Files

File	Purpose
config.yml	Menu access, allowed worlds, source material allowlist, addon delay, sounds, and ingredient removal rules.
messages.yml	Player feedback and the upgrade and confirmation menu layouts.
upgrades.yml	All item transformation recipes.

First Custom Recipe

1. Add the source material to upgradable-items in config.yml.
2. Add one recipe under upgrades in upgrades.yml.
3. Run /itemupgrader reload.
4. Hold at least the recipe’s from.amount in the main hand.
5. Open /itemupgrader and test the cancel, success, and failure paths.

Continue with Creating Upgrades for a complete field-by-field example.