Item variables and Item::use()

An Item variable asks the person using an action to choose an Item from their inventory. Item::use() belongs to the Item namespace because it performs a controlled operation on one of those selected Items.

Your Sugar code can then read information about the chosen Item. With Item::use(), it can also use part or all of a consumable Item after the person confirms.

Create an Item variable

Declare the Item variable:

var ingredient: Item with {
  input: true,
  required: true,
};

The variable now holds an object with properties about the chosen Item.

Read the Item’s information

Use a dot after the variable name:

ingredient.name
ingredient.blueprintId
ingredient.quantity
ingredient.totalUses
ingredient.quality
ingredient.persistent

For example, a Boop can keep the Item variable and the text that reads it together in Code:

var ingredient: Item with {
  input: true,
  required: true,
};

text "@1 selected {ingredient.name}. It has {ingredient.totalUses} uses available.";

The object reference lists every Item property.

Check the blueprint

When a recipe or key requires one specific kind of Item, compare its blueprintId.

Copy the blueprint ID from the Mint blueprint editor, then place quotation marks around it:

ingredient.blueprintId == "123456789012345678"

Item and blueprint IDs are text in Sugar. Always keep the quotation marks.

Use the selected Item

This asks to use one available use:

Item::use(ingredient);

Ask for two uses with a second argument:

let used = Item::use(ingredient, 2);

The function returns the number it can actually use. If only one use remains, asking for two returns 1.

Check before using it

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

  text if ingredient.blueprintId != "123456789012345678" {
    "That Item does not work for this recipe."
  } else if ingredient.totalUses < 2 {
    "This recipe needs 2 uses."
  } else {
    let used = Item::use(ingredient, 2);
    "@1 completes the recipe using {used} uses of {ingredient.name}."
  }
}

JOI shows a confirmation screen naming the Item and number of uses. If the person cancels, the action does not use the Item or send its result.

Items that cannot be used

Item::use() cannot use:

• The Item whose custom action is currently running
• An equipped Item
• A bodyswap Item
• An Item that contains inventory storage
• A persistent Item

Persistent Items return 0. JOI checks the inventory again after confirmation in case anything changed.