ReferenceReference

Object reference

Reference the public properties available on Item, Joi, Media, Seat, HOST, SESSION, and embed values.

Item variable object

An Item variable contains the Item selected from inventory. Use meta for built-in Item information. To read a variable declared in the selected Item’s Sugar code, use its name directly:

plant.meta.name
plant.health
plant.$hydration
  • meta contains built-in Item information and is read-only.
  • Direct properties such as health are top-level variables declared in the selected Item’s Code module.
  • Properties such as $hydration are Host variables supplied by its linked App.

Item.meta

PropertyTypeMeaning
meta.namestrVisible name, preferring displayName
meta.displayNamestr or NoneCustom instance name
meta.originalNamestrOriginal Item or blueprint name
meta.idstrSelected inventory instance ID
meta.blueprintIdstr or NoneSource blueprint ID
meta.quantitynumberNumber of Items in the stack
meta.remainingUsesnumberUses remaining on the active stack entry
meta.usesPerItemnumberFull uses provided by each Item
meta.totalUsesnumberAll uses available across the stack
meta.qualitystrCurrent quality
meta.persistentboolWhether 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.

Item variables

The value of a direct property has the type declared by the selected Item. A property exists only when that Item or its linked App declares it.

Memory variables may be assigned:

plant.health -= 10;
plant.$hydration = clamp(plant.$hydration + 20, 0, 100);

Regular variables and constants may be read but not assigned through the Item. The Item object itself and every property under meta are also read-only. Changes to Memory variables are saved only when the action completes successfully.

Joi object

ACTOR, entries in JOIS, Seat.joi, and Joi input variables use the same read-only type.

PropertyTypeMeaning
idstrStable JOI ID
namestrDisplay name
usernamestrUsername without @
imageMediaCurrent profile image as a first-class Media value
they, them, their, theirs, themselvesstrPronouns resolved for this JOI
is, was, has, doesstrVerb 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.

PropertyTypeMeaning
typestr"IMAGE" or "VIDEO"
urlstrResolved resource URL
namestr or NoneMedia 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.

PropertyTypeMeaning
indexnumberOne-based seat position
joiJoiJOI occupying the seat
hostItem-like objectItem bound to the seat
Session seat variable nameIts declared value typeCurrent 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:

PropertyTypeMeaning
idstrCurrent Session ID
namestrSession declaration name
statusstrCurrent 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.

PropertyMeaning
nameVisible Item or Boop name
descriptionItem or Boop description
imageCurrent Item or Boop image value when applicable
qualityCurrent Item quality when applicable
kindKind 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.

PropertyRequiredTypeLimit or behavior
titleNostr, number, or bool256 characters
descriptionNostr, number, or bool2,000 characters
bannerNoMedia nameMust resolve to an image
thumbnailNoMedia nameMust resolve to an image
footerNostr, number, or bool256 characters
fieldsNoList of field objectsUp 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.

PropertyRequiredTypeLimit or behavior
titleYesstr, number, or bool256 characters, must not be empty
textNostr, number, or bool1,000 characters
iconNoMediaMust resolve to an image
progressNonumber or two-value listCurrent value, or (value, maximum)

Embed override object

Overrides support every embed property plus addFields.

  • fields replaces the saved list.
  • addFields appends 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.