PyStage

Scratch-like Python programming.

PyStage bridges the gap between Scratch and Python. This module implements all code blocks as available in scratch. With the PyStage command line converter Scratch projects can be easily transferred to Python executable Code. To run your game in Python, PyStage uses PyGame.

Demo

Consider the following code. It defines a stage and a sprite on the stage. The functions are code blocks that are associated with events (i.e. connected to a hat block in Scratch) via 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:

Goals

Export your Scratch project to real executable Python code!
Helping coding beginners to learn Python "by Scratch".
Implementation of scratch blocks in several languages (ideal for kids). As of now en and de.

See our quick intro to PyStage for ScratchCon 2021

Installation

pip install pystage

if doesn't work, try following commands one by one.

pip install wheel
pip install pygame==2.3.0
pip install svglib==1.1.0
pip install reportlab==3.5.67
pip install pystage

Getting started

If you are interested in PyStage and want to get in touch, feel free to join us on our Discord Server.

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

For the English API, you can start with the following example code:

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. Not all of them work. Motion and Looks is mostly implemented (besides graphics effects), the Pen extension works and most of Sensing should work as well. If you want to know the details, just check the files under src/pystge/core.

The documentation is here: https://pystage.readthedocs.io/en/latest/pystage.en.html

NOTE

Please note this is a pre alpha version. Not all things may work as expected. If so, please contact us or open an issue. Documentation is automatically generated but especially the user-facing block API is still mostly empty.

Import your Scratch projects

Use our Web converter

Publish your Scratch project or download your Scratch project as .sb3 file.
Go to https://convert.pystage.org and convert your project.
Download the resulting zip file, it contains your new Python project ready to run.

Convert on your computer

Converting a Scratch project to Python code:

Export your Scratch project on the Scratch page. You will get an .sb3 file.
Use our command line converter. Yes, it's unhandy, we will work on it to make things easier.

The base usage is python -m pystage.convert.sb3 <SB3 File> -l en -d <DIRECTORY> The parameters are:

-l language of generated python "scratch blocks". In the moment of writing, en and de are available.
-d the output directory, defaults to current directory
-i print intermediate code representation
-s print sb3 project.json
-p print python code
-v verbose
-vv debug mode

Contributors

Kai Eckert, Stuttgart Media University
Florian Rupp, Stuttgart Media University

kokofixcomputers/pystage