Embed Templates

An Embed Template is a named card that an Item action or Boop can add to its result. An embed may contain a title, description, banner, thumbnail, footer, and up to 10 fields.

Embed declarations live in the same source as the code that uses them. Put an Item or Boop embed in its Code module. Put an App embed in Main.

Declare and show an embed

This complete Boop keeps its variable, embed, and text together:

var score = 0;

embed challengeResult -> "Challenge result" {
  description: format("@1 scored {score} points."),
  fields: (
    score -> "Score",
  ),
}

text {
  show embed challengeResult;
  "@1 checks the challenge result."
}

challengeResult is the embed’s Sugar name. The display arrow -> supplies its title. Because this embed has no arguments, show embed uses its name directly. Parentheses belong to embeds that receive arguments.

The title is optional. Sugar does not turn the declaration name into display text:

embed quietResult {
  description: "Nothing disturbed the room.",
}

quietResult remains the name used by Sugar, but the rendered embed has no title.

The property names determine where the remaining values appear. Their expressions are evaluated when the embed is shown.

Add images and fields

banner and thumbnail use image resources from the effective Media Library:

embed amuletStatus -> "Amulet status" {
  thumbnail: &amulet,
  description: "The amulet hums softly.",
  fields: (
    charges -> "Charges" with icon => &charge,
    format("{}%", corruption) -> "Corruption" with {
      icon: &warning,
      progress: corruption,
    },
  ),
}

A field places its value on the left of -> and its displayed label on the right. An optional with adds its icon from the effective Media Library. Use the inline => form for one line or a {} block when the declaration reads better across several lines. Field icons must be images; videos are not accepted.

progress renders JOI’s progress bar beneath the field. One number uses 100 as its maximum. Pass (value, maximum) when the scale is different:

energy -> "Energy" with progress => (energy, maxEnergy),

Fields appear in source order. Write an empty list as ().

Pass values to an embed

Parameters let the same template present different values without reading fixed variable names:

embed duelResult(score, opponent, note = "No special effect") -> "Duel result" {
  description: format("Against {opponent}"),
  fields: (
    score -> "Score",
    note -> "Note",
  ),
}

Pass the arguments when the result is shown:

show embed duelResult(points, rivalName, "Perfect defense");

Required parameters come first. A parameter with = supplies a default when its argument is omitted. An embed may have up to 20 parameters.

Show an embed conditionally

Add when before the body when the entire embed should only appear sometimes. It follows the title when one is present:

embed secretResult(code) -> "Secret result" when unlocked {
  fields: (
    code -> "Code",
  ),
}

When unlocked is false, show embed secretResult(secretCode); adds no embed.

Highlight an Item embed

An Item can keep an embed visible in its dialog by highlighting the declaration:

embed status {
  fields: (
    format("{health} / 100") -> "Health" with icon => &heart, progress => health,
    format("{energy} / 100") -> "Energy" with icon => &energy, progress => energy,
  ),
  highlighted: true,
}

JOI evaluates it from the Item’s saved state without running an action. An Item may have up to two highlighted embeds. A highlighted embed with parameters must provide a default for every inherited and own parameter, because the Item dialog does not supply call arguments.

Configure one call

with changes only the result produced by one call:

show embed challengeResult with footer => "Double points round";

Use a block for several options:

show embed challengeResult with {
  description: "Double points round",
  addFields: (
    { title: "Bonus", text: bonus },
  ),
};

fields replaces the template’s field list. addFields appends to it. The saved declaration is unchanged.

Extend an App embed

An App can provide a base embed to every linked Item and Boop. In App Main:

embed encounterStatus(health, danger) -> "Encounter status" {
  fields: (
    health -> "Health",
    danger -> "Danger",
  ),
}

A linked creation can extend that App embed in Code:

embed detailedStatus(note) extends encounterStatus {
  thumbnail: &encounter_art,
  addFields: (
    note -> "Current effect" with icon => &effect,
  ),
}

extends names the App embed but does not call it. The child automatically inherits health and danger, then adds its own note parameter. Supply the complete effective argument list only when showing it:

show embed detailedStatus(health, danger, "The bridge is collapsing");

Inherited arguments always come first. If the App embed ends with optional parameters, parameters added by the child must also have defaults.

The child inherits the base title unless it declares another with ->. Scalar properties such as description, thumbnail, and footer replace inherited values. fields replaces all inherited fields, while addFields appends. A child’s when condition must pass in addition to the base condition.