Show Statements

show adds media, chips, embeds, message components, or a toast beside the text produced by an Item action or Boop. Every show statement ends with a semicolon.

show is unavailable in predicate expressions, Embed Template bodies, and Automations.

show media

Show one resource from the effective Media Library:

show media &victory;

Choose randomly from a declared Media Pool:

show media from outcomes;

Choose randomly from an inline pool:

show media from (&victory, &celebration);

Each inline candidate may have its own condition:

show media from (
  &victory when score >= 10,
  &defeat when score < 10,
);

Choose randomly from every resource in the local Item or Boop Media Library:

show media;

Filter one selection with except. It accepts one resource or a parenthesized list:

show media from outcomes except &rare;
show media from outcomes except (&rare, &legendary);
show media from (&common, &rare) except &common;
show media except (&debug_image, &unused_result);

except is unavailable when showing one exact resource. It never mutates the declared pool or Media Library.

The last form does not include App resources. An exact resource or a declared pool may use resources from the linked App.

If several show media statements run, the last one determines the attachment. A selection with no eligible candidates adds no media.

mediaExists()

mediaExists(&resource)

Returns true when the Item, Boop, or linked App provides the resource.

if mediaExists(&special_result) {
  show media &special_result;
}

show variables

show variables;
show variables health, energy, $reputation;

With no references, adds every applicable variable as a message chip. Otherwise, adds only the selected variables. Repeated references are displayed once. Unknown names produce an error.

show chip

show chip text;
show chip text with icon => ℑ
show chip text with progress => health;
show chip text with progress => (health, maxHealth);
show chip chipName;
show chip chipName(arguments);

Adds a custom message chip. Chip text must be non-empty and may contain up to 80 characters. The optional icon must resolve to an image, not a video. A bare name uses a parameterless chip definition; call syntax supplies arguments to a parameterized chip. Otherwise the value remains an ordinary expression. One program can add up to 20 custom chips.

progress renders JOI’s progress bar below the chip. A single number uses 100 as its maximum; (value, maximum) sets both values.

show embed

show embed templateName;
show embed templateName(arguments);

Use the embed name directly when no arguments are passed. Use call syntax when supplying arguments:

show embed summary;
show embed stats(health, level);

Arguments are evaluated once and bound to the template’s parameters from left to right. Arguments for required parameters must be supplied. Parameters with defaults may be omitted from the call.

Call-time options can replace part of the result:

show embed stats(health, level) with {
  description: "Bonus round",
  addFields: (
    { title: "Bonus", text: bonus, icon: &bonus_icon },
  ),
};

Allowed embed properties are title, description, banner, thumbnail, footer, and fields. Call-time options also allow addFields. fields replaces saved fields; addFields appends.

One action can show up to 3 embeds. Each embed can have up to 10 fields.

show button and show select

Chat messages can carry components bound to an interaction declaration:

show button confirm() -> "Confirm";
show button cancel(orderId) -> "Cancel" with variant => ButtonStyle::Outline, maxUses => 1;
show select chooseMode() -> "Choose a mode" with choices => ("Calm", "Bold", "Chaotic");

Arguments before -> are captured when the message is created. A select appends its selected choice value as the interaction’s final argument. maxUses accepts a positive whole number or None; its default is None, so the component can be used repeatedly until it expires. One message can contain up to five components.

Standalone components expire after one hour. Components created during a Session live with that Session. ACTOR always represents the JOI using the component, and Sugar checks the interaction’s current condition before applying a successful use.

show toast

show toast "Saved for your next turn";

Shows a private toast to the JOI who ran the code. A toast does not add content to the message. Item actions and Boops must still produce Sugar text, while an interaction may produce only a toast. Sandbox Mode previews the toast without sending anything.

Postfix when

Every output kind accepts a condition at the end of the statement:

show media from outcomes when score >= 10;
show media from outcomes except &rare when score < 10;
show variables score when debug;
show chip "Rare result" with icon => &sparkles when rare;
show embed victory when won;

Sugar evaluates the condition first. When it returns false, the output value, arguments, and with options are not evaluated.

Inline with

When a with configuration fits comfortably on one line, pair names and values with the mapping arrow => and separate several entries with commas:

show chip "Rare result" with icon => &sparkles;
show embed stats(health, level) with footer => "Updated now", description => summary;

The final entry is not followed by a comma. This mapping-arrow form belongs to with; object literals continue to use braces and colons.

Saved output

JOI stores media, chips, and embeds as they appeared when the result was created. Later changes to variables, templates, or Media Libraries do not rewrite old messages.