ReferenceReference

Item functions

Reference HOST Item information, Item changes, blueprint transformation, and inventory Item use.

The Item namespace changes the Item hosting an action or Host Automation. Item::use() instead works with another Item selected through an Item variable. Read the current Item through the HOST constant.

reset()

reset(variable)

Restores a Memory variable to its configured default.

reset(charges);
reset($playerStreak);

Pass the variable itself, not its name as text. The program must be allowed to change that variable. Constants cannot be reset.

Current Item properties

HOST.kind
HOST.name
HOST.description
HOST.image
HOST.quality

HOST.name is the current Item’s visible name. A custom name given to that copy takes priority over its original name. The remaining properties return its kind ("ITEM"), description, current image, and quality.

Item::setImage()

Item::setImage(&resource)
Item::setImage(joi.image)

Changes the current non-stackable Item to an image from its effective Media Library.

Item::setImage(&stage_2);

The argument must be an image Media value. It may come from a named resource, a Media variable, or a JOI profile image such as ACTOR.image. Interactive results show the previous Item frame beside the new image. Host Automations may use this function when the current host is an Item.

Item::setQuality()

Item::setQuality(quality)

Allowed values are BASIC, ENHANCED, PREMIUM, ELITE, and ICONIC.

The function returns the new quality. An upgrade costs the difference between the current and new quality’s mint costs. A downgrade is free.

Quality may change at most once per action. A paid change requires approval. Quality setting is unavailable in Automations.

Item::mutate()

Item::mutate(blueprintId)

Transforms the current Item into an eligible non-stackable blueprint from the same creator.

The blueprint ID must be text:

Item::mutate("123456789012345678");

Mutation costs 75 percent of the destination blueprint’s mint cost, rounded up. It may happen once per action and requires approval.

One action cannot combine mutation with Item::setQuality(newQuality). Mutation is unavailable in Automations.

Item::use()

Item::use(item)
Item::use(item, uses)

Requests use of an Item supplied through a selected Item variable. It defaults to one use and returns the number that will actually be consumed.

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

Requests larger than the available totalUses are clamped to what remains. Persistent Items return 0.

The function cannot consume:

  • The Item running the custom action
  • An Item not supplied through a selected Item variable
  • An equipped Item
  • A bodyswap Item
  • An Item with inventory storage
  • A persistent Item

JOI asks the person to confirm the Item use and checks the inventory again before applying it. Item::use() is unavailable in Automations and conditions.