Python Play (beta)

The easiest way to start coding games and graphics projects in Python

Python Play is an open-source code library for the Python programming language that makes it as easy as possible to start making games. Here's the code to make a simple game using Play:

import play

cat = play.new_text('=^.^=', font_size=70)

@play.repeat_forever
async def move_cat():
    cat.x = play.random_number(-200, 200)
    cat.y = play.random_number(-200, 200)
    cat.color = play.random_color()
    
    cat.show()

    await play.timer(seconds=0.4)

    cat.hide()

    await play.timer(seconds=0.4)

@cat.when_clicked
def win_function():
    cat.show()
    cat.words = 'You won!'

play.start_program()

The code above makes a game where you have to click the cat to win:

You can try playing and changing this game on repl.it!

Python Play is an excellent choice for beginner programmers to get started with graphics programming. It was designed to have similar commands and simplicity to MIT's Scratch and is distinguished from such projects as Pygame, Arcade, or Pygame Zero because of its lack of boiler plate code, its easy-to-understand plain-english commands, and intuitive API. Read more about its design at the bottom of this document.

How to install Python Play

Run the following command in your terminal:

pip install replit-play

Or you can just go to repl.it and you won't have to install anything :)

How to use Python Play

All Python Play programs start with import play and end with play.start_program(), like this:

import play # this is the first line in the program



play.start_program() # this is the last line in the program

All other commands go between those two commands.

To try any of the following examples, go to repl.it and try pasting code in.

Commands

The rest of this document is divided into the following sections:

• Basic Commands - Getting graphics, shapes, and text on the screen. Also changing the backdrop.
• Animation and Control Commands - Animating and controlling graphics, shapes, and text.
• Sprite Commands - Controlling sprites.
• Mouse Commands - Detecting mouse actions (clicks, movement).
• Keyboard Commands - Detecting keyboard actions.
• Physics Commands - Making physics objects.
• Other Useful Commands - General commands.
• Why use Python Play? - How this library is different from other graphics libraries.

Basic Commands

To get images or text on the screen, use the following commands. (Copy and paste the code below to try it out.)

play.new_box()

box = play.new_box(
        color='black',
        x=0,
        y=0,
        width=100,
        height=200,
        border_color="light blue",
        border_width=10
    )

This will put a tall, black box in the middle of the screen.

If you want to change where the image is on the screen, try changing x=0 (horizontal position) and y=0 (vertical position). Just like Scratch, the middle of the screen is x=0, y=0. Increasing x moves the image right and decreasing x moves the image left. Likeswise, increasing y moves the image up and decreasing y moves the image down. You can also change the color by changing 'black' to another color name, like 'orange'.

play.new_image()

character = play.new_image(
        image='character.png', 
        x=0, 
        y=0, 
        angle=0, 
        size=100, 
        transparency=100
    )

This will place an image in the middle of the screen. Make sure you have a file named character.png in your project files for the code above to work. You can find images online at sites like http://icons.iconarchive.com/icons/icojam/animals/64/01-bull-icon.png

play.new_text()

greeting = play.new_text(
        words='hi there', 
        x=0, 
        y=0, 
        angle=0, 
        font=None, 
        font_size=50, 
        color='black', 
        transparency=100
    )

This will put some text on the screen.

If you want to change the font, you'll need a font file (usually named something like Arial.ttf) in your project files. Then you can change font=None to font='Arial.ttf'. You can find font files at sites like DaFont.

play.new_circle()

ball = play.new_circle(
        color='black', 
        x=0, 
        y=0, 
        radius=100, 
        border_color="light blue", 
        border_width=10, 
        transparency=100
    )

This will put a black circle in the middle of the screen.

play.new_line()

line = play.new_line(
        color='black', 
        x=0, 
        y=0, 
        length=100, 
        angle=0, 
        thickness=1, 
        x1=None, 
        y1=None
    )

