Introduction

Introduction to Alchemy

Alchemy is a server-side Minecraft Fabric mod designed to automate item data migration and conversion. Built for Minecraft 1.21.1, it provides a robust configuration-based system for transforming items during world transitions or plugin migrations.

What is Alchemy?

Alchemy intercepts item deserialization and applies rule-based transformations, making it perfect for:

• Server Migrations: Converting items when moving from Bukkit/Spigot to Fabric
• Plugin Transitions: Migrating custom items between different item systems (Oraxen, ItemsAdder, etc.)
• Data Restructuring: Updating item component structures for new versions
• Legacy Support: Maintaining compatibility with old item formats

Key Features

Transmutation System

The core of Alchemy is its transmutation system - a powerful rules engine that:

• Matches items using flexible conditions
• Applies sequential operations to transform item data
• Supports priority-based rule ordering
• Handles complex nested component structures

Configuration-Based

All conversions are defined in JSON configuration files, making it:

• Easy to version control
• Simple to share between servers
• Possible to update without recompiling
• Testable and debuggable

Zero-Copy Performance

Alchemy only processes items that match configured rules, leaving unaffected items completely untouched for optimal performance.

Quick Example

Here’s a simple transmutation rule that converts Oraxen items to a custom format:

{
  "conversions": [
    {
      "id": "oraxen_items",
      "priority": 100,
      "condition": {
        "type": "component_exists",
        "path": "components.minecraft:custom_data.PublicBukkitValues.oraxen:id"
      },
      "operations": [
        {
          "type": "set_item_id_from_lookup",
          "source": "components.minecraft:custom_data.PublicBukkitValues.oraxen:id",
          "mapping": {
            "ruby_sword": "custom:ruby_sword",
            "emerald_pickaxe": "custom:emerald_pickaxe"
          }
        },
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        }
      ]
    }
  ]
}

Getting Started

Ready to start using Alchemy? Check out the Installation Guide to get up and running!