Review version: New website (Hugo) — not the official website. Official site: https://www.pystage.org/
PyStage

Blocks

Every Scratch block and the Python command that does the same.

Each entry shows the Scratch block on the left and the Python command on the right. The commands are generated from PyStage itself, so they are always up to date.

Motion ↑

turn ↺ (15) degrees

sprite.turn_left(deg)

Works for: Sprite

Turns the sprite to the left (counter-clockwise) by the given number of degrees.

deg number
The number of degrees to turn. 90 is a quarter turn.
turn ↻ (15) degrees

sprite.turn_right(deg)

Works for: Sprite

Turns the sprite to the right (clockwise) by the given number of degrees.

deg number
The number of degrees to turn. 90 is a quarter turn.
move (10) steps

sprite.move(steps)

Works for: Sprite

Moves the sprite forward by the given number of steps, in the direction it is pointing.

steps number
How many steps to move. Negative values move the sprite backwards.
go to (random position v)

sprite.go_to_random_position()

Works for: Sprite

Moves the sprite to a random position on the stage.

go to (mouse-pointer v)

sprite.go_to_mouse_pointer()

Works for: Sprite

Moves the sprite to the position of the mouse pointer.

go to (sprite v)

sprite.go_to_sprite(sprite)

Works for: Sprite

Moves the sprite to the position of another sprite.

sprite str
The name of the sprite to go to. Use "_mouse_" for the mouse pointer or "_random_" for a random position.
go to x: (0) y: (0)

sprite.go_to_x_y(x, y)

Works for: Sprite

Moves the sprite to the given x and y position. The center of the stage is x = 0, y = 0.

x number
The horizontal position. On the default stage of 480 by 360 pixels, x goes from -240 (left) to 240 (right).
y number
The vertical position. On the default stage, y goes from -180 (bottom) to 180 (top).
glide (1) secs to (random position v)

sprite.glide_to_random_position(secs)

Works for: Sprite

Glides the sprite to a random position within the given number of seconds.

More details

The script waits until the glide is finished.

secs number
The duration of the glide in seconds. 0 moves the sprite at once.
glide (1) secs to (mouse-pointer v)

sprite.glide_to_mouse_pointer(secs)

Works for: Sprite

Glides the sprite to the position of the mouse pointer within the given number of seconds.

More details

The script waits until the glide is finished.

secs number
The duration of the glide in seconds. 0 moves the sprite at once.
glide (1) secs to (sprite v)

sprite.glide_to_sprite(secs, sprite)

Works for: Sprite

Glides the sprite to the position of another sprite within the given number of seconds.

More details

The script waits until the glide is finished.

secs number
The duration of the glide in seconds. 0 moves the sprite at once.
sprite str
The name of the sprite to glide to. Use "_mouse_" for the mouse pointer or "_random_" for a random position.
glide (1) secs to x: (0) y: (0)

sprite.glide_to_x_y(secs, x, y)

Works for: Sprite

Glides the sprite to the given x and y position within the given number of seconds.

More details

The script waits until the glide is finished.

secs number
The duration of the glide in seconds. 0 moves the sprite at once.
x number
The horizontal position to glide to.
y number
The vertical position to glide to.
point in direction (90)

sprite.point_in_direction(direction)

Works for: Sprite

Turns the sprite to face the given direction.

direction number
The direction in degrees. 0 is up, 90 is right, 180 is down and -90 is left.
point towards (mouse-pointer v)

sprite.point_towards_mouse_pointer()

Works for: Sprite

Turns the sprite to face the mouse pointer.

point towards (random direction v)

sprite.point_towards_random_direction()

Works for: Sprite

Turns the sprite towards a random direction.

point towards (sprite v)

sprite.point_towards_sprite(sprite)

Works for: Sprite

Turns the sprite to face another sprite.

sprite str
The name of the sprite to face. Use "_mouse_" for the mouse pointer or "_random_" for a random direction.
change x by (10)

sprite.change_x_by(value)

Works for: Sprite

Moves the sprite horizontally by the given amount. Positive values move it to the right.

value number
The number of steps to move horizontally.
set x to (0)

sprite.set_x(value)

Works for: Sprite

Sets the horizontal position of the sprite. The center of the stage is x = 0.

value number
The new x position.
change y by (10)

sprite.change_y_by(value)

Works for: Sprite

Moves the sprite vertically by the given amount. Positive values move it up.

value number
The number of steps to move vertically.
set y to (0)

sprite.set_y(value)

Works for: Sprite

Sets the vertical position of the sprite. The center of the stage is y = 0.

value number
The new y position.
if on edge, bounce

sprite.if_on_edge_bounce()

Works for: Sprite

If the sprite touches the edge of the stage, it bounces back and stays on the stage.

set rotation style [left-right v]

sprite.set_rotation_style_left_right()

Works for: Sprite

Sets the rotation style to left-right: the costume only turns to face left or right and is never upside down.

