SugarSugar appears in several JOI fields. The same language is used everywhere, but a field made only to answer a question cannot also change an Item or add content to a message.
Use this page when Sugar says a function or assignment is not available where you wrote it.
Creator functions follow the rules of the place that calls them. For example, a function called by a condition may read variables but may not change them. Putting an instruction inside another function never gives it extra permission.
Quick table
| Where you write Sugar | Read variables | Change variables | Add output | Use Items or Lore |
|---|---|---|---|---|
| Item action body | Yes | Yes | Yes | Yes, with confirmation when needed |
| Item action or Boop Sugar text | Yes | Yes | Yes | Yes, with confirmation when needed |
| Condition field | Yes | No | No | No |
const declaration | Yes | No | No | No |
| Embed Template | Yes | Only its own let variables | No | No |
| Interaction | Yes | Yes | Message output or a private toast | Item images only; no confirmation or Lore operations |
| Session view | Yes | No | Chips and embeds | No |
| App Automation | Yes | Variables in the App scope | No | No |
| Player Automation | Yes | Variables in the Player scope | No | No |
| Host Automation | Yes | Local and hosted Memory variables | Item::setImage() for Item hosts | No |
Item actions and Boop texts
These are the main places for complete interactive programs. Put shared Item action behavior directly in the action body so it runs once before Sugar chooses a text. Keep code inside an individual text when only that selected result should run it.
They can:
- Read and change their variables
- Use linked App variables
- React to participants
- Add chips, media, variable chips, dice, and embeds
- Use a selected inventory Item
- Read or move Lore
- Change the current Item when running as an Item action
JOI asks for confirmation before applying Item use, Lore costs, paid quality changes, or transformations.
Conditions and constants
A condition checks values and returns true or false. A const declaration calculates a value from its expression.
They may use calculations and functions that only give back information. They cannot change variables or call functions that add content, use Items, move Lore, or change the current Item.
Embed Templates
An Embed Template reads the values and arguments available when show embed runs. An optional display arrow supplies its title, its properties supply the content, and an optional when condition can make it produce no embed.
Its property expressions and called functions cannot change the Item action, Boop, or App variables that called it.
An App Embed Template may also read the public HOST object described in the Object reference.
Interactions and Session views
An interaction runs only after a person uses its button or select. It receives the current ACTOR and checks its optional condition again. It may change variables, Item images, and Session state; return ordinary Sugar text; add message output; show a private toast; or combine those results. Unlike an Item action or Boop, an interaction may intentionally return only a toast. Operations that need confirmation, including Lore operations, are unavailable after a component is used.
A Session view is read-only. It can read the current SELF, SEATS, and SESSION values and show chips or embeds beside the chat composer, but it cannot change state or create message components.
Session lifecycle calls belong to Item actions. Boops and Automations cannot start or end Sessions.
Automations
Automations run in the background without an active message or confirmation screen.
Their declaration scope decides which variables they may change:
- App changes variables in the App scope
- Player changes variables in the Player scope
- Host changes local and hosted Memory variables on linked Items or Boops
Host Automations may call Item::setImage() when the current host is an Item. Other functions that add message content or require confirmation are unavailable.
Rand::roll() must use false as its second argument in an Automation because there is no message for the visible dice result.
Timezone
In an Item action or Boop, time functions use the first participant’s timezone when available and Pacific Time otherwise.
Automations use their declared timezone, or the creator’s detected timezone when none is declared.