An Item variable asks the person using an action to choose an Item from their inventory. After they choose one, the variable refers to that Item. Sugar can then read its information and variables, change its Memory variables, or pass it to Item::use().
Create an Item variable
This input asks the person to choose one Item:
var ingredient: Item = None with {
input: true,
required: true,
};
None means the input begins without a selected Item. The chosen Item is stored in ingredient when the action runs.
Read information about the selected Item
The selected Item’s built-in information is available under meta. For example, use ingredient.meta.name to read the name shown by JOI:
text "@1 selected {ingredient.meta.name}.";
Other available properties include:
ingredient.meta.blueprintId
ingredient.meta.quantity
ingredient.meta.totalUses
ingredient.meta.quality
ingredient.meta.persistent
These properties can be read but not assigned. The object reference lists all of them.
Read variables from the selected Item
An Item can declare its own variables in Sugar. Suppose a plant Item has this Code:
mem var health = 100;
var species = "FERN";
Now suppose an action or Boop has an Item input named plant. After the person selects that plant, the code can read both variables by name:
var plant -> "Plant": Item = None with {
input: true,
required: true,
};
text "{plant.meta.name} is a {plant.species} with {plant.health} health.";
Write the Item variable first, followed by ., followed by the variable declared in the selected Item. The selected Item must declare that variable: plant.health only works when the chosen Item has a top-level variable named health.
Variables supplied by the selected Item’s linked App keep their $ prefix:
plant.$hydration
Change a Memory variable on the selected Item
Because the plant declared health with mem var, other Sugar code can assign a new value to it:
action healPlant -> "Heal plant" {
var plant -> "Plant": Item = None with {
input: true,
required: true,
};
plant.health = clamp(plant.health + 10, 0, 100);
text "{plant.meta.name} now has {plant.health} health.";
}
Assignment shortcuts work too:
plant.health -= 10;
If a selected Item has a Memory variable containing a list, its mutating list methods can also change that list.
Only Memory variables can be changed this way. Regular var variables, calculated constants, and properties under meta can be read but not assigned. Sugar also does not allow replacing the selected Item itself with plant = anotherItem;.
JOI saves changes to the selected Item’s Memory variables only when the action completes successfully. If the action fails or is canceled, those changes are not saved.
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.meta.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 = None with {
input: true,
required: true,
};
text if ingredient.meta.blueprintId != "123456789012345678" {
"That Item does not work for this recipe."
} else if ingredient.meta.totalUses < 2 {
"This recipe needs 2 uses."
} else {
let used = Item::use(ingredient, 2);
"@1 completes the recipe using {used} uses of {ingredient.meta.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.