Change the current Item

An Item custom action can read or change the Item that is running it. Read that current Item through the HOST value. Controlled changes are grouped in the Item namespace, so they use names such as Item::setImage().

This is different from an Item variable. An Item variable asks someone to choose another Item from their inventory. The functions on this page work with the current Item itself.

Read the current Item

HOST is a constant supplied by JOI, not a namespace. It represents the Item or Boop hosting the current Sugar code, and its information is read with property access (.).

HOST.name
HOST.description
HOST.quality

HOST.name returns the Item’s visible name. If its owner renamed that copy, the custom name is returned.

HOST.description returns its description.

HOST.quality returns "BASIC", "ENHANCED", "PREMIUM", "ELITE", or "ICONIC".

These forms only read information. They do not change anything.

Change the image

Add named images to the Item’s Media Library, then change the image from an action in the Item’s Code module:

action emptyAmulet -> "Empty amulet" {
  Item::setImage(&amulet_empty);
  text "@1 empties {HOST.name}.";
}

This changes the image of that non-stackable Item. It does not change every copy of the blueprint.

The media name must exist and must belong to an image, not a video.

Change the quality

Pass a quality to Item::setQuality() inside an Item action:

action upgrade -> "Upgrade quality" {
  Item::setQuality("PREMIUM");
  text "@1 upgrades {HOST.name}.";
}

Moving to a higher quality costs the difference between the Item’s current mint cost and the new quality’s mint cost. Moving to a lower quality is free.

JOI shows a confirmation screen when the change costs Lore. One action may change quality only once.

The function gives back the new quality, so you can use it in the message:

action upgrade -> "Upgrade quality" {
  let before = HOST.quality;
  let after = Item::setQuality("PREMIUM");

  text "{HOST.name} changed from {before} to {after}.";
}

Transform into another blueprint

Use Item::mutate() when the Item should become a different Item. This is also a complete action in the Item’s Code module:

action transform -> "Transform Item" {
  Item::mutate("123456789012345678");
  text "@1 transforms {HOST.name}.";
}

Copy the destination blueprint ID from the Mint blueprint editor and keep it inside quotation marks.

The destination must be an eligible non-stackable blueprint created by the same person. The transformation costs 75 percent of the destination Item’s mint cost, rounded up.

One action may transform the Item only once.

Choose quality or transformation

The same action cannot change quality and transform the Item. Choose one of them.

If the person cancels JOI’s confirmation screen, the Item, its Memory variables, any Lore payments, and the outgoing message remain unchanged.

Stackable Items cannot use Item::setImage() or Item-level Memory variables because JOI needs to know which individual copy should change.