Automations

An Automation is a Sugar program that an App runs on a schedule. Define every Automation together in the App’s Automations tab.

Use one when part of your experience should change even if nobody is currently using an Item or Boop.

Change shared weather every day

Declare a choice in the App scope in Main:

app var $weather: choice = "SUNNY" with {
  choices: ("SUNNY" -> "Sunny", "CLOUDY" -> "Cloudy", "RAINY" -> "Rainy"),
};

Add a daily Automation in the same scope:

app automation changeWeather {
  config {
    schedule: daily("09:00"),
  }

  $weather = Rand::pick("SUNNY", "CLOUDY", "RAINY");
}

Once it runs, every linked creation can react to the same weather value.

Choose what the Automation updates

Like an App variable declaration, an Automation declaration begins with a scope. Here the scope chooses which targets run the program and which values it may change.

• app runs the program once and can change variables in the App scope.
• player runs it once for each registered JOI and can change that JOI’s values in the Player scope.
• host runs it for linked Item instances and Boop memory contexts. It can change their local and hosted Memory variables.

Choose the scope that matches the variable you need to change.

Restore each player’s energy

Use the Player scope when every JOI should recover separately. First declare its values together in Main:

player var $energy = 10;
player var $maxEnergy = 10;

Then add the Automation in Automations:

player automation restoreEnergy {
  config {
    schedule: hourly(0),
  }

  $energy = clamp($energy + 5, 0, $maxEnergy);
}

One player’s energy changing does not change anyone else’s.

Change linked hosts over time

An Automation in the Host scope can update Memory variables defined on a linked Item or Boop, including hosted memory variables provided by the App. For this example, the linked non-stackable Item’s Code module contains:

mem var durability = 100;

The App’s Automations tab contains:

host automation lowerDurability {
  config {
    schedule: daily("00:00"),
  }

  if durability > 0 {
    durability--;
  }
}

When its current host is an Item, it may also call Item::setImage() to change that Item’s named image.

Schedules and timezones

Use the schedule helpers inside config:

schedule: hourly(15)
schedule: daily("09:30")
schedule: weekly("monday", "09:30")
schedule: monthly(1, "09:30")

Times use 24-hour HH:MM text. JOI detects your timezone when timezone is omitted. Add an IANA timezone when the schedule must use a specific one:

timezone: "Europe/London"

enabled defaults to true. Set it to false to pause the entire Automation.

When the configuration is short, it can stay on one line:

config schedule => daily("09:30"), timezone => "Europe/London";

This is equivalent to a config block with the same settings, written in the compact mapping form introduced in Arrow syntax.

An optional when condition is checked for each scheduled target. For this example, Main contains:

app var $rewardsEnabled = true;
player var $tokens = 0;

The Automations tab contains:

player automation dailyReward when $rewardsEnabled {
  config {
    schedule: daily("09:30"),
  }

  $tokens += 5;
}

What an Automation cannot do

An Automation runs in the background, so there is no active chat message and nobody waiting to approve a purchase or Item use.

For that reason, it cannot:

• Add message chips, media, variable chips, or embeds
• Use an Item from someone’s inventory
• Charge or transfer Lore
• Request a paid Item quality change or mutation

It may use Rand::roll() only when the visible dice result is turned off:

let roll = Rand::roll("1d20", false);

Test and pause

You can pause an Automation without deleting it.

The App’s Run menu keeps testing separate from real execution:

• Run in Sandbox Mode tests one Automation against editable context. Choose the Automation and run time. For a Host Automation, choose a linked Item from your inventory to start from its saved state, or choose one of the App’s blueprints to start from its defaults. The result shows whether when matched and which values or effects would change. Nothing is saved or queued.
• Queue automation asks you to choose a saved, enabled Automation and confirm it. This runs against real targets, can change real variables and Items, and has a five-minute cooldown.

Save changes before queueing an Automation. Sandbox Mode can test the code currently in the editors without saving it first.