Saved values

A program forgets everything when it stops. save keeps a value so that it is still there the next time the program runs, and load gives it back: a best score, a player's name, the level you reached.

let clicks = load("clicks", 0)      // what was saved last time, or 0 the first time

function onMouseDown() {
  clicks += 1
  save("clicks", clicks)
}

function draw() {
  background("midnightblue")
  text("Clicks " + clicks, width / 2, height / 2, "white", 40, "centre")
}

Click a few times, then press Restart in the footer, or close the file and open it again. The count carries on from where it was.

save and load

The name is any text you choose: "best", "player", "level 3 time". Both answer at once, so there is no await.

Always give load its second value. The first time a program runs nothing has been saved yet, and that value is what you get: load("best", 0) is 0, load("name", "nobody") is "nobody". Left out, you get undefined.

What can be saved

Numbers, text, true and false, lists, and objects with names and values. Lists and objects can hold each other, as deep as you like.

save("player", { name: "Ada", level: 3, keys: ["red", "blue"] })

const player = load("player", { name: "", level: 1, keys: [] })
console.log(player.name, player.keys.length)

A function, a sprite or an image cannot be saved, and trying to stops the scene with an error that says so. Save the numbers that describe the thing: save("ship", { x: ship.x, y: ship.y }).

What load gives you is a copy. Changing it does not change what is saved, so save it again when you want the change kept:

const player = load("player", { name: "", level: 1, keys: [] })
player.level += 1
save("player", player)

When to save

Save when something worth keeping changes: a game ends, a level is finished, a setting is switched. There is no need to save every frame.

A best score is saved at the moment the game ends, and only when it has been beaten:

if (score > best) {
  best = score
  save("best", best)
}

The Snake demo keeps its best score with these lines.

To start again from nothing, save the starting value: save("best", 0).

Where the values are kept

• On the computer, tablet or phone you are using. They are not sent anywhere, and Circuitry on another device starts with nothing.
• For this scene alone. Each scene has its own names, so two scenes can both save "best" and neither sees the other's. A scene cannot see anything Circuitry itself keeps.
• By the scene's file. A file that is renamed, moved or copied starts with nothing. A scene exported with File, Export as Web Page keeps its own values in the browser it is opened in.
• Until Circuitry's data on the device is cleared.

Keep what you save small: scores, names and settings, not pictures. A scene has room for 100 names and 100,000 characters in all. Past that the scene carries on, but the new value is forgotten when the scene next starts.

These are not the functions for files. loadText and loadJSON read a file that sits beside the scene (2D functions).