App variable scopes

The variables from earlier lessons belong to the Item or Boop where they are declared. An App can declare variables for several linked creations instead.

App declarations use the same variable syntax you already know, with a scope added at the beginning:

player var $reputation = 0;
app var $eventProgress = 0;
app const $eventComplete = $eventProgress >= 100;
host mem var $attempts = 0;

The pieces keep separate jobs:

player, app, or host chooses where the value belongs.
var declares a value that can be changed.
const declares a read-only value calculated from an expression.
mem gives a mutable local or hosted variable persistent storage.
$ marks the name as coming from an App.

For example, in host mem var $attempts = 0;, host is the scope. mem var is the variable declaration. Neither piece changes the meaning of the other.

Declare App variables in the App’s Main module.

The `player` scope

The player scope gives every registered JOI a separate value:

player var $reputation = 0;
player var $energy = 10;

Alice can have 20 reputation while Mateo has 8. Both values are available across every Item and Boop linked to the App.

Mutable values in this scope are stored automatically, so mem is not added to the declaration.

The `app` scope

The app scope gives the App one value shared by everyone:

app var $eventProgress = 0;
app var $eventGoal = 10000;

If one linked creation changes $eventProgress, every other linked creation reads the new value. Mutable values in this scope are also stored automatically.

The `host` scope

The host scope provides the same declaration separately to each linked Item or Boop:

host var $lockDifficulty = 10;
host mem var $attempts = 0;
host const $mastered = $attempts >= 5;

The scope only decides where these values belong. The declaration after it keeps its usual meaning: $lockDifficulty is mutable, mem gives $attempts persistent storage, and $mastered is calculated.

For an Item, hosted memory belongs to that individual non-stackable Item. For a Boop, it belongs separately to each JOI using the Boop.

Constants keep their scope

Add const after whichever scope should own the calculation:

app var $eventProgress = 0;
app var $eventGoal = 10000;
app const $eventPercent = clamp(($eventProgress / $eventGoal) * 100, 0, 100);

player var $health = 100;
player var $maxHealth = 100;
player const $healthPercent = clamp(($health / $maxHealth) * 100, 0, 100);

host mem var $attempts = 0;
host const $mastered = $attempts >= 5;

The scope decides which values the expression may read. A constant in the App scope cannot depend on a value in the Player scope because there would be no single result for the entire App.

Use App names in linked creations

The $ remains part of the name everywhere the variable is used:

text {
  $reputation += 5;
  "@1 gained 5 reputation. Total: {$reputation}"
}

Keep it when a function expects the variable’s name as text too:

show variables $reputation;

Input is a separate choice

A with block configures presentation and input just as it does for a local declaration:

player var $nickname = "Traveler" with {
  input: true,
};

The scope decides where the value belongs. input: true only decides whether a linked creation asks the person for it.

Functions shared by an App

A regular function declared in App Main can use App resources and is callable from every linked creation:

app var $eventScore = 0;
app var $eventGoal = 1000;

fn eventProgress() {
  format("{} / {}", $eventScore, $eventGoal)
}

Sometimes the shared function also needs names declared by whichever Item or Boop calls it. Add the host scope to that function:

host fn healthLabel() {
  format("{} HP", health)
}

host still means “use the linked host’s context.” It does not create a different kind of function. A hosted function is available only while an Item or Boop linked to the App is running.

The next lesson uses hosted variables with defaults and introduces mixins for sharing source declarations.

The player scope

The app scope

The host scope