Components and interactions

A Sugar action normally ends after it sends its message. A component gives that message something a person can use later. Sugar currently provides buttons and selects.

An interaction is the named code that responds to a component. Declaring an interaction does not display anything by itself; an action connects it to a component with show.

Declare an interaction

Imagine an Item action that discovers a key. The person may keep it directly from the resulting message. In App Main, declare the hosted state and the interaction that will save the key:

host mem var $savedKeys = 0;

interaction keepKey(owner: Joi) when ACTOR.id == owner.id {
  $savedKeys += 1;
  show toast "Key saved";
  "{ACTOR.name} slips the key into their pocket."
}

keepKey is the interaction’s name. owner is a parameter containing the Joi passed to it. The code between the braces runs when the connected component is used.

The final expression becomes a new Sugar message. An interaction may instead show only a toast when no new message is needed.

Attach it to a button

Inside the action that finds the key:

show button keepKey(ACTOR) -> "Keep the key" with maxUses => 1;
text "{ACTOR.name} finds a silver key beneath the floorboards.";

This line has three parts:

• show button adds a button to the action’s message.
• keepKey(ACTOR) chooses the interaction and passes the current acting JOI as owner.
• -> "Keep the key" sets the button label.

The value passed to keepKey() is captured with that particular message. When another JOI presses the button, ACTOR represents that new person while owner still represents the person who originally found the key.

Decide who may use it

The declaration’s when condition controls whether the interaction may run:

when ACTOR.id == owner.id

In this example, only the JOI who found the key can keep it. If someone else presses the button, nothing changes and JOI explains that the interaction is unavailable.

You can write any Sugar condition here. For more involved behavior, omit when, inspect ACTOR inside the interaction, and use a toast to explain why a choice did not work.

ACTOR is always the JOI currently using the component. JOIS is the list of JOIs available to that interaction. Its exact Sugar type is List<Joi>—a list whose entries are Joi values.

Limit successful uses

maxUses counts successful uses of one displayed component:

show button keepKey(ACTOR) -> "Keep the key" with maxUses => 1;

After the first successful use, the button becomes disabled. Leave out maxUses, or set it to None, to allow any number of uses until the component expires.

A component remains available for one hour. The Sessions lesson later explains how components can continue a shared experience.

Button styles are optional:

show button keepKey(ACTOR) -> "Keep the key" with variant => ButtonStyle::Outline, maxUses => 1;

Available styles are ButtonStyle::Default, ButtonStyle::Outline, and ButtonStyle::Ghost.

Add a select

A select presents several values. The chosen value is appended to the interaction’s arguments:

interaction chooseDoor(owner: Joi, door: str) when ACTOR.id == owner.id {
  show toast format("{} door selected", door);
  "{ACTOR.name} opens the {door} door."
}

show select chooseDoor(ACTOR) -> "Choose a door" with {
  choices: ("North", "East", "Below"),
  maxUses: 1,
};

The action supplies owner. The select supplies door, so their order matches chooseDoor(owner, door).

Select choices may contain strings, numbers, or booleans. Every value in one select must use the same type.

Return only a toast

Not every interaction needs to continue the public conversation:

interaction explainSymbol(symbol: str) {
  show toast format("The {} mark identifies a hidden passage.", symbol);
}

show button explainSymbol("moon") -> "Inspect the symbol";

The toast is visible only to the person who used the component. Because the interaction has useful output, it does not also need to return a Sugar message.

Use components safely

One message can contain up to five components. Repeated taps on the same use are handled as one use, so a button cannot accidentally apply its change twice.

An interaction can change Sugar state, show a toast, send a message, and attach more components. Operations that require JOI’s confirmation screen—such as spending an inventory Item or approving a Lore change—must begin from a normal action instead.