Docs › game library

game.submit_score()

Put a player's score on your game's own leaderboard. Publish the game, and its page gets a scoreboard showing the best score of everyone who plays it.

How to write it

game.submit_score(points)
points
The score, as a number. Decimals are rounded down to a whole number (12.9 becomes 12). Higher is better: the board is sorted biggest first.

It gives nothing back, and it never stops or slows your game, so you can call it whenever you like.

A full example

A 20-second coin catcher. When the time runs out, the score goes on the leaderboard and the game ends:

import game
import random

game.window(480, 360, background="#0b1020")

basket = game.sprite("basket", 240, 320, size=60)
coin = game.sprite("coin", random.randint(30, 450), 0, size=36)
board = game.label("Score: 0", 70, 24, color="#ffffff")
clock = game.label("Time: 20", 400, 24, color="#ffffff")

score = 0
frames = 20 * 30            # 20 seconds at 30 frames a second

while game.playing():
    if game.pressed("left"):
        basket.x = basket.x - 8
    if game.pressed("right"):
        basket.x = basket.x + 8

    coin.y = coin.y + 6
    if basket.touches(coin):
        score = score + 1
        board.content = "Score: " + str(score)
        game.sound("coin")
        coin.x = random.randint(30, 450)
        coin.y = 0
    if coin.y > 380:
        coin.x = random.randint(30, 450)
        coin.y = 0

    frames = frames - 1
    clock.content = "Time: " + str(frames // 30)
    if frames == 0:
        game.submit_score(score)          # onto the leaderboard
        game.game_over("Time's up! Score: " + str(score), retry=True)

    game.frame()

In the Playground, game.submit_score() quietly does nothing, so the example runs but no board appears. That's on purpose: you can test your game as much as you like without filling the board with practice runs. Publish it to see the board.

How the leaderboard works

  • It appears by itself. Publish your game (any program with import game is published as a game), and if its code contains game.submit_score, the game's page gets a Leaderboard next to the game.
  • One line per player. Each player keeps only their best score. A worse run never replaces a better one.
  • The top 10 are shown, biggest score first, with each player's name and picture.
  • Players must be signed in. Anyone can play, but only signed-in players' scores are saved. The board reminds everyone else to sign in.
  • Scores are saved on the game's own page. Pressing Play on a game in the community gallery takes you there, and so does its link.

When to call it

The simplest place is right before game.game_over(), as in the example above: one score per game.

You can also call it every time the score goes up. Only scores that beat the player's best for that run are sent, so this is safe, and the board updates live as they play. It also means a player who closes the tab mid-game still keeps their score.

if basket.touches(coin):
    score = score + 1
    game.submit_score(score)    # the board updates while you play

Why isn't my leaderboard showing?

  • It's written without game. in front. The site looks for the exact text game.submit_score in your code. With from game import * you'd write submit_score(score), and with import game as g you'd write g.submit_score(score). Both run fine, but no board appears. Use import game and game.submit_score(...).
  • You're testing in the Playground. It does nothing there. Open the published game's page instead.
  • Nobody signed in has played yet. The board says "No scores yet" until a signed-in player finishes a run.
  • It's never reached. If the line is inside an if that never comes true, nothing is sent. A print("sent", score) next to it shows whether it runs.

When lower is better

The board always puts the biggest number first. For a race or a speed-run, where the fastest time wins, turn the time into points so faster means more:

seconds = frames_taken / 30
game.submit_score(1000 - seconds * 10)   # 20 s scores 800, 30 s scores 700