Docs › game library

game.label()

Put words on the game window: a score, a timer, a "Level up!" message. Make the label once, then change what it says whenever you like.

How to write it

game.label(text, x, y, size=20, color="#ffffff", background=None)
text
What it says. Usually text in quotes, like "Score: 0". A plain number works too.
x, y
Where the middle of the words goes. (0, 0) is the top-left corner of the window, so x=70, y=24 sits near the top left.
size
How tall the letters are, in pixels. Optional, 20 if you leave it out. The text is always bold.
color
The colour of the letters, like "#ffd23f" or "yellow". Optional, white if you leave it out.
background
Optional. A colour for a rounded box behind the words, so they are easy to read on a busy scene. Leave it out for no box.

It gives back the label, so keep it in a variable (board = game.label(...)). You need that variable to change the words later.

A full example

Catch the eggs with the basket (left and right arrows). Three labels: a score with a dark box behind it, the lives left, and a "Level up!" message that pops up for a second every 5 eggs:

import game
import random

game.window(480, 360, background="#13305a")

basket = game.sprite("basket", 240, 320, size=60)
egg = game.sprite("egg", random.randint(30, 450), 0, size=34)

board = game.label("Score: 0", 70, 24, color="#ffffff", background="#000000")
lives_label = game.label("Lives: 3", 410, 24, color="#ff8080")
news = game.label("Level up!", 240, 160, size=40, color="#ffd23f")
news.hide()                     # only shown now and then

score = 0
lives = 3
speed = 4
news_timer = 0

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

    egg.y = egg.y + speed
    if basket.touches(egg):
        score = score + 1
        board.content = "Score: " + str(score)
        egg.x = random.randint(30, 450)
        egg.y = 0
        if score % 5 == 0:
            speed = speed + 1
            news.show()
            news_timer = 30     # 30 frames = 1 second
    if egg.y > 380:
        lives = lives - 1
        lives_label.content = "Lives: " + str(lives)
        egg.x = random.randint(30, 450)
        egg.y = 0
        if lives == 0:
            game.game_over("Score: " + str(score), retry=True)

    if news_timer > 0:
        news_timer = news_timer - 1
        if news_timer == 0:
            news.hide()

    game.frame()

Changing the words

Set the label's .content to new text. It shows on the next game.frame():

board.content = "Score: " + str(score)

You may see board.text = ... in older programs. That is the old name for the same thing, and it still works, but .content is the one to use.

You can also change a label's .color, .size, .background, .x and .y at any time, just like a sprite. Make the timer go red when time is nearly up:

if seconds_left < 5:
    clock.color = "#ff4040"

Good to know

  • Labels sit on top. A label starts on layer 1000 and sprites start on layer 0, so your scoreboard stays in front of the action. Want a sprite to fly over the score? Give it .layer = 2000.
  • Hide and show. news.hide() takes a label off the screen and news.show() brings it back, like the "Level up!" message above. news.remove() gets rid of it for good.
  • It's a sprite underneath. A label moves, hides and layers like any sprite. It even has a collision box, but it is a small square in the middle of the words, so a label makes a poor button. Use game.button() for that.
  • Keeping score. game.score() is a counter only. It never draws anything, so pair it with a label to show it.

Why isn't my label working?

  • TypeError: can only concatenate str (not "int") to str. You wrote "Score: " + score. Python won't glue text and a number together. Turn the number into text first: "Score: " + str(score).
  • The game gets slower and slower, or the words look smudged. You made a game.label(...) inside the loop, so there's a brand new label every frame, all piled up. Make it once, before the loop, and change .content inside it.
  • The number never changes. Changing the score variable doesn't update the label by itself. Set board.content again every time the score changes.
  • Half the words are off the edge. x and y are the middle of the text. A label at x=0 hangs half off the left side. Move it in, for example x=70.
  • I can't read it. White text on a light background disappears. Pick a different color, or add background="#000000".
  • Nothing shows at all. Check the loop ends with game.frame(), and that you didn't call .hide() and forget to .show() it again.