SugarItem variable object
An Item variable contains information about the Item selected from inventory. Its properties can be read but not changed.
| Property | Type | Meaning |
|---|---|---|
name | str | Visible name, preferring displayName |
displayName | str or None | Custom instance name |
originalName | str | Original Item or blueprint name |
id | str | Selected inventory instance ID |
blueprintId | str or None | Source blueprint ID |
quantity | number | Number of Items in the stack |
remainingUses | number | Uses remaining on the active stack entry |
usesPerItem | number | Full uses provided by each Item |
totalUses | number | All uses available across the stack |
quality | str | Current quality |
persistent | bool | Whether the Item is not consumed through uses |
For a consumable stack:
totalUses = remainingUses + ((quantity - 1) * usesPerItem)Item and blueprint IDs are strings. JOI checks the selected Item against the person’s current inventory before using it.
Joi object
ACTOR, entries in JOIS, Seat.joi, and Joi input variables use the same read-only type.
| Property | Type | Meaning |
|---|---|---|
id | str | Stable JOI ID |
name | str | Display name |
username | str | Username without @ |
image | Media | Current profile image as a first-class Media value |
they, them, their, theirs, themselves | str | Pronouns resolved for this JOI |
is, was, has, does | str | Verb forms that agree with this JOI’s pronouns |
ACTOR is the JOI invoking the current action or message interaction. JOIS contains the current participants as a list of JOIs; its exact type is List<Joi>. Their profile images can be used anywhere a Media value is accepted:
Item::setImage(ACTOR.image);Use Joi.agree(singular, plural) for other verbs:
let action = ACTOR.agree("watches", "watch");
text "{ACTOR.they} {action} the horizon.";Media object
A Media resource such as &cover and Joi.image has the Media type.
| Property | Type | Meaning |
|---|---|---|
type | str | "IMAGE" or "VIDEO" |
url | str | Resolved resource URL |
name | str or None | Media Library name when the value came from &resource |
Pass Media values directly to features such as Item::setImage(). Media references are highlighted separately from variables in the editor.
Seat object
SELF, entries in SEATS, and Seat input variables represent one participant in the current Session.
| Property | Type | Meaning |
|---|---|---|
index | number | One-based seat position |
joi | Joi | JOI occupying the seat |
host | Item-like object | Item bound to the seat |
| Session seat variable name | Its declared value type | Current value for that seat |
SEATS contains every participant as a list of seats, so ordinary list access, closures, and list methods work with it. Its exact type is List<Seat>. SELF is the entry belonging to the acting JOI.
SESSION object
Session actions and Session-bound interactions can read:
| Property | Type | Meaning |
|---|---|---|
id | str | Current Session ID |
name | str | Session declaration name |
status | str | Current lifecycle status |
HOST object
Item actions can read their current Item through the HOST constant. App Embed Templates and hosted functions can use it to read the linked Item or Boop calling them.
| Property | Meaning |
|---|---|
name | Visible Item or Boop name |
description | Item or Boop description |
image | Current Item or Boop image value when applicable |
quality | Current Item quality when applicable |
kind | Kind of creation when available |
Only the properties in this table are available.
Embed object
Saved embed declarations may provide title through embed name -> "Title". Embed definitions and one-use overrides use the following properties.
| Property | Required | Type | Limit or behavior |
|---|---|---|---|
title | No | str, number, or bool | 256 characters |
description | No | str, number, or bool | 2,000 characters |
banner | No | Media name | Must resolve to an image |
thumbnail | No | Media name | Must resolve to an image |
footer | No | str, number, or bool | 256 characters |
fields | No | List of field objects | Up to 10 |
Unsupported properties produce an error.
Embed field object
Embed declarations use the shorter value -> "Label" field syntax. Add an optional image with with icon => &resource or with { icon: &resource }. Field objects are used by fields or addFields call-time options on show embed.
| Property | Required | Type | Limit or behavior |
|---|---|---|---|
title | Yes | str, number, or bool | 256 characters, must not be empty |
text | No | str, number, or bool | 1,000 characters |
icon | No | Media | Must resolve to an image |
progress | No | number or two-value list | Current value, or (value, maximum) |
Embed override object
Overrides support every embed property plus addFields.
fieldsreplaces the saved list.addFieldsappends to the current list.- Both values must be lists.
- The final merged embed still follows every field and length limit.
Object access rules
Sugar objects expose only their defined properties. A missing property returns None.