PyStage

Scratch-like Python programming

PyStage bridges the gap between Scratch and Python. It is a Python library that offers all Scratch blocks as Python methods, and a converter that turns your Scratch projects into Python code. Graphics and sound run on PyGame.

1. Install

One command, Python 3.10 or newer.

pip install pystage

Getting started

2. Convert your Scratch project

Upload a project or a .sb3 file and get a ready-to-run Python project.

Convert a project

3. Read the docs

All blocks as methods for sprites and the stage, in English and German.

Open the docs

Scratch blocks, written as Python

Every Scratch block has a matching method. Scripts that start with a hat block become functions that you connect to the same event. Because PyStage refreshes the screen after each loop iteration and after blocks like wait, your code behaves like a Scratch script, and you do not need to write a game loop.

Left: a Scratch script with the blocks when flag clicked, go to x y, set size, repeat 8 with move, change size, next costume and wait, then say Hello pyStage. Middle: the Scratch cat on a stage saying Hello pyStage. Right: the same program as PyStage Python code.
A Scratch script (left) and the Python code the PyStage converter makes from it (right).
Scratch blocks and the matching PyStage methods
Scratch blockPyStage (English API)
when green flag clickedsprite.when_program_starts(function)
when d key pressedsprite.when_key_pressed("d", function)
move 10 stepssprite.move(10)
turn left 90 degreessprite.turn_left(90)
change x by 10sprite.change_x_by(10)
wait 1 secondssprite.wait(1)
say Hellosprite.say("Hello")

A complete example

This program defines a stage and a sprite on the stage. The functions are code blocks that are connected to events (the hat blocks in Scratch) with the corresponding methods.

from pystage.en import Stage

stage = Stage()
stage.add_backdrop("grid")
zombie = stage.add_a_sprite()

def doit(zombie):
    zombie.say("Hello pyStage!")
    for i in range(4):
        zombie.move(10)
        zombie.wait(1)
        zombie.think("This is awesome!")
        zombie.turn_left(90)
        zombie.wait(1)
        zombie.think("")
    zombie.say("Move me around with WASD.")

zombie.when_program_starts(doit)

def right(zombie):
    zombie.change_x_by(10)

def left(zombie):
    zombie.change_x_by(-10)

def up(zombie):
    zombie.change_y_by(10)

def down(zombie):
    zombie.change_y_by(-10)

zombie.when_key_pressed("d", right)
zombie.when_key_pressed("a", left)
zombie.when_key_pressed("w", up)
zombie.when_key_pressed("s", down)

stage.play()

And here is the result:

Screen capture of the demo: a sprite on a grid says Hello pyStage, moves in a square and can be moved around with the keys W, A, S and D.
Screen capture of the demo program.

Why PyStage?

Alpha version. Not all things may work as expected. If something breaks, please get in touch or open an issue.

Quick intro video

Video thumbnail: Quick intro to PyStage for ScratchCon 2021

Watch our quick intro to PyStage for ScratchCon 2021 (opens YouTube).