Example Configurations

Example Configurations

This page provides complete, real-world examples of transmutation configurations for common migration scenarios.

Oraxen Item Migration

Converting Oraxen custom 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",
            "sapphire_axe": "custom:sapphire_axe",
            "obsidian_hammer": "custom:obsidian_hammer"
          },
          "defaultValue": "minecraft:stick"
        },
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        }
      ]
    }
  ]
}

What it does:

1. Detects Oraxen items by checking for PublicBukkitValues.oraxen:id
2. Maps old Oraxen IDs to new custom item IDs
3. Removes Bukkit plugin data

---

ItemsAdder Magic Items

Converting ItemsAdder magic items with stat preservation:

{
  "conversions": [
    {
      "id": "itemsadder_magic_weapons",
      "priority": 150,
      "condition": {
        "type": "all",
        "all": [
          {
            "type": "component_exists",
            "path": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:id"
          },
          {
            "type": "component_equals",
            "path": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:category",
            "value": "magic_weapons"
          }
        ]
      },
      "operations": [
        {
          "type": "set_item_id_from_lookup",
          "source": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:id",
          "mapping": {
            "fire_staff": "custom:weapons/fire_staff",
            "ice_staff": "custom:weapons/ice_staff",
            "lightning_staff": "custom:weapons/lightning_staff"
          }
        },
        {
          "type": "set_component",
          "component": "custom:magic_stats",
          "value": {
            "type": "map",
            "map": {
              "mana_cost": {
                "type": "from_source",
                "fromPath": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:mana"
              },
              "spell_power": {
                "type": "from_source",
                "fromPath": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:power"
              },
              "element": {
                "type": "from_source",
                "fromPath": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:element"
              },
              "migrated": {
                "type": "boolean",
                "boolean": true
              }
            }
          }
        },
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        }
      ]
    }
  ]
}

What it does:

1. Matches ItemsAdder items in the “magic_weapons” category
2. Converts item IDs using lookup table
3. Creates new custom:magic_stats component with preserved data
4. Cleans up old Bukkit data

---

Armor Set Conversion

Converting custom armor sets with set bonuses:

{
  "conversions": [
    {
      "id": "ruby_armor_set",
      "priority": 90,
      "condition": {
        "type": "all",
        "all": [
          {
            "type": "component_exists",
            "path": "components.minecraft:custom_data.armor_set"
          },
          {
            "type": "component_equals",
            "path": "components.minecraft:custom_data.armor_set.type",
            "value": "ruby"
          }
        ]
      },
      "operations": [
        {
          "type": "set_item_id_from_lookup",
          "source": "components.minecraft:custom_data.armor_set.piece",
          "mapping": {
            "helmet": "custom:armor/ruby_helmet",
            "chestplate": "custom:armor/ruby_chestplate",
            "leggings": "custom:armor/ruby_leggings",
            "boots": "custom:armor/ruby_boots"
          }
        },
        {
          "type": "set_component",
          "component": "custom:armor_properties",
          "value": {
            "type": "map",
            "map": {
              "set_name": {
                "type": "string",
                "string": "ruby_guardian"
              },
              "defense": {
                "type": "from_source",
                "fromPath": "components.minecraft:custom_data.armor_set.stats.defense"
              },
              "toughness": {
                "type": "from_source",
                "fromPath": "components.minecraft:custom_data.armor_set.stats.toughness"
              },
              "set_bonus": {
                "type": "string",
                "string": "fire_resistance"
              }
            }
          }
        },
        {
          "type": "remove_custom_data_key",
          "path": "armor_set"
        }
      ]
    }
  ]
}

What it does:

1. Matches ruby armor pieces
2. Converts each piece to the correct new item ID
3. Preserves stats and adds set bonus information
4. Removes old armor data

---

Legacy Data Version Migration

Migrating between internal data versions:

{
  "conversions": [
    {
      "id": "legacy_to_v2_migration",
      "priority": 200,
      "condition": {
        "type": "all",
        "all": [
          {
            "type": "component_exists",
            "path": "components.minecraft:custom_data.legacy_data"
          },
          {
            "type": "component_equals",
            "path": "components.minecraft:custom_data.legacy_data.version",
            "value": 1
          }
        ]
      },
      "operations": [
        {
          "type": "set_item_id_from_component",
          "source": "components.minecraft:custom_data.legacy_data.new_item_id"
        },
        {
          "type": "set_component",
          "component": "custom:item_data_v2",
          "value": {
            "type": "map",
            "map": {
              "identifier": {
                "type": "from_source",
                "fromPath": "components.minecraft:custom_data.legacy_data.id"
              },
              "owner": {
                "type": "map",
                "map": {
                  "uuid": {
                    "type": "from_source",
                    "fromPath": "components.minecraft:custom_data.legacy_data.player.uuid"
                  },
                  "name": {
                    "type": "from_source",
                    "fromPath": "components.minecraft:custom_data.legacy_data.player.name"
                  }
                }
              },
              "stats": {
                "type": "map",
                "map": {
                  "level": {
                    "type": "from_source",
                    "fromPath": "components.minecraft:custom_data.legacy_data.level"
                  },
                  "experience": {
                    "type": "from_source",
                    "fromPath": "components.minecraft:custom_data.legacy_data.xp"
                  }
                }
              },
              "version": {
                "type": "number",
                "number": 2
              },
              "migrated_at": {
                "type": "number",
                "number": 1234567890
              }
            }
          }
        },
        {
          "type": "remove_custom_data_key",
          "path": "legacy_data"
        }
      ]
    }
  ]
}

