What is Sugar?

Sugar is JOI’s programming language for Items and Boops. It lets your creation make choices, remember information, react to people, and change what it shows.

You do not need Sugar for a Boop that always says the same thing. You use Sugar when part of the result should depend on something.

For example, this Boop always shows the same number:

text "@1 rolled a 12.";

This version asks Sugar to choose the number:

text "@1 rolled a {}." with Rand::pick(1..=20);

text declares a possible message. JOI replaces @1 with the first participant’s name. 1..=20 is a number range containing every whole number from 1 through 20, including both ends. Rand is a group of random tools called a namespace, and ::pick selects its choice function. {} marks where the value after with belongs in the text.

The course explains ranges and namespaces in their own lessons before asking you to build with them. For now, it is enough to see that one line can produce a different roll each time.

That is already a complete Sugar creation.

One creation, one module

An Item or Boop keeps its Sugar in one Code editor. That complete document is called its module. As the course introduces variables, functions, and Item actions, they will all belong to that same document and can work together.

You can place top-level declarations in the order that reads best. A function or action may use a top-level name declared later in the same module.

What you can build

As you learn more, you can make creations that:

• Choose different text, numbers, images, or videos
• Remember values such as charges, affection, health, or wins
• Change an Item when someone uses it
• Connect several Items and Boops through an App
• Run parts of a game automatically on a schedule
• Use inventory Items or Lore with JOI’s confirmation screen

You will meet those features one at a time. None of them are required for the next lesson.

How these docs work

Learn Sugar is a course. Read it in order when you are new. Each page introduces one idea and assumes only what earlier pages have taught.

Guides build complete projects. Examples give you code to adapt. Reference is for looking up exact names, options, and limits.

Next, you will make a small Boop that is useful as soon as you publish it.