Conditions Reference

Conditions Reference

Conditions determine when a transmutation rule should be applied to an item. This page documents all available condition types.

Condition Structure

All conditions have a type field that determines their behavior:

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

Condition Types

always

Always matches, regardless of item data. Useful for catch-all rules.

Fields:

• None

Example:

{
  "type": "always"
}

Use Case: Fallback rules that should apply to all items that weren’t caught by higher-priority rules.

---

component_exists

Checks if a component or NBT path exists on the item.

Fields:

Field	Type	Required	Description
path	String	Yes	Dot-notation path to check

Example:

{
  "type": "component_exists",
  "path": "components.minecraft:custom_data.PublicBukkitValues.oraxen:id"
}

Use Case: Detecting items from specific plugins or systems that add marker data.

---

component_equals

Checks if a component value equals a specific value.

Fields:

Field	Type	Required	Description
path	String	Yes	Dot-notation path to check
value	Any	Yes	Expected value (string, number, boolean, or null)

Example:

{
  "type": "component_equals",
  "path": "components.minecraft:custom_data.item_type",
  "value": "weapon"
}

Supported Value Types:

• Strings: "sword", "magic_wand"
• Numbers: 42, 3.14
• Booleans: true, false
• Null: null

Use Case: Matching specific item types or categories.

---

item_id

Matches items with a specific item ID.

Fields:

Field	Type	Required	Description
itemId	String	Yes	Item ID to match (e.g., minecraft:diamond_sword)

Example:

{
  "type": "item_id",
  "itemId": "minecraft:diamond_sword"
}

Use Case: Applying conversions only to specific vanilla or modded item types.

---

any

Matches if ANY of the sub-conditions match (logical OR).

Fields:

Field	Type	Required	Description
any	Array	Yes	Array of condition objects

Example:

{
  "type": "any",
  "any": [
    {
      "type": "item_id",
      "itemId": "minecraft:diamond_sword"
    },
    {
      "type": "item_id",
      "itemId": "minecraft:netherite_sword"
    }
  ]
}

Use Case: Matching multiple item types or multiple possible data structures.

---

all

Matches if ALL of the sub-conditions match (logical AND).

Fields:

Field	Type	Required	Description
all	Array	Yes	Array of condition objects

Example:

{
  "type": "all",
  "all": [
    {
      "type": "item_id",
      "itemId": "minecraft:diamond_sword"
    },
    {
      "type": "component_exists",
      "path": "components.minecraft:custom_data.enchanted"
    },
    {
      "type": "component_equals",
      "path": "components.minecraft:custom_data.tier",
      "value": "legendary"
    }
  ]
}

Use Case: Matching items that meet multiple criteria simultaneously.

---

Complex Condition Examples

Nested Logical Conditions

You can nest any and all conditions for complex logic:

{
  "type": "all",
  "all": [
    {
      "type": "component_exists",
      "path": "components.minecraft:custom_data.legacy_data"
    },
    {
      "type": "any",
      "any": [
        {
          "type": "component_equals",
          "path": "components.minecraft:custom_data.legacy_data.version",
          "value": 1
        },
        {
          "type": "component_equals",
          "path": "components.minecraft:custom_data.legacy_data.version",
          "value": 2
        }
      ]
    }
  ]
}

Logic: Item has legacy_data AND (version == 1 OR version == 2)

Multiple Item Types with Shared Data

{
  "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": "component_exists",
      "path": "components.minecraft:custom_data.PublicBukkitValues"
    }
  ]
}

Logic: Item is a diamond tool AND has Bukkit data

Detecting Specific Plugin Items

{
  "type": "all",
  "all": [
    {
      "type": "component_exists",
      "path": "components.minecraft:custom_data.PublicBukkitValues.oraxen:id"
    },
    {
      "type": "component_equals",
      "path": "components.minecraft:custom_data.PublicBukkitValues.oraxen:id",
      "value": "ruby_sword"
    }
  ]
}

Logic: Item has Oraxen ID AND the ID equals “ruby_sword”

Path Syntax

Paths use dot-notation to navigate nested structures:

id                                  # Root item ID
components                          # Components container
components.minecraft:custom_data    # Custom data component
components.minecraft:custom_data.my_key.nested    # Nested keys
components.custom:namespace         # Custom namespace

Important:

• Always include namespace prefixes (e.g., minecraft:custom_data)
• Paths are case-sensitive
• Non-existent paths return null (use component_exists to check)

Best Practices

1. Start Specific, Then Broaden

// Check if path exists before checking its value
{
  "type": "all",
  "all": [
    {"type": "component_exists", "path": "components.minecraft:custom_data.type"},
    {"type": "component_equals", "path": "components.minecraft:custom_data.type", "value": "weapon"}
  ]
}

2. Use any for Variants

// Multiple item types that should be converted the same way
{
  "type": "any",
  "any": [
    {"type": "item_id", "itemId": "minecraft:iron_sword"},
    {"type": "item_id", "itemId": "minecraft:iron_axe"}
  ]
}

3. Avoid Overly Broad Conditions

// Bad: Matches too many items
{
  "type": "component_exists",
  "path": "components.minecraft:custom_data"
}

// Good: Specific marker
{
  "type": "component_exists",
  "path": "components.minecraft:custom_data.oraxen_marker"
}

4. Test Your Conditions

Enable logConversions in the config to verify your conditions are matching the intended items:

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

Next Steps

• Operations Reference - Learn about available operations
• Example Configurations - See real-world examples
• Transmutation Builder - Build rules visually