Make an Item evolve

Sugar offers three different ways for an Item to change. Choose the smallest one that matches your idea.

Change only the image

Use Item::setImage() when the Item keeps the same blueprint and quality but needs a new appearance.

action gainExperience -> "Gain experience" {
  var gainedExperience -> "Experience gained" = 10 with {
    input: true,
    required: true,
    min: 1,
    max: 100,
  };

  experience += gainedExperience;

  if experience >= 100 {
    Item::setImage(&stage_3);
  } else if experience >= 50 {
    Item::setImage(&stage_2);
  } else {
    Item::setImage(&stage_1);
  }

  text "@1 gained {gainedExperience} experience.";
}

Image changes are free and do not require a payment approval by themselves.

Change quality

Item::setQuality("PREMIUM");

Quality upgrades cost the positive difference between the current and target mint costs. Downgrades are free.

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

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

  text "Quality: {before} to {after}";
}

Transform into another blueprint

Use Item::mutate() when the result should become a genuinely different Item blueprint.

Copy the destination blueprint ID from the Mint blueprint editor:

Item::mutate("123456789012345678");

The destination must be an eligible non-stackable blueprint from the same creator. The mutation costs 75 percent of its mint cost, rounded up.

An action may mutate only once.

Do not combine quality and mutation

One action cannot call Item::setQuality(newQuality) and Item::mutate(). Choose which transformation the action performs.

You may still combine a mutation with variable changes. If the user cancels the confirmation, none of the action is applied.

Which one should you use?

Use Sandbox Mode to preview the old and new Item presentation before trying the real action.