This will create a thin line on the screen.

play.set_backdrop()

You can change the background color with the play.set_backdrop() command:

play.set_backdrop('light blue')

There are lots of named colors to choose from. Additionally, if you want to set colors by RGB (Red Green Blue) values, you can do that like this:

# Sets the background to white. Each number can go from 0 to 255
play.set_backdrop( (255, 255, 255) )

Anywhere you can set a color in Python Play, you can do it using a named color like 'red' or an RGB value above like (255, 255, 255) or even an RGBA value like (0, 0, 0, 127) (the fourth number is transparency from 0 to 255). You can get the current background color with play.backdrop.

Animation and Control Commands

@play.repeat_forever

To make things move around, you can start by using @play.repeat_forever, like this:

cat = play.new_text('=^.^=')

@play.repeat_forever
def do():

    cat.turn(10)  

The above code will make the cat turn around forever. Sprites have other commands that you can see in the next section called Sprite Commands.

@play.when_program_starts

To make some code run just at the beginning of your project, use @play.when_program_starts, like this:

cat = play.new_text('=^.^=')

@play.when_program_starts
def do():

    cat.turn(180)  

This will make the cat turn upside down instantly when the program starts.

await play.timer(seconds=1)

To run code after a waiting period, you can use the await play.timer() command like this:

cat = play.new_text('=^.^=')

@play.when_program_starts
async def do():

    cat.turn(180)  
    await play.timer(seconds=2)
    cat.turn(180)  

This will make the cat turn upside down instantly when the program starts, wait 2 seconds, then turn back up again.

play.repeat() and await play.animate()

To smoothly animate a character a certain number of times, you can use play.repeat() with await play.animate(), like this:

cat = play.new_text('=^.^=')

@play.when_program_starts
async def do():
    for count in play.repeat(180):
        cat.turn(1)
        await play.animate()

This code will animate the cat turning upside down smoothly when the program starts.

To break down the code:

• for count in play.repeat(180): runs the code 180 times.
• cat.turn(1) turns that cat 1 degree each time.
• await play.animate() makes the cat animate smoothly. Without this command, the cat would just turn upside down instantly.

Note: to use await play.animate() and await play.timer(), the word async must be included before def in your function definition.

Sprite Commands

Simple commands

Sprites (images and text) have a few simple commands:

• sprite.move(10) — moves the sprite 10 pixels in the direction it's facing (starts facing right). Use negative numbers (-10) to go backward.
• sprite.turn(20) — Turns the sprite 20 degrees counter-clockwise. Use negative numbers (-20) to turn the other way.
• sprite.go_to(other_sprite) — Makes sprite jump to another sprite named other_sprite's position on the screen. Can also be used to make the sprite follow the mouse: sprite.go_to(play.mouse).
• sprite.go_to(x=100, y=50) — Makes sprite jump to x=100, y=50 (right and up a little).
• sprite.point_towards(other_sprite) — Turns sprite so it points at another sprite called other_sprite.
• sprite.point_towards(x=100, y=50) — Turns sprite so it points toward x=100, y=50 (right and up a little).
• sprite.hide() — Hides sprite. It can't be clicked when it's hidden.
• sprite.show() — Shows sprite if it's hidden.
• sprite.clone() — Makes a copy or clone of the sprite and returns it.
• sprite.remove() — Removes a sprite from the screen permanently. Calling sprite commands on a removed sprite won't do anything.
• sprite.start_physics() — Turn on physics for a sprite. See the Physics Commands section for details.
• sprite.stop_physics() — Turn off physics for a sprite. See the Physics Commands section for details.

Properties

Sprites also have properties that can be changed to change how the sprite looks. Here they are:

• sprite.x — The sprite's horizontal position on the screen. Positive numbers are right, negative numbers are left. The default is 0.
• sprite.y — The sprite's vertical position on the screen. Positive numbers are up, negative numbers are down. The