Participants

A participant is a JOI taking part in an Item action or Boop. Sugar numbers participants so your code can refer to each one consistently.

Participant numbers

• Participant 1 is always the JOI using the Item action or Boop.
• Participant 2 is the first additional participant.
• Participant 3 is the next participant.

The numbers begin at 1. An action must allow every participant number its code uses.

Put participant names in text

Write @ followed by a participant number:

text "@1 dares @2 to send @3 their last saved photo.";

When Alice uses this with Mateo and Rosa, the result begins:

@1, @2, and @3 are participant mentions. They are not text variables or function calls.

Count participants

PCOUNT is a constant containing the number of participants in the current use:

PCOUNT == 3

count() returns the same total when called without arguments:

count()

Both values are 3 in the earlier example. PCOUNT is concise; count() becomes more useful when you want to count only participants matching a rule.

Check one participant

Participant helper functions are standalone functions, not part of a namespace. Their purpose is already clear from names such as woman(), man(), and nonbinary().

Pass the participant number as the argument:

woman(1)

This returns true when participant 1 is a woman and false otherwise.

Use the result in a condition:

text when woman(1) {
  "@1 enters the women's tournament."
}

Functions such as gender(), sexuality(), and genderIdentity() support more detailed rules. The participant function reference lists every accepted value.

Check several participants

Some participant helpers can check more than one numbered participant:

woman(1, 2)

This is true only when both participant 1 and participant 2 match.

any() answers whether at least one selected participant matches a rule, while count() can return how many match:

any("woman", 1, 2, 3)
count("woman", 1, 2, 3)

Use pronouns

Every Joi value exposes its pronouns directly:

ACTOR.they
ACTOR.them
ACTOR.their
ACTOR.theirs
ACTOR.themselves

This also works with a JOI selected through an input or reached through a Session seat:

text "{opponent.name} raises {opponent.their} sword.";
text "{SELF.joi.name} spends {SELF.joi.their} final mana.";

The original participant functions remain convenient when you only need one word from a numbered participant:

they(2)
them(2)
their(2)
theirs(2)
themselves(2)

For example:

text "@1 takes @2's hand and pulls {} closer." with them(2);

Sugar uses participant 2’s configured pronouns. These functions are useful where an @2 name mention would sound unnatural.

When you need several forms, create one reusable Pronoun value:

let p = Pronoun::of(2);

text "{p.they} takes the lantern and carries it with {p.them}.";

Pronoun::of() also accepts a Joi or Seat. Use Pronoun::fromGender() when there is no participant or JOI:

let narrator: Pronoun = Pronoun::fromGender("NON_BINARY");

Pronoun values handle common verb agreement:

text "{p.they} {p.is} ready.";
text "{p.they} {p.has} arrived.";
let movement = p.agree("walks", "walk");
text "{p.they} {movement} toward the door.";

agree() receives the singular form first and the plural-agreement form second. It selects "walks" for she or he, and "walk" for singular they.

The next lesson focuses on pronoun values and grammatical agreement. After that, match combines these value skills into readable multi-way decisions.