PyStage

Getting started

Install PyStage, run your first program and learn how Python code behaves like a Scratch script.

Install

pip install pystage

PyStage needs Python 3.10 or newer. pygame-ce is installed automatically. If you have the classic pygame installed, remove it first with pip uninstall pygame.

Your first program

Save this as a file, for example first.py, and run it with Python. A window opens and the sprite moves in a square.

from pystage.en import Sprite, Stage

stage = Stage()
zombie = stage.add_a_sprite()

def doit(zombie: Sprite):
    for i in range(4):
        zombie.move(10)
        zombie.turn_left(90)
        zombie.wait(1)

zombie.when_program_starts(doit)

stage.play()

Use the autocompletion of your editor to see what methods are available. There are methods for all Scratch blocks bound to your stage and sprite instances, including the Pen extension, variables, lists, clones and all events. The only blocks that do nothing are the ones that need a microphone (loudness).

The full list is in the documentation.

Your code behaves like a Scratch script

Some things work differently than in normal Python programs, because your code behaves like a Scratch script.

Loops refresh the screen

The screen is refreshed after each iteration of a loop and after blocks that take time, like wait. You do not have to care about a game loop.

Functions are custom blocks

Functions in the same file that you call from your code behave like custom blocks in Scratch, so they can contain loops and wait as well.

Run without screen refresh

Mark a function with @no_refresh and it runs at once, like “run without screen refresh” in Scratch. In the example below, the square is drawn immediately.

from pystage.en import Sprite, Stage, no_refresh

stage = Stage()
zombie = stage.add_a_sprite()

def jump(zombie: Sprite, height):
    for i in range(10):
        zombie.change_y_by(height / 10)
    for i in range(10):
        zombie.change_y_by(-height / 10)

@no_refresh
def draw_square(zombie: Sprite):
    # Like "run without screen refresh" in Scratch:
    # The square is there at once.
    zombie.pen_down()
    for i in range(4):
        zombie.move(50)
        zombie.turn_left(90)
    zombie.pen_up()

def doit(zombie: Sprite):
    draw_square(zombie)
    while True:
        jump(zombie, 80)
        zombie.wait(1)

zombie.when_program_starts(doit)

stage.play()

Errors are shown

If there is an error in your code, the message is shown in the window and in the terminal.

English and German

The examples use the English API: from pystage.en import Sprite, Stage. A German API exists as well, with the block names of German Scratch: from pystage.de import ....

Currently, only the English API is fully translated. The German API is generated automatically. Other languages will be added when PyStage gets more stable. Get in touch if you want to help maintain a translation.

Next steps