Operations Reference

Operations define the transformations that are applied to an item when a rule’s condition matches. Operations are executed in sequence, with each operation receiving the output of the previous operation.

Operation Structure

All operations have a type field that determines their behavior:

{
  "type": "operation_type_name",
  // ... additional fields depending on type
}

Item ID Operations

`set_item_id`

Directly sets the item ID to a specific value.

Fields:

Field	Type	Required	Description
`itemId`	String	Yes	New item ID (e.g., `minecraft:diamond_sword`)

Example:

{
  "type": "set_item_id",
  "itemId": "custom:ruby_sword"
}

Use Case: Simple direct conversions where you know the exact target item ID.

`set_item_id_from_lookup`

Sets the item ID by looking up a value from the item’s data in a mapping table.

Fields:

Field	Type	Required	Description
`source`	String	Yes	Path to read the lookup key from
`mapping`	Object	Yes	Map of source values to target item IDs
`defaultValue`	String	No	Fallback item ID if source value not in mapping

Example:

{
  "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"
  },
  "defaultValue": "minecraft:stick"
}

Use Case: Converting plugin items where the old ID is stored in NBT data.

`set_item_id_from_component`

Sets the item ID directly from a component value.

Fields:

Field	Type	Required	Description
`source`	String	Yes	Path to read the new item ID from

Example:

{
  "type": "set_item_id_from_component",
  "source": "components.minecraft:custom_data.new_item_id"
}

Use Case: When the target item ID is already stored in the item’s data.

Component Modification Operations

`add_component`

Adds a new component to the item. Fails if the component already exists.

Fields:

Field	Type	Required	Description
`component`	String	Yes	Component path to add
`value`	ComponentValue	Yes	Value to set (see ComponentValue types below)

Example:

{
  "type": "add_component",
  "component": "custom:magic_data",
  "value": {
    "type": "map",
    "map": {
      "power": {"type": "number", "number": 10},
      "element": {"type": "string", "string": "fire"}
    }
  }
}

Use Case: Adding new data structures to items.

`set_component`

Sets a component value, creating it if it doesn’t exist or replacing it if it does.

Fields:

Field	Type	Required	Description
`component`	String	Yes	Component path to set
`value`	ComponentValue	Yes	Value to set (see ComponentValue types below)

Example:

{
  "type": "set_component",
  "component": "minecraft:custom_name",
  "value": {
    "type": "string",
    "string": "{\"text\":\"Legendary Sword\",\"color\":\"gold\"}"
  }
}

Use Case: Setting or updating component values.

`remove_component`

Removes a component or NBT path from the item.

Fields:

Field	Type	Required	Description
`path`	String	Yes	Path to remove

Example:

{
  "type": "remove_component",
  "path": "components.minecraft:custom_data.PublicBukkitValues"
}

Use Case: Cleaning up old data after migration.

`remove_custom_data_key`

Shorthand for removing a key from minecraft:custom_data.

Fields:

Field	Type	Required	Description
`path`	String	Yes	Key within custom_data to remove

Example:

{
  "type": "remove_custom_data_key",
  "path": "legacy_item"
}

Equivalent to:

{
  "type": "remove_component",
  "path": "components.minecraft:custom_data.legacy_item"
}

Use Case: Convenient cleanup of custom data keys.

`copy_component`

Copies data from one path to another.

Fields:

Field	Type	Required	Description
`from`	String	Yes	Source path to copy from
`to`	String	Yes	Destination path to copy to

Example:

{
  "type": "copy_component",
  "from": "components.minecraft:custom_data.old_location",
  "to": "components.custom:new_location"
}

Use Case: Restructuring data without losing information.

ComponentValue Types

When using add_component or set_component, you must specify a ComponentValue object that describes the value to set.

String Value

{
  "type": "string",
  "string": "text value here"
}

Number Value

{
  "type": "number",
  "number": 42
}

Supports integers, longs, floats, and doubles.

Boolean Value

{
  "type": "boolean",
  "boolean": true
}

List Value

{
  "type": "list",
  "list": [
    {"type": "string", "string": "item1"},
    {"type": "string", "string": "item2"},
    {"type": "number", "number": 3}
  ]
}

Map Value

{
  "type": "map",
  "map": {
    "name": {"type": "string", "string": "Ruby Sword"},
    "tier": {"type": "number", "number": 3},
    "enchanted": {"type": "boolean", "boolean": true}
  }
}

From Source Value

Copies a value from the original item data:

{
  "type": "from_source",
  "fromPath": "components.minecraft:custom_data.old_power_level"
}

