Show statements

A text declaration provides the message created by an Item action or Boop. The show statement adds other visible results beside that text.

Show a chip

Choose the kind of result immediately after show, then provide its value:

show chip "Critical hit";

The statement ends with a semicolon because it is an instruction. It does not replace the message from text.

Configure a shown result

with adds options to the result. A chip can use an image from the Media Library as its icon:

show chip "Critical hit" with icon => &sparkle;

The compact mapping form keeps a short configuration on one line. Use a block when several options read better vertically:

show chip "Critical hit" with {
  icon: &sparkle,
};

Both forms configure the same icon.

Declare a reusable chip

Give a chip a name when its text or icon belongs to the creation rather than one particular instruction:

chip healthStatus {
  config icon => &heart;
  format("Health: {health}")
}

The declaration creates no output by itself. Show it by name wherever that declaration is available:

show chip healthStatus;

A top-level chip is available throughout the Item or Boop. A chip declared inside an Item action belongs to that action.

On an Item, highlighted: true keeps a named chip visible in the Item dialog without running an action:

chip healthStatus {
  config icon => &heart, highlighted => true;
  format("Health: {health}")
}

Highlighted chips read the Item’s saved state. An Item may have up to eight across its top level and all of its actions.

A chip can also render a progress bar. A single value uses 100 as its maximum; a pair supplies another maximum:

chip focus {
  config progress => (focus, maxFocus), highlighted => true;
  format("Focus: {focus}/{maxFocus}")
}

Chips may accept parameters and are called with the same syntax as functions:

chip score(value: number) {
  format("Score: {value}")
}

show chip score(80);

Show variable chips

Write variable references directly after show variables:

show variables health, energy, level;

App variables keep their $:

show variables health, $reputation;

With no references, the statement shows every variable available for display:

show variables;

show variables adds variable chips to the result created by this particular use. Use a highlighted named chip when a customized value should remain visible on the Item itself.

Show named media

show media &victory;

This adds the victory image or video from the creation’s Media Library. Media Libraries and Pools covers declared pools, inline pools, and random selection from the whole library.

Show a result conditionally

Place when at the end of any show statement:

show chip "Critical hit" when roll == 20;
show variables score when debug;
show media &victory when score >= 100;

The result is added only when its condition returns true.

Put several results together

Add an image named star and an image or video named victory, then place this module in Code:

var score = 0;

action rollForPoints -> "Roll for points" {
  let roll = Rand::roll("1d20");
  score += roll;
  show chip format("+{} points", roll) with icon => ☆
  show variables score;
  show media &victory;

  text "@1's total is now {score}.";
}

Sugar runs the instructions from top to bottom. JOI combines the dice result, chip, variable chip, media, and message into one result.

Show a private toast

show toast "Your preference was saved";

A toast appears only to the person running the action and is not placed in the message. An action still needs an eligible Sugar text. Sandbox Mode previews the toast without sending it.

The next lesson introduces Media Libraries and Pools, including random and conditional media selection.