Consume Items in a recipe

An Item variable can turn a custom action into a recipe, key check, ticket gate, or power-up system.

This example requires two uses from a specific ingredient.

1. Copy the ingredient blueprint ID

Open the ingredient in the Mint blueprint editor and use Copy Blueprint ID. IDs must be written as text in Sugar.

"123456789012345678"

2. Add the Item variable

The action needs an ingredient Item variable with input: true and required: true. Keep it inside the action because no other action needs this input. The complete declaration appears in step 4.

3. Check the selection

ingredient.blueprintId == "123456789012345678"

The selected Item object cannot be changed directly. JOI checks that the selected Item still exists in the person’s inventory when the action runs.

4. Write the complete action

Put this complete declaration in the Item’s Code module. Its variable, checks, Item use, and result text all stay inside the action:

action craft -> "Craft recipe" {
  var ingredient: Item with {
    input: true,
    required: true,
  };

  text if ingredient.blueprintId != "123456789012345678" {
    "That Item cannot be used in this recipe."
  } else if ingredient.totalUses < 2 {
    "This recipe needs 2 uses, but {ingredient.name} only has {ingredient.totalUses}."
  } else {
    let used = Item::use(ingredient, 2);
    show chip "Ingredient used";
    "@1 completes the recipe using {used} uses of {ingredient.name}."
  }
}

Checking totalUses lets you choose your own insufficient-item message. This is a useful reason to keep branch-specific code inside text if: Item::use() only runs in the successful branch. Even without the check, Item::use() clamps the request to what remains and returns the actual amount.

5. Understand approval

The action does not use the Item immediately. JOI first shows the person a confirmation screen.

If they cancel, Sugar does not use the ingredient, save changes to Memory variables, spend Lore, or send the result.

After approval, JOI checks the inventory again. If the Item changed while the drawer was open, the action stops safely and asks the user to try again.

Restrictions

Item::use() cannot consume:

• The Item running the custom action
• Equipped Items
• Bodyswap Items
• Items containing inventory storage
• Persistent Items

Sandbox Mode shows the planned Item use without touching the real inventory.