Use Case: Preserving data during restructuring.

Complex Operation Examples

Complete Item Restructuring

{
  "operations": [
    {
      "type": "set_item_id_from_lookup",
      "source": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:id",
      "mapping": {
        "magic_wand_tier1": "custom:wand_novice",
        "magic_wand_tier2": "custom:wand_adept",
        "magic_wand_tier3": "custom:wand_master"
      }
    },
    {
      "type": "set_component",
      "component": "custom:magic_properties",
      "value": {
        "type": "map",
        "map": {
          "mana": {
            "type": "from_source",
            "fromPath": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:mana"
          },
          "spell_slots": {
            "type": "from_source",
            "fromPath": "components.minecraft:custom_data.PublicBukkitValues.itemsadder:slots"
          },
          "migrated": {
            "type": "boolean",
            "boolean": true
          },
          "migration_version": {
            "type": "number",
            "number": 2
          }
        }
      }
    },
    {
      "type": "remove_component",
      "path": "components.minecraft:custom_data.PublicBukkitValues"
    }
  ]
}

Conditional Data Migration

{
  "operations": [
    {
      "type": "copy_component",
      "from": "components.minecraft:custom_data.legacy.player_uuid",
      "to": "components.custom:owner_data.uuid"
    },
    {
      "type": "copy_component",
      "from": "components.minecraft:custom_data.legacy.player_name",
      "to": "components.custom:owner_data.name"
    },
    {
      "type": "set_component",
      "component": "custom:owner_data.bound_at",
      "value": {
        "type": "number",
        "number": 1234567890
      }
    },
    {
      "type": "remove_custom_data_key",
      "path": "legacy"
    }
  ]
}

Armor Conversion

{
  "operations": [
    {
      "type": "set_item_id_from_lookup",
      "source": "components.minecraft:custom_data.armor_set",
      "mapping": {
        "ruby_helmet": "custom:armor/ruby_helmet",
        "ruby_chestplate": "custom:armor/ruby_chestplate",
        "ruby_leggings": "custom:armor/ruby_leggings",
        "ruby_boots": "custom:armor/ruby_boots"
      }
    },
    {
      "type": "set_component",
      "component": "custom:armor_stats",
      "value": {
        "type": "map",
        "map": {
          "defense": {
            "type": "from_source",
            "fromPath": "components.minecraft:custom_data.stats.defense"
          },
          "toughness": {
            "type": "from_source",
            "fromPath": "components.minecraft:custom_data.stats.toughness"
          },
          "set_bonus": {
            "type": "string",
            "string": "ruby_power"
          }
        }
      }
    },
    {
      "type": "remove_custom_data_key",
      "path": "armor_set"
    },
    {
      "type": "remove_custom_data_key",
      "path": "stats"
    }
  ]
}

Operation Sequencing

Operations are applied in the order they appear in the array. This is important when operations depend on previous operations:

{
  "operations": [
    // Step 1: Copy data to new location
    {
      "type": "copy_component",
      "from": "components.minecraft:custom_data.old_data",
      "to": "components.custom:new_data"
    },
    // Step 2: Transform the item ID based on old data
    {
      "type": "set_item_id_from_lookup",
      "source": "components.minecraft:custom_data.old_data.type",
      "mapping": { /* ... */ }
    },
    // Step 3: Clean up old data (must be after copy!)
    {
      "type": "remove_custom_data_key",
      "path": "old_data"
    }
  ]
}

Best Practices

1. Always Clean Up

Remove old data after conversion to prevent re-processing:

{
  "operations": [
    {"type": "set_item_id", "itemId": "new:item"},
    {"type": "remove_component", "path": "old_marker"}  // Important!
  ]
}

2. Use from_source for Data Preservation

When restructuring, preserve original data:

{
  "type": "set_component",
  "component": "custom:new_location",
  "value": {
    "type": "map",
    "map": {
      "value": {
        "type": "from_source",
        "fromPath": "components.minecraft:custom_data.old_location"
      }
    }
  }
}

3. Provide Defaults for Lookups

Always include defaultValue in lookups to handle unexpected data:

{
  "type": "set_item_id_from_lookup",
  "source": "components.minecraft:custom_data.type",
  "mapping": { /* ... */ },
  "defaultValue": "minecraft:stick"  // Fallback
}

4. Test Operation Sequences

Enable logConversions to verify operations are applied correctly:

{
  "enableTransmutation": true,
  "logConversions": true,
  "debugMode": true
}

Next Steps

Conditions Reference - Learn about available conditions
Example Configurations - See real-world examples
Transmutation Builder - Build rules visually