What it does:

1. Detects version 1 legacy data
2. Uses embedded new item ID
3. Completely restructures data to version 2 format
4. Adds migration metadata
5. Removes old data

---

Multiple Item Types with Shared Logic

Converting different item types that share the same migration logic:

{
  "conversions": [
    {
      "id": "shared_plugin_migration",
      "priority": 120,
      "condition": {
        "type": "all",
        "all": [
          {
            "type": "any",
            "any": [
              {"type": "item_id", "itemId": "minecraft:diamond_sword"},
              {"type": "item_id", "itemId": "minecraft:diamond_axe"},
              {"type": "item_id", "itemId": "minecraft:diamond_pickaxe"},
              {"type": "item_id", "itemId": "minecraft:diamond_shovel"}
            ]
          },
          {
            "type": "component_exists",
            "path": "components.minecraft:custom_data.PublicBukkitValues.custom:tier"
          }
        ]
      },
      "operations": [
        {
          "type": "set_component",
          "component": "custom:tool_tier",
          "value": {
            "type": "from_source",
            "fromPath": "components.minecraft:custom_data.PublicBukkitValues.custom:tier"
          }
        },
        {
          "type": "set_component",
          "component": "custom:tool_enchanted",
          "value": {
            "type": "boolean",
            "boolean": true
          }
        },
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        }
      ]
    }
  ]
}

What it does:

1. Matches any diamond tool with custom tier data
2. Preserves tier information in new format
3. Marks as enchanted
4. Removes Bukkit data

---

Catch-All Fallback

A low-priority catch-all for any remaining unconverted items:

{
  "conversions": [
    {
      "id": "bukkit_data_cleanup",
      "priority": -100,
      "condition": {
        "type": "component_exists",
        "path": "components.minecraft:custom_data.PublicBukkitValues"
      },
      "operations": [
        {
          "type": "copy_component",
          "from": "components.minecraft:custom_data.PublicBukkitValues",
          "to": "components.custom:legacy_bukkit_data"
        },
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        },
        {
          "type": "set_component",
          "component": "custom:migration_status",
          "value": {
            "type": "string",
            "string": "unknown_type_preserved"
          }
        }
      ]
    }
  ]
}

What it does:

1. Runs at very low priority (after all specific conversions)
2. Catches any items still with Bukkit data
3. Preserves data in a new location for manual review
4. Marks with migration status

---

Complete Multi-File Setup

File: oraxen.json

{
  "conversions": [
    {
      "id": "oraxen_weapons",
      "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"
          }
        },
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        }
      ]
    }
  ]
}

File: itemsadder.json

{
  "conversions": [
    {
      "id": "itemsadder_items",
      "priority": 100,
      "condition": {
        "type": "component_exists",
        "path": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:id"
      },
      "operations": [
        {
          "type": "set_item_id_from_lookup",
          "source": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:id",
          "mapping": {
            "fire_staff": "custom:fire_staff"
          }
        },
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        }
      ]
    }
  ]
}

File: cleanup.json

{
  "conversions": [
    {
      "id": "final_cleanup",
      "priority": -100,
      "condition": {
        "type": "component_exists",
        "path": "components.minecraft:custom_data.PublicBukkitValues"
      },
      "operations": [
        {
          "type": "remove_component",
          "path": "components.minecraft:custom_data.PublicBukkitValues"
        }
      ]
    }
  ]
}

All these files would be placed in config/alchemy/transmutations/ and loaded automatically.

Testing Your Configurations

1. Start Small: Test with a few items first
2. Enable Logging: Set logConversions: true in config.json
3. Backup First: Always backup your world before running conversions
4. Monitor Logs: Watch server logs for conversion messages
5. Verify Results: Check converted items in-game

Next Steps

• Transmutation Builder - Build configurations visually
• Conditions Reference - All condition types
• Operations Reference - All operation types