set rotation style [don't rotate v]

sprite.set_rotation_style_none()

Works for: Sprite

Sets the rotation style to "don't rotate": the costume always looks the same, whatever direction the sprite points in.

set rotation style [all around v]

sprite.set_rotation_style_around()

Works for: Sprite

Sets the rotation style to "all around": the costume turns with the direction of the sprite.

(x position)

sprite.x_position()

Works for: Sprite

Returns the horizontal position of the sprite. The center of the stage is 0.

(y position)

sprite.y_position()

Works for: Sprite

Returns the vertical position of the sprite. The center of the stage is 0.

(direction)

sprite.direction()

Works for: Sprite

Returns the direction the sprite is pointing in degrees. 90 is right, 0 is up, 180 is down and -90 is left.

Looks ↑

switch backdrop to (next backdrop v)

sprite.switch_to_next_backdrop()

Works for: SpriteStage

Switches the stage to the next backdrop. After the last backdrop, the first one is used again.

switch backdrop to (previous backdrop v)

sprite.switch_to_previous_backdrop()

Works for: SpriteStage

Switches the stage to the previous backdrop. Before the first backdrop, the last one is used.

switch backdrop to (random backdrop v)

sprite.switch_to_random_backdrop()

Works for: SpriteStage

Switches the stage to a random backdrop.

switch backdrop to (backdrop1 v)

sprite.switch_backdrop_to(backdrop)

Works for: SpriteStage

Switches the stage to another backdrop.

backdrop str or int
The name of the backdrop, its number (starting with 1), or one of "next backdrop", "previous backdrop" and "random backdrop".
next backdrop

sprite.next_backdrop()

Works for: SpriteStage

Switches the stage to the next backdrop. After the last backdrop, the first one is used again.

set [color v] effect to (0)

sprite.set_color_effect_to(value)

Works for: SpriteStage

Sets the color effect of the sprite. The color effect changes the colors of the costume.

value number
The new value of the effect, from 0 to 200. 0 means no effect.
set [fisheye v] effect to (0)

sprite.set_fisheye_effect_to(value)

Works for: SpriteStage

Sets the fisheye effect of the sprite. The fisheye effect bends the costume like a fish-eye lens.

value number
The new value of the effect. 0 means no effect.
set [whirl v] effect to (0)

sprite.set_whirl_effect_to(value)

Works for: SpriteStage

Sets the whirl effect of the sprite. The whirl effect twists the costume.

value number
The new value of the effect. 0 means no effect.
set [pixelate v] effect to (0)

sprite.set_pixelate_effect_to(value)

Works for: SpriteStage

Sets the pixelate effect of the sprite. The pixelate effect makes the costume look blocky.

value number
The new value of the effect. 0 means no effect.
set [mosaic v] effect to (0)

sprite.set_mosaic_effect_to(value)

Works for: SpriteStage

Sets the mosaic effect of the sprite. The mosaic effect repeats the costume as small tiles.

value number
The new value of the effect. 0 means no effect.
set [brightness v] effect to (0)

sprite.set_brightness_effect_to(value)

Works for: SpriteStage

Sets the brightness effect of the sprite. Negative values make the costume darker.

value number
The new value of the effect, from -100 (black) to 100 (white). 0 means no effect.
set [ghost v] effect to (0)

sprite.set_ghost_effect_to(value)

Works for: SpriteStage

Sets the ghost effect of the sprite. The higher the effect, the more transparent the sprite becomes.

value number
The new value of the effect. 0 means visible, 100 means invisible.
change [color v] effect by (25)

sprite.change_color_effect_by(value)

Works for: SpriteStage

Changes the color effect of the sprite by the given amount. The color effect changes the colors of the costume.

value number
The change of the effect. The effect goes from 0 to 200 and starts again at 0 after 200.
change [fisheye v] effect by (25)

sprite.change_fisheye_effect_by(value)

Works for: SpriteStage

Changes the fisheye effect of the sprite by the given amount. The fisheye effect bends the costume like a fish-eye lens.

value number
The change of the effect. 0 means no effect.
change [whirl v] effect by (25)

sprite.change_whirl_effect_by(value)

Works for: SpriteStage

Changes the whirl effect of the sprite by the given amount. The whirl effect twists the costume.

value number
The change of the effect. 0 means no effect.
change [pixelate v] effect by (25)

sprite.change_pixelate_effect_by(value)

Works for: SpriteStage

Changes the pixelate effect of the sprite by the given amount. The pixelate effect makes the costume look blocky.

value number
The change of the effect. 0 means no effect.
change [mosaic v] effect by (25)

sprite.change_mosaic_effect_by(value)

Works for: SpriteStage

Changes the mosaic effect of the sprite by the given amount. The mosaic effect repeats the costume as small tiles.

value number
The change of the effect. 0 means no effect.
change [brightness v] effect by (25)

sprite.change_brightness_effect_by(value)

Works for: SpriteStage

Changes the brightness effect of the sprite by the given amount. Negative values make the costume darker.

value number
The change of the effect. The effect goes from -100 (black) to 100 (white).
change [ghost v] effect by (25)

sprite.change_ghost_effect_by(value)

Works for: SpriteStage

Changes the ghost effect of the sprite by the given amount. The higher the effect, the more transparent the sprite becomes.

value number
The change of the effect. 0 means visible, 100 means invisible.
clear graphic effects

sprite.clear_graphic_effects()

Works for: SpriteStage

Removes all graphic effects (color, fisheye, whirl, pixelate, mosaic, brightness and ghost) of the sprite.

(backdrop [number v])

sprite.backdrop_number()

Works for: SpriteStage

Returns the number of the current backdrop of the stage (starting with 1).

(backdrop [name v])

sprite.backdrop_name()

Works for: SpriteStage

Returns the name of the current backdrop of the stage.

say (Hello!) for (2) seconds

sprite.say_for_seconds(text, secs)

Works for: Sprite

Shows a speech bubble with the given text next to the sprite for a number of seconds.

More details

The script waits until the time is over.

text str
The text to show in the bubble.
secs number
The number of seconds the bubble is shown.
say (Hello!)

sprite.say(text)

Works for: Sprite

Shows a speech bubble with the given text next to the sprite.

text str
The text to show in the bubble.
think (Hmm...) for (2) seconds

sprite.think_for_seconds(text, secs)

Works for: Sprite

Shows a thought bubble with the given text next to the sprite for a number of seconds.

More details

The script waits until the time is over.

text str
The text to show in the bubble.
secs number
The number of seconds the bubble is shown.
think (Hmm...)

sprite.think(text)

Works for: Sprite

Shows a thought bubble with the given text next to the sprite.

text str
The text to show in the bubble.
switch costume to (costume2)

sprite.switch_costume_to(costume)

Works for: Sprite

Switches the sprite to another costume.

costume str or int
The name of the costume, or its number (starting with 1).
next costume

sprite.next_costume()

Works for: Sprite

Switches the sprite to the next costume. After the last costume, the first one is used again.

change size by (10)

sprite.change_size_by(percent)

Works for: Sprite

Changes the size of the sprite by the given percentage. Negative values make it smaller.

percent number
The change in percent. For example, 10 makes the sprite 10 percent bigger.
set size to (100) %

sprite.set_size_to(percent)

Works for: Sprite

Sets the size of the sprite in percent. 100 is the normal size.

percent number
The new size in percent. 100 is the normal size, 50 is half size.
show

sprite.show()

Works for: Sprite

Shows the sprite on the stage.

hide

sprite.hide()

Works for: Sprite

Hides the sprite. It is not shown on the stage until it is shown again.

go to [front v] layer

sprite.go_to_front_layer()

Works for: Sprite

Moves the sprite in front of all other sprites.

go to [back v] layer

sprite.go_to_back_layer()

Works for: Sprite

Moves the sprite behind all other sprites.

go [forward v] (1) layers

sprite.go_forward(value)

Works for: Sprite

Moves the sprite forward by the given number of layers, so that it is shown in front of other sprites.

value int
The number of layers to move forward.
go [backward v] (1) layers

sprite.go_backward(value)

Works for: Sprite

Moves the sprite backward by the given number of layers, so that it is shown behind other sprites.

value int
The number of layers to move backward.
(costume [number v])

sprite.costume_number()

Works for: Sprite

Returns the number of the current costume of the sprite (starting with 1).

(costume [name v])

sprite.costume_name()

Works for: Sprite

Returns the name of the current costume of the sprite.

(size)

sprite.size()

Works for: Sprite

Returns the size of the sprite in percent. 100 is the normal size.

switch backdrop to (backdrop1) and wait

stage.switch_backdrop_to_and_wait(backdrop)

Works for: Stage

Switches the stage to another backdrop and waits until all scripts started by "when backdrop switches to" are finished.

backdrop str or int
The name of the backdrop, its number (starting with 1), or one of "next backdrop", "previous backdrop" and "random backdrop".

Sound ↑

start sound (pop v)

sprite.start_sound(name, loop=0)

Works for: SpriteStage

Starts playing a sound. The script does not wait until the sound is finished.

name str or int
The name of the sound file, e.g. "pop.wav", or the number of the sound (starting with 1).
loop int
How often the sound is repeated after the first time. 0 plays it once, -1 repeats it forever.
play sound (pop v) until done

sprite.play_sound_until_done(name)

Works for: SpriteStage

Plays a sound and waits until it is finished.

name str or int
The name of the sound file, e.g. "pop.wav", or the number of the sound (starting with 1).
stop all sounds

sprite.stop_all_sounds()

Works for: SpriteStage

Stops all sounds that are playing, of all sprites and the stage.

change [pitch v] effect by (10)

sprite.change_pitch_effect_by(value)

Works for: SpriteStage

Changes the pitch effect of the sound by the given amount. Positive values make the sound higher.

value number
The change of the pitch effect. The effect goes from -360 to 360, and 0 is the normal pitch.
change [pan left/right v] effect by (10)

sprite.change_pan_left_right_effect_by(value)

Works for: SpriteStage

Changes the pan effect of the sound by the given amount. The pan effect moves the sound between the left and the right speaker.

value number
The change of the pan effect. -100 is all left, 0 is the middle and 100 is all right.
set [pitch v] effect to (0)

sprite.set_pitch_effect_to(value)

Works for: SpriteStage

Sets the pitch effect of the sound. Higher values make the sound higher.

value number
The new pitch effect, from -360 to 360. 0 is the normal pitch.
set [pan left/right v] effect to (0)

sprite.set_pan_left_right_effect_to(value)

Works for: SpriteStage

Sets the pan effect of the sound. The pan effect moves the sound between the left and the right speaker.

value number
The new pan effect. -100 is all left, 0 is the middle and 100 is all right.
clear sound effects

sprite.clear_sound_effects()

Works for: SpriteStage

Removes all sound effects (pitch and pan) of the sprite.

change volume by (-10)

sprite.change_volume_by(value)

Works for: SpriteStage

Changes the volume of the sprite's sounds by the given amount. Negative values make the sound quieter.

value number
The change of the volume. The volume goes from 0 to 100.
set volume to (100) %

sprite.set_volume_to(value)

Works for: SpriteStage

Sets the volume of the sprite's sounds. 100 is the loudest and 0 is silent.

value number
The new volume, from 0 to 100 percent. Values outside this range are limited to it.
(volume)

sprite.volume()

Works for: SpriteStage

Returns the volume of the sprite's sounds, from 0 to 100.

Events ↑

when flag clicked

sprite.when_program_starts(generator_function, name='', no_refresh=False)

Works for: SpriteStage

Runs the code when the green flag is clicked, i.e. when the program starts.

generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.
when [space v] key pressed

sprite.when_key_pressed(key, generator_function, name='', no_refresh=False)

Works for: SpriteStage

Runs the code when a key is pressed.

key str
The key, e.g. "a", "1", "space", "left arrow", "right arrow", "up arrow", "down arrow" or "any" (any key). Upper and lower case do not matter.
generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.
when this sprite clicked

sprite.when_this_sprite_clicked(generator_function, name='', no_refresh=False)

Works for: SpriteStage

Runs the code when the sprite is clicked with the mouse.

generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.
when backdrop switches to [backdrop1 v]

sprite.when_backdrop_switches_to(backdrop, generator_function, name='', no_refresh=False)

Works for: SpriteStage

Runs the code when the stage switches to the given backdrop.

backdrop str
The name of the backdrop. Upper and lower case do not matter.
generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.
when [loudness v] > (10)

sprite.when_loudness_greater_than(value, generator_function, name='', no_refresh=False)

Works for: SpriteStage

Runs the code when the loudness of the microphone is greater than the given value.

More details

This is only a stub: the microphone is not supported, the loudness is always -1 and the code never runs.

value number
The loudness value that must be exceeded.
generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.
when [timer v] > (10)

sprite.when_timer_greater_than(value, generator_function, name='', no_refresh=False)

Works for: SpriteStage

Runs the code when the timer is greater than the given value.

More details

The code runs once each time the timer becomes greater than the value. It runs again after the timer has been reset.

value number
The number of seconds the timer must exceed.
generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.
when I receive (message1)

sprite.when_i_receive_message(message, generator_function, name='', no_refresh=False)

Works for: SpriteStage

Runs the code when the given message is broadcast.

message str
The name of the message. Upper and lower case do not matter.
generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.
broadcast (message1)

sprite.broadcast(message)

Works for: SpriteStage

Sends a message to all sprites and the stage. Every "when I receive" block with this message starts running. The script does not wait for them.

message str
The name of the message. Upper and lower case do not matter.
broadcast (message1) and wait

sprite.broadcast_and_wait(message)

Works for: SpriteStage

Sends a message to all sprites and the stage and waits until all scripts that receive it are finished.

message str
The name of the message. Upper and lower case do not matter.
when stage clicked

stage.when_stage_clicked(generator_function, name='', no_refresh=False)

Works for: Stage

Runs the code each time the stage is clicked.

generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.

Control ↑

wait (1) seconds

sprite.wait(secs)

Works for: SpriteStage

Waits the given number of seconds before the script continues. Other scripts keep running meanwhile.

secs number
The number of seconds to wait. Negative values are treated as 0.
stop [all v]

sprite.stop_all()

Works for: SpriteStage

Stops all scripts of all sprites and the stage, removes all clones, and stops all sounds.

stop [this script v]

sprite.stop_this_script()

Works for: SpriteStage

Stops the script that runs this block. The other scripts keep running.

create clone of (sprite v)

sprite.create_clone_of_sprite(sprite='_myself_')

Works for: SpriteStage

Creates a clone of a sprite. A clone is a copy that starts at the same position, with the same costume and variables.

More details

At most 300 clones can exist at the same time. Further clones are not created.

sprite str
The name of the sprite to clone. Use "_myself_" to clone the sprite that runs this block.
stop [other scripts in sprite v]

sprite.stop_other_scripts_in_sprite()

stage.stop_other_scripts_in_stage()

Works for: SpriteStage

Stops all other scripts of this sprite. The script that runs this block keeps running.

create clone of (myself v)

sprite.create_clone_of_myself()

Works for: Sprite

Creates a clone of this sprite. A clone is a copy that starts at the same position, with the same costume and variables.

More details

At most 300 clones can exist at the same time. Further clones are not created.

delete this clone

sprite.delete_this_clone()

Works for: Sprite

Deletes the clone that runs this block. A sprite that is not a clone is not deleted.

when I start as a clone

sprite.when_i_start_as_a_clone(generator_function, name='', no_refresh=False)

Works for: Sprite

Runs the code each time a clone of this sprite is created.

generator_function function
The function with the code to be executed.
name str
A name to distinguish code blocks using the same function.
no_refresh bool
If True, the code is executed in one go without screen refresh.

Sensing ↑

ask (What's your name?) and wait

sprite.ask_and_wait(question)

Works for: SpriteStage

Shows a question on the stage in a text box and waits until the user has answered it.

More details

The answer can be read with the answer block.

question str
The question to show to the user.
(answer)

sprite.answer()

Works for: SpriteStage

Returns the last answer that the user typed for an ask block.

key (space v) pressed?

sprite.key_pressed(key)

Works for: SpriteStage

Checks whether a key is pressed at this moment.

key str
The key, e.g. "a", "1", "space", "left arrow", "right arrow", "up arrow", "down arrow" or "any" (any key). Upper and lower case do not matter.
mouse down?

sprite.mouse_down()

Works for: SpriteStage

Checks whether a mouse button is pressed at this moment.

(mouse x)

sprite.mouse_x()

Works for: SpriteStage

Returns the horizontal position of the mouse pointer on the stage. The center of the stage is 0.

(mouse y)

sprite.mouse_y()

Works for: SpriteStage

Returns the vertical position of the mouse pointer on the stage. The center of the stage is 0.

(loudness)

sprite.loudness()

Works for: SpriteStage

Returns the loudness of the microphone.

More details

This is only a stub: the microphone is not supported, so the value is always -1.

(timer)

sprite.timer()

Works for: SpriteStage

Returns the time in seconds since the program started or since the timer was last reset.

reset timer

sprite.reset_timer()

Works for: SpriteStage

Resets the timer to 0.

set drag mode [draggable v]

sprite.set_drag_mode_draggable()

Works for: SpriteStage

Makes the sprite draggable: the user can move it with the mouse while the program runs.

set drag mode [not draggable v]

sprite.set_drag_mode_not_draggable()

Works for: SpriteStage

Makes the sprite not draggable: the user cannot move it with the mouse.

([x position v] of (sprite v))

sprite.x_position_of(sprite)

Works for: SpriteStage

Returns the x position of another sprite.

sprite str
The name of the sprite. If there is no such sprite, 0 is returned.
([y position v] of (sprite v))

sprite.y_position_of(sprite)

Works for: SpriteStage

Returns the y position of another sprite.

sprite str
The name of the sprite. If there is no such sprite, 0 is returned.
([direction v] of (sprite v))

sprite.direction_of(sprite)

Works for: SpriteStage

Returns the direction of another sprite in degrees. 90 is right, 0 is up.

sprite str
The name of the sprite. If there is no such sprite, 0 is returned.
([costume # v] of (sprite v))

sprite.costume_of(sprite)

Works for: SpriteStage

Returns the number of the current costume of another sprite (starting with 1).

sprite str
The name of the sprite. If there is no such sprite, 0 is returned.
([costume name v] of (sprite v))

sprite.costume_name_of(sprite)

Works for: SpriteStage

Returns the name of the current costume of another sprite.

sprite str
The name of the sprite. If there is no such sprite, 0 is returned.
([size v] of (sprite v))

sprite.size_of(sprite)

Works for: SpriteStage

Returns the size of another sprite in percent. 100 is the normal size.

sprite str
The name of the sprite. If there is no such sprite, 0 is returned.
([volume v] of (sprite v))

sprite.volume_of(sprite='_stage_')

Works for: SpriteStage

Returns the volume of the sounds of a sprite or of the stage, from 0 to 100.

sprite str
The name of the sprite, or "_stage_" for the stage. Defaults to the stage.
([variable v] of (sprite v))

sprite.get_variable_of(variable, sprite='_stage_')

Works for: SpriteStage

Returns the value of a variable of a sprite or of the stage.

variable str
The name of the variable.
sprite str
The name of the sprite, or "_stage_" for the stage. Defaults to the stage.
([backdrop # v] of (Stage v))

sprite.backdrop_of(stage='_stage_')

Works for: SpriteStage

Returns the number of the current backdrop (starting with 1). Only the stage has backdrops.

stage str
The name of the stage, "_stage_" by default. For a sprite, 0 is returned.
([backdrop name v] of (Stage v))

sprite.backdrop_name_of(stage='_stage_')

Works for: SpriteStage

Returns the name of the current backdrop. Only the stage has backdrops.

stage str
The name of the stage, "_stage_" by default. For a sprite, 0 is returned.
(current [year v])

sprite.current_year()

Works for: SpriteStage

Returns the current year.

(current [month v])

sprite.current_month()

Works for: SpriteStage

Returns the current month as a number, from 1 (January) to 12 (December).

(current [date v])

sprite.current_date()

Works for: SpriteStage

Returns the current day of the month, from 1 to 31.

(current [day of week v])

sprite.current_day_of_week()

Works for: SpriteStage

Returns the current day of the week as a number. 1 is Sunday, 2 is Monday and 7 is Saturday.

(current [hour v])

sprite.current_hour()

Works for: SpriteStage

Returns the current hour, from 0 to 23.

(current [minute v])

sprite.current_minute()

Works for: SpriteStage

Returns the current minute, from 0 to 59.

(current [second v])

sprite.current_second()

Works for: SpriteStage

Returns the current second, from 0 to 59.

(days since 2000)

sprite.days_since()

Works for: SpriteStage

Returns the number of days since 1 January 2000 (in UTC), including the fraction of the current day.

(username)

sprite.username()

Works for: SpriteStage

Returns the user name. pystage does not know the user name, so the result is always an empty text.

touching (mouse-pointer v)?

sprite.touching_mouse_pointer()

Works for: Sprite

Checks whether the sprite touches the mouse pointer.

touching (edge v)?

sprite.touching_edge()

Works for: Sprite

Checks whether the sprite touches the edge of the stage.

touching (sprite v)?

sprite.touching(sprite)

Works for: Sprite

Checks whether the sprite touches another sprite, the mouse pointer or the edge.

sprite str
The name of the sprite. Use "_mouse_" for the mouse pointer or "_edge_" for the edge of the stage.
touching color (color)?

sprite.touching_color(color)

Works for: Sprite

Checks whether the sprite touches a color on the stage.

color str or tuple
The color, e.g. "#ff0000" for red, or a tuple of red, green and blue values from 0 to 255.
color (color) is touching (color)?

sprite.color_is_touching(sprite_color, color)

Works for: Sprite

Checks whether a color of the sprite touches another color on the stage.

sprite_color str or tuple
The color of the sprite, e.g. "#ff0000" for red, or a tuple of red, green and blue values from 0 to 255.
color str or tuple
The color on the stage that is searched for, in the same format.
(distance to (mouse-pointer v))

sprite.distance_to_mouse_pointer()

Works for: Sprite

Returns the distance between the sprite and the mouse pointer in pixels.

(distance to (sprite v))

sprite.distance_to_sprite(sprite)

Works for: Sprite

Returns the distance between the sprite and another sprite in pixels.

sprite str
The name of the sprite. Use "_mouse_" for the mouse pointer. If there is no such sprite, 10000 is returned.

Operators ↑

pick random (1) to (10)

sprite.pick_random(start, end)

Works for: SpriteStage

Returns a random number between two numbers, both ends included. If both numbers are whole numbers, the result is a whole number too.

start number
The lowest possible number.
end number
The highest possible number. If it is lower than start, the two are swapped.
((10) / (2))

sprite.divide(a, b)

Works for: SpriteStage

Divides a by b.

More details

Like in Scratch, dividing by 0 gives Infinity, -Infinity or NaN instead of an error.

((10) mod (3))

sprite.modulo(a, b)

Works for: SpriteStage

Gives the remainder of dividing a by b.

More details

The remainder of a division, with the sign of the divisor like in Scratch. The modulo of 0 is NaN.

(join [apple] [banana])

sprite.join(string1, string2)

Works for: SpriteStage

Joins two texts into one.

(letter (1) of [world])

sprite.letter_of(letter, string)

Works for: SpriteStage

Gives one letter of a text.

letter int
The position of the letter, starting with 1.
string str
The text.
(length of [world])

sprite.length_of(string)

Works for: SpriteStage

Gives the number of letters of a text.

string str
The text.
<(a) > (b)>

sprite.greater_than(operand1, operand2)

Works for: SpriteStage

Checks whether the first value is greater than the second. Numbers are compared as numbers, texts alphabetically without regard to upper and lower case.

operand1 number or str
The first value.
operand2 number or str
The second value.
<(a) < (b)>

sprite.less_than(operand1, operand2)

Works for: SpriteStage

Checks whether the first value is less than the second. Numbers are compared as numbers, texts alphabetically without regard to upper and lower case.

operand1 number or str
The first value.
operand2 number or str
The second value.
<(a) = (b)>

sprite.equals(operand1, operand2)

Works for: SpriteStage

Checks whether two values are equal. Numbers are compared as numbers, texts without regard to upper and lower case.

operand1 number or str
The first value.
operand2 number or str
The second value.
<[apple] contains [a]?>

sprite.contains(string1, string2)

Works for: SpriteStage

Tells whether a text contains another text.

More details

Upper and lower case is ignored.

string1 str
The text to search in.
string2 str
The text to search for.
(round (3.5))

sprite.round(number)

Works for: SpriteStage

Rounds a number to the nearest whole number.

More details

Like in Scratch, .5 is always rounded up.

([abs v] of (-1))

sprite.math_function(operator, number)

Works for: SpriteStage

Calculates a mathematical function of a number.

operator str
The function: "abs", "floor", "ceiling", "sqrt", "sin", "cos", "tan", "asin", "acos", "atan", "ln", "log", "e ^" or "10 ^". The sine, cosine and tangent use degrees.
number number
The number to calculate the function of.

Variables and lists ↑

set (my variable) to (0)

sprite.set_variable(name, value)

Works for: SpriteStage

Sets a variable to a new value.

name str
The name of the variable.
value object
The new value, a number or a text.
(my variable)

sprite.get_variable(name)

Works for: SpriteStage

Returns the value of a variable.

name str
The name of the variable.
change (my variable) by (1)

sprite.change_variable_by(name, value)

Works for: SpriteStage

Changes the value of a variable by the given number. The variable must contain a number.

name str
The name of the variable.
value number
The number to add. Negative values make the variable smaller.
show variable (my variable)

sprite.show_variable(name)

Works for: SpriteStage

Shows the monitor of a variable on the stage, so that its value can be seen.

name str
The name of the variable.
hide variable (my variable)

sprite.hide_variable(name)

Works for: SpriteStage

Hides the monitor of a variable on the stage.

name str
The name of the variable.

sprite.get_list(name)

Works for: SpriteStage

The list itself.

More details

This is the real Python list, you can use it like any other list.

name str
The name of the list.
add [thing] to [my list v]

sprite.add_to_list(name, item)

Works for: SpriteStage

Adds an item to the end of a list.

name str
The name of the list. item The item, a number or a text.
item
delete (1) of [my list v]

sprite.delete_item_of_list(name, index)

Works for: SpriteStage

Deletes one item of a list.

name str
The name of the list.
index int or str
The position, starting with 1. Also possible: "last" and "random". With "all", all items are deleted.
delete all of [my list v]

sprite.delete_all_of_list(name)

Works for: SpriteStage

Deletes all items of a list.

name str
The name of the list.
insert [thing] at (1) of [my list v]

sprite.insert_at_list(name, item, index)

Works for: SpriteStage

Inserts an item into a list at a position.

name str
The name of the list. item The item, a number or a text.
item
index int or str
The position, starting with 1. Also possible: "last" and "random".
replace item (1) of [my list v] with [thing]

sprite.replace_item_of_list(name, index, item)

Works for: SpriteStage

Replaces an item of a list by another one.

name str
The name of the list.
index int or str
The position, starting with 1. Also possible: "last" and "random". item The item, a number or a text.
item
(item (1) of [my list v])

sprite.item_of_list(name, index)

Works for: SpriteStage

Gives one item of a list.

name str
The name of the list.
index int or str
The position, starting with 1. Also possible: "last" and "random".
(item # of [thing] in [my list v])

sprite.item_number_in_list(name, item)

Works for: SpriteStage

Gives the position of an item in a list.

name str
The name of the list. item The item, a number or a text.
item
(length of [my list v])

sprite.length_of_list(name)

Works for: SpriteStage

Gives the number of items in a list.

name str
The name of the list.
<[my list v] contains [thing]?>

sprite.list_contains(name, item)

Works for: SpriteStage

Tells whether a list contains an item.

name str
The name of the list. item The item, a number or a text.
item
show list [my list v]

sprite.show_list(name)

Works for: SpriteStage

Shows the list on the stage.

name str
The name of the list.
hide list [my list v]

sprite.hide_list(name)

Works for: SpriteStage

Hides the list from the stage.

name str
The name of the list.

Pen ↑

erase all

sprite.erase_all()

Works for: SpriteStage

Erases everything that the pens of all sprites have drawn on the stage.

stamp

sprite.stamp()

Works for: Sprite

Stamps a copy of the sprite's costume onto the stage. The copy stays there, even when the sprite moves.

pen down

sprite.pen_down()

Works for: Sprite

Puts the pen down. From now on, the sprite draws a line on the stage while it moves.

pen up

sprite.pen_up()

Works for: Sprite

Lifts the pen up. The sprite no longer draws while it moves.

set pen color to [#ff0000]

sprite.set_pen_color(color)

Works for: Sprite

Sets the color of the pen.

color str or tuple
The color, e.g. "#ff0000" for red, or a tuple of red, green and blue values from 0 to 255.
change pen (color v) by (10)

sprite.change_pen_hue_by(value)

Works for: Sprite

Changes the color (hue) of the pen by the given amount. The color goes from 0 to 100 and starts again at 0 after 100.

value number
The change of the pen color.
change pen (saturation v) by (10)

sprite.change_pen_saturation_by(value)

Works for: Sprite

Changes the saturation of the pen color by the given amount. Higher saturation makes the color more colorful.

value number
The change of the saturation, from 0 to 100.
change pen (brightness v) by (10)

sprite.change_pen_brightness_by(value)

Works for: Sprite

Changes the brightness of the pen color by the given amount. 0 is black and 100 is the brightest color.

value number
The change of the brightness, from 0 to 100.
change pen (transparency v) by (10)

sprite.change_pen_transparency_by(value)

Works for: Sprite

Changes the transparency of the pen color by the given amount. 0 is not transparent, higher values make the lines more see-through.

value number
The change of the transparency, from 0 to 100.
set pen (color v) to (50)

sprite.set_pen_hue_to(value)

Works for: Sprite

Sets the color (hue) of the pen. The color goes from 0 to 100 and starts again at 0 after 100.

value number
The new pen color, from 0 to 100.
set pen (saturation v) to (50)

sprite.set_pen_saturation_to(value)

Works for: Sprite

Sets the saturation of the pen color. Higher saturation makes the color more colorful.

value number
The new saturation, from 0 to 100.
set pen (brightness v) to (50)

sprite.set_pen_brightness_to(value)

Works for: Sprite

Sets the brightness of the pen color. 0 is black and 100 is the brightest color.

value number
The new brightness, from 0 to 100.
set pen (transparency v) to (50)

sprite.set_pen_transparency_to(value)

Works for: Sprite

Sets the transparency of the pen color. 0 is not transparent, higher values make the lines more see-through.

value number
The new transparency, from 0 to 100.
change pen size by (1)

sprite.change_pen_size_by(value)

Works for: Sprite

Changes the thickness of the pen by the given amount. The pen is at least 1 thick.

value number
The change of the pen thickness. Negative values make the pen thinner.
set pen size to (1)

sprite.set_pen_size_to(value)

Works for: Sprite

Sets the thickness of the pen. The pen is at least 1 thick.

value number
The new pen thickness.

PyStage extras ↑

Commands that Scratch does not have as blocks: loading costumes and sounds, creating variables, starting the program and more.

sprite.add_sound(name)

Works for: SpriteStage

Loads a sound file, so that the sprite or stage can play it.

More details

Sounds are also loaded automatically when they are played for the first time.

name str
The name of the sound file, e.g. "pop.wav". The file must be in the project folder.

sprite.set_name(name)

Works for: Sprite

Sets the name of the sprite. Other blocks can refer to the sprite by this name.

name str
The new name of the sprite.

stage.add_a_sprite(costume='default')

Works for: Stage

Adds a new sprite to the stage and returns it. The sprite is shown with the given costume.

More details

The name of the sprite is "Sprite" for the default costume, otherwise the name of the costume.

costume str
The name of the image file for the sprite's costume, e.g. "cat.png". "default" is the standard costume of pystage.

sprite.create_variable(name, value=0, all_sprites=True)

Works for: SpriteStage

Creates a new variable. The variable can be used with the variable blocks and shown as a monitor.

name str
The name of the variable. It must not exist yet.
value object
The initial value of the variable. The default is 0.
all_sprites bool
If True, the variable is shared by the stage and all sprites. If False, it belongs to this sprite only.

sprite.create_list(name, values=None, all_sprites=True)

Works for: SpriteStage

Create a list.

name str
The name of the list.
values list
The initial items of the list.
all_sprites bool
If True, the list can be used by the stage and all sprites. If False, it belongs to this sprite only.

sprite.set_monitor_position(name, x, y)

Works for: SpriteStage

Sets the position of the monitor of a variable on the stage.

name str
The name of the variable.
x number
The horizontal position of the upper left corner of the monitor. The center of the stage is 0.
y number
The vertical position of the upper left corner of the monitor. The center of the stage is 0.

sprite.set_list_monitor_position(name, x, y, width=None, height=None)

Works for: SpriteStage

Set position and size of the list shown on the stage.

name str
The name of the list.
x int
Left border.
y int
Upper border.
width int
Width in pixels, automatic if not given.
height int
Height in pixels, automatic if not given.

sprite.set_monitor_style_large(name)

Works for: SpriteStage

Shows the monitor of a variable in the large style, with a big display of its value.

name str
The name of the variable.

sprite.add_costume(name, center_x=None, center_y=None, factor=1)

Works for: Sprite

Adds a costume (an image) to the sprite. The costume is added at the end of the costume list.

name str
The name of the image file, e.g. "cat.png". The file must be in the project folder.
center_x number
The horizontal position of the costume's center in the image, in pixels. If not given, the center of the image is used.
center_y number
The vertical position of the costume's center in the image, in pixels. If not given, the center of the image is used.
factor number
The scaling of the image. 1 keeps the original size, 2 shows it at double size.

sprite.set_monitor_style_normal(name)

Works for: SpriteStage

Shows the monitor of a variable in the normal style, with a small display of its value.

name str
The name of the variable.

sprite.replace_costume(index, name, center_x=None, center_y=None, factor=1)

Works for: Sprite

Replaces an existing costume of the sprite with another image.

index int
The number of the costume to replace, starting with 1.
name str
The name of the new image file.
center_x number
The horizontal position of the costume's center in the image, in pixels. If not given, the center of the image is used.
center_y number
The vertical position of the costume's center in the image, in pixels. If not given, the center of the image is used.
factor number
The scaling of the image. 1 keeps the original size.

sprite.set_monitor_style_slider(name, minimum=0, maximum=100, integer=True)

Works for: SpriteStage

Shows the variable as a slider that can be dragged with the mouse.

name str
The name of the variable.
minimum number
The lowest value of the slider. Like in Scratch, the default is 0.
maximum number
The highest value of the slider. Like in Scratch, the default is 100.
integer bool
If True, the slider only sets whole numbers, otherwise numbers with two decimals.

sprite.insert_costume(index, name, center_x=None, center_y=None, factor=1)

Works for: Sprite

Inserts a costume (an image) into the sprite's costume list at the given position.

index int
The position where the costume is inserted, starting with 1.
name str
The name of the image file, e.g. "cat.png".
center_x number
The horizontal position of the costume's center in the image, in pixels. If not given, the center of the image is used.
center_y number
The vertical position of the costume's center in the image, in pixels. If not given, the center of the image is used.
factor number
The scaling of the image. 1 keeps the original size.

sprite.show_monitor(reporter)

Works for: SpriteStage

Show the monitor of a value, like the checkbox next to a block in Scratch.

reporter str
What to show: "x position", "y position", "direction", "costume number", "costume name", "size", "volume" (sprites and stage), "backdrop number", "backdrop name" (stage), "answer", "loudness", "timer", "year", "month", "date", "day of week", "hour", "minute", "second" or "username".

sprite.hide_monitor(reporter)

Works for: SpriteStage

Hides the monitor of a value.

reporter str
The value, e.g. "x position", "size", "timer" or "year". The same values as for show_monitor are allowed.

sprite.set_value_monitor_position(reporter, x, y)

Works for: SpriteStage

Set the position of the monitor of a value.

reporter str
The value, see show_monitor.
x int
Left border (Scratch coordinates).
y int
Upper border (Scratch coordinates).

sprite.set_value_monitor_style(reporter, style='normal')

Works for: SpriteStage

Set the style of the monitor of a value.

reporter str
The value, see show_monitor.
style str
"normal" or "large".

stage.add_backdrop(name, center_x=None, center_y=None, factor=1)

Works for: Stage

Adds a backdrop (an image) to the stage. The backdrop is added at the end of the backdrop list.

name str
The name of the image file, e.g. "forest.png". The file must be in the project folder.
center_x number
The horizontal position of the image's center, in pixels. If not given, the center of the image is used.
center_y number
The vertical position of the image's center, in pixels. If not given, the center of the image is used.
factor number
The scaling of the image. 1 keeps the original size.

stage.play()

Works for: Stage

Starts the program. The stage is shown and all scripts run until the window is closed.

More details

Call this once, at the end of the program.

stage.replace_backdrop(index, name, center_x=None, center_y=None, factor=1)

Works for: Stage

Replaces an existing backdrop of the stage with another image.

index int
The number of the backdrop to replace, starting with 1.
name str
The name of the new image file.
center_x number
The horizontal position of the image's center, in pixels. If not given, the center of the image is used.
center_y number
The vertical position of the image's center, in pixels. If not given, the center of the image is used.
factor number
The scaling of the image. 1 keeps the original size.

stage.insert_backdrop(index, name, center_x=None, center_y=None, factor=1)

Works for: Stage

Inserts a backdrop (an image) into the stage's backdrop list at the given position.

index int
The position where the backdrop is inserted, starting with 1.
name str
The name of the image file, e.g. "forest.png".
center_x number
The horizontal position of the image's center, in pixels. If not given, the center of the image is used.
center_y number
The vertical position of the image's center, in pixels. If not given, the center of the image is used.
factor number
The scaling of the image. 1 keeps the original size.