Memory variables

A Memory variable remembers its latest value after someone uses the Item action or Boop.

That means a score can keep growing, an amulet can run out of charges, or a companion can remember that it is hungry.

Make a variable remember

Open the Item’s Code editor. Put the remembered variable at the top level and the action that uses it in the same module:

mem var charges = 5;

action useAmulet -> "Use amulet" {
  charges--;

  text "The amulet flashes. {charges} charges remain.";
}

The mem keyword tells JOI to remember the variable’s latest value. Because charges is top-level, every action in this Item module can use it.

The first use changes charges from 5 to 4. The next use starts at 4, changes it to 3, and remembers 3 afterward.

Without mem, every new use would start at 5.

Memory variables on Items

An Item-level Memory variable belongs to that particular Item. Two copies of the same Item can have different values.

For example, one amulet may have 2 charges left while another still has 5. If the owner gifts an amulet, its remembered values travel with it.

Item-level variables are available to every custom action on that Item. This is useful when Use, Recharge, and Check charges all need the same charges variable.

Memory variables on Boops

A Boop Memory variable remembers a separate value for each JOI using the Boop.

If a Boop remembers a streak, Alice can have a streak of 8 while Mateo has a streak of 3. They use the same Boop without sharing the same number.

Ask the user for a value

Add a with block when the person should choose the variable’s value before Sugar runs:

mem var personality: choice = "playful" with {
  input: true,
  required: true,
  choices: ("playful", "quiet", "chaotic"),
};

For example, a companion Item might ask the first owner to choose its starting personality. After that, the personality is remembered.

Asking the user and remembering the result are separate choices. mem controls what JOI remembers. input: true controls whether a person sees an input.

Remember when something happened

Memory variables can also contain Date values. This complete Code module remembers when its action last ran:

mem var lastOpened: Date = Date::from(2026, 1, 1);

action open {
  let previous: Date = lastOpened;
  lastOpened = Date::now();

  text "Previously opened on {previous}.";
}

Sugar remembers the new Date for the next use. As with every Date variable, lastOpened cannot use input: true.

Memory inside an Item action

An action can have its own Memory variables:

action search {
  mem var searches = 0;

  searches++;

  text "@1 has searched the room {searches} times.";
}

That value belongs only to search. Another action may declare its own searches without sharing the value.

Return to the default value

reset() changes a Memory variable back to its configured default. Add an action like this to the same Item Code module that declared charges earlier:

action resetAmulet -> "Reset amulet" {
  reset(charges);

  text "@1 restores the amulet to {charges} charges.";
}

If charges has a default of 5, it becomes 5 again and remembers that value.

The next lesson introduces show statements for adding chips and other visible results beside an action’s Sugar text.