Docs › game library

game.save() and game.load()

A game forgets everything when it stops. Save the things that matter, like coins, a high score or the levels you've unlocked, and they're still there next time.

How to write it

game.save(key, value) game.load(key, default=None) game.clear_save(key=None)
key
A name for the thing you're saving, in quotes, like "coins" or "best". Use the same name to load it back.
value
What to save: a number, text, True/False, or a list or dictionary of those, like ["carrot", "rose"].
default
What game.load() gives back when nothing has been saved under that key yet, like the very first time someone plays. Leave it out and you get None.

game.save() and game.clear_save() give nothing back. game.load() gives back the saved value, or the default. game.clear_save("coins") forgets just the coins, and game.clear_save() with nothing in the brackets forgets everything this game saved.

A full example

A coin clicker. Click the coin to earn coins, and spend them on upgrades that earn more per click. Stop the game, press Run again, and your coins are still there:

import game

game.window(480, 360, background="#1b4332")

coins = game.load("clicker_coins", 0)     # 0 the very first time
power = game.load("clicker_power", 1)     # coins per click

coin = game.sprite("coin", 240, 170, size=110)
info = game.label("", 240, 40, size=22, color="#ffffff")
upgrade = game.button("Upgrade", 160, 320)
restart = game.button("New game", 330, 320)

def show():
    cost = power * 10
    info.content = "Coins: " + str(coins) + "   Upgrade costs " + str(cost)

show()

while game.playing():
    if game.clicked() and coin.at_mouse():
        coins = coins + power
        game.save("clicker_coins", coins)       # save when it changes
        game.sound("coin")
        show()

    if upgrade.clicked():
        cost = power * 10
        if coins >= cost:
            coins = coins - cost
            power = power + 1
            game.save("clicker_coins", coins)
            game.save("clicker_power", power)
            game.sound("powerup")
        else:
            game.sound("buzz")
        show()

    if restart.clicked():
        game.clear_save()                       # forget everything
        coins = 0
        power = 1
        show()

    game.frame()

The pattern is always the same: load at the top with a sensible default, and save whenever the value changes.

Where the save lives

  • In this browser, on this device. Play on your laptop and then on your phone, and they each have their own save. Clearing the browser's data wipes it too.
  • Each program has its own save. On a published game's page, one game can never read or spoil another game's save, even if both use the key "coins".
  • In the Playground, all your programs share one save. A "coins" saved by one Playground program is loaded by the next program that asks for "coins". Give your keys names that belong to your game, like "clicker_coins", to keep them apart.
  • Each player has their own. Your best score lives in your browser, so it's private to you. For a scoreboard everyone can see, use game.submit_score().

A high score that lasts

Load the best score at the top, and only save when it's beaten:

best = game.load("best", 0)

# ... the game loop, then when the game ends:
if score > best:
    best = score
    game.save("best", best)
game.game_over("Score: " + str(score) + "\nBest: " + str(best))

Why isn't my save working?

  • It's back to 0 every run. You load it, but never call game.save() when the value changes. Or the key is spelled differently in the two places: "coins" and "Coins" are different keys.
  • I put game.save() at the bottom of the loop. That saves the same value 30 times a second, again and again. It works, but it's wasted effort. Save only when something actually changes, like in the example above.
  • I get None and then an error. You left out the default. Write game.load("coins", 0), not game.load("coins"), so coins + 1 works the very first time.
  • It says it can't store something. game.save() only takes numbers, text, True/False, and lists and dictionaries of those. A sprite or a set can't be saved: save its numbers instead, like player.x.
  • My dictionary's number keys came back as text. A saved dictionary always comes back with text keys, so {1: "gold"} loads as {"1": "gold"}. Use text keys from the start.
  • I want to start over while testing. Run game.clear_save() once, or give your game a "New game" button like the example.