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 English API reference; other languages have their own.
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.
Other languages
The examples use the English API: from pystage.en import Sprite, Stage. German (pystage.de) and Lithuanian (pystage.lt) use the block names of Scratch in these languages.
Next steps
- Convert one of your Scratch projects and read the Python code it produces.
- Browse the documentation. The user-facing block API is still mostly undocumented, so the docs are a reference rather than a tutorial.
- Ask questions on Discord.