Use Python with Sprites

By using Python with Sprites, you may:

  • Learn Python with your previous Scratch knowledge
  • Write big programs (like algorithms) easily
  • Use complex data structures like dictionaries to do things that are not easy in Scratch.

In mBlock 5, Python can almost do whatever Scratch can do.
You can control the movement and appearance of your sprite. You may also draw pictures.
Using broadcasting and Sprite Variables, Python code can interact with the Python or Block code in other sprites.

Start Using Python

Start using Python by switching the programming mode from "Blocks" to "Python" (Insert Pics)

Note: please make sure that a sprite, not a hardware device, is currently selected. (Insert Pics)

This is an example of the Python code used in a Sprite.

from mblock import *


for i in range(5):

When the code is complete, click "Run" to run your Python code. (Insert Pic)

Convert Blocks to Python

(Insert Pic)

Moving a Sprite


Tell the Sprite to move forward for a certain distance towards
the current facing direction.



Tell the Sprite to move backward for a certain distance from the current facing direction.



Tell the sprite to turn right for certain degrees.



Tell the Sprite to turn left for certain degrees.



Use the "direction" attribute to get the current facing direction of the Sprite

sprite.direction = 90 # set the facing direction to 90 degrees
sprite.direction = sprite.direction + 10 # tell the sprite to rotate clockwise for 10 degrees
print(sprite.direction) # now the facing direction will be 100


Tell the Sprite to face another sprite (the sprite_name is a string)

sprite.towards('mouse') # 朝向鼠标指针


Tell the Sprite to bounce when it touches the edge of the stage.

while True:


Set the rotation mode of the Sprite.
"mode" is a boolean value, could be one of these:

  • 'left-right': the image of the Sprite only turns left or right
  • 'all-around' or True: the Sprite image could face any direction
  • 'none' or False: the Sprite image will not rotate.

Position and Coordinates

goto(x, y) | goto(place)

Tell the sprite to move to a certain (x, y) coordinate.
x, y is numbers. You may use the following special string value:

  • "random": move to a random location on the stage.
  • "mouse": move to the location of the mouse.
sprite.x # =30
sprite.y # =0
sprite.goto("random") # move to a random location
sprite.goto("mouse") # move to the mouse pointer

glide(x, y, duration=5) | glide(location, duration=5)

Tell the Sprite to slide to a specific location in a certain duration.
You may also use the following string to denote the special location:

  • "random": a random location on the stage
  • "mouse": the location of the mouse pointer
sprite.glide(30, 60, 5) # Tell the sprite to move to (30, 60) in 5 seconds
sprite.glide("random", 2) # move to a random location in 2 seconds
sprite.glide("mouse", 2) # move to the pointer in 2 seconds

coordinate of the sprite: x, y

Get the coordinate of the Sprite, or set the (x, y) coordinate of the Sprite on the stage

sprite.x # get the x location of the Sprite
sprite.y # get the y location of the Sprite
sprite.x = 50 # set the x location of the Sprite to 50
sprite.y = 60 # set the y location to 60
sprite.y = sprite.y + 10 # increase the y coordinate by 10, that means move the Sprite up for 10
print(sprite.x) # print the x location of the sprite (50 in this case)
print(sprite.y) # print the y location of the sprite (70 in this case)


say(text, duration=0)

Tell the Sprite to "say" some text.
If the duration is not specified, the text box will not disappear;
otherwise, it will disappear after a certain duration.

sprite.say("nice to meet you", 5)
sprite.say("hello world")

think(text, duration=0)

Tell the Sprite to "think" for a certain text.
If the duration is not specified, the text box will not disappear;
otherwise, it will disappear after a certain duration.

sprite.think("nice to meet you", 5)
sprite.think("hello world")


Hide the sprite



Show the sprite


Change the costume of the sprite. The costume_name must exist in the Sprite, otherwise nothing will happen.



Switch the costume of the sprite to the next costume.



Switch the backdrop of the Stage. the background_name must exist in the projects, otherwise nothing will happen.



Switch the backdrop to the next backdrop


set_effect(effect, value)

Set the effect strength to a certain value. The effect could be one of these:

  • color
  • fisheye
  • whirl
  • pixelate
  • mosaic
  • brightness
  • ghost
sprite.set_effect("color", 10) # Set the color value to 10

change_effect_by(effect, value)

Increase the effect strength by a certain value. The effect could be one of these:

  • color
  • fisheye
  • whirl
  • pixelate
  • mosaic
  • brightness
  • ghost
sprite.change_effect_by("color", 10) # Increase the "color" effect by 10


Clear all the Sprite Effects.



Set or get the size proportion of the Sprite
100 is the original size (100%) of the Sprite.

sprite.size = 200 # enlarge the sprite to its 200%
sprite.size = sprite.size + - 50 # shrink the sprite by 50%
print(sprite.size) # print the proportional size of the sprite, 150 in this case

Play Sound


Play a sound effect. The sound effect name must exist in the project,
otherwise nothing will happen"meow") # play the "meow" sound


Play a sound effect, and run next statement when it is done.
The sound effect name must exist in the project, otherwise nothing will happen

sprite.play_until_done("meow") # play the "meow" sound


Stop playing all the sound


play_drum(instrument_number, beats)

Play a drum beat. Instrument number ranges from 1 to 18.
The "beats" refers to the duration of the drum beat.

sprite.play_drum(1, 0.25)


Stop playing sound for a certain beat.

play_note(note_number, beats=0.25)

Play a musical note. The note_number is a integer (MIDI number)
The higher the number, the higher the pitch.
"beats" is the duration of the sound.

sprite.play_note(60, 0.25) # play a "C" note in the third level


Set the current instrument. The instrument number ranges from 1 to 21. TODO: Table of instruments

sprite.set_inst(1) # set the musical instrument to piano

set_sfx(sound_effect_name, value)

Set the value of the sound effect.

sprite.set_sfx('PITCH', 10) # set the value of the sound effect as 10

change_sfx_by(sound_effect_name, value)

Change the value of the sound effect.

sprite.change_sfx_by('PITCH', 10) # increase the value of the sound effect by 10


Clear all sound effects.

sprite.clear_sfx() # clear all sound effects


Use volume to get or change the sound volume.
The volume value is a number ranged from 1 to 100.

sprite.volume = 50 # set the volume to 50
sprite.volume = sprite.volume + 10 # change the volume by 10%
print(sprite.volume) # 60

set_tempo(beats_per_minute) | change_tempo_by(beats_per_minute)

Use the tempo to set beat-per-minute(bpm) of music notes and sound effects.


Turtle Graphics


Put down the pen. A trail will be drawn by the sprite when the pen is down.



Lift up the pen. No trail will left behind when the Sprite moves then.



Leave an image of the sprite at the current position, like using a stamp.


pencolor(color) | pencolor(red, green, blue)

Change the color of the pen. The color could be:

  1. One of the follow strings: "red", "orange", "yellow", "green", "cyan", "blue", "purple", "black", "white", "grey"
  2. Hex code start with "#", like "#FF0000"
  3. A tuple of RGB value
  4. RGB values as parameters
sprite.pencolor(255, 0, 0) # 效果是相同的

pencolor_effect(effect_name, value)

set the pen effect (0-100)
the effect_name could be a string of:

  • "hue"
  • "saturation"
  • "brightness"
  • "transparency"
sprite.pencolor_effect("hue", 60)

change_pencolor_effect_by(effect_name, value)

Change the pen effect (0-100)
the effect_name could be a string of:

  • "color"
  • "saturation"
  • "brightness"
  • "transparency"
sprite.change_pencolor_effect_by("hue", 10)


change the shade value of the pen color.



Clear everything in the canvas drawn by the sprite.



Set the size of the pen.



Change the pen size by a certain value.

sprite.change_pensize_by(1) # increase the pen size by 1

Use Events

You can use events in Python to interact with the keyboard or the mouse
by adding a mark("decorator") before the function:

from mblock import *

@event.greenflag # the following function will run when the green flag is clicked
def on_green_flag(): # you may choose your own function name
    print("绿旗被按下了") # here put the code that will run after the green flag is clicked.


when the green flag is clicked/tapped

def on_green_flag():
    print("green flag is clicked!")


When a certain key on the keyboard is pressed, fire the event. The key_name could be:
"a", "A", "1", "enter", "space", "backspace".

def on_space_key():
    print("the space key is pressed")


Trigger the event when the Sprite is clicked.
mousedown and mouseup might be added in the future.

def on_clicked():
    print("the sprite is clicked")


When the backdrop is set to the certain backdrop, trigger this event.

def on_backdrop_enter():
    print("the backdrop is switched to Party")

@when_greater_than(parameter_name, value)

when a parameter with the certain name is greater than a value, trigger this event.
the parameter name could be:

  • "TIMER": the internal timer of Scratch
  • "VOLUME"(not implemented yet): the microphone volume.
@event.when_greater_than("timer", 10)
def on_backdrop_enter():
    print("10 seconds has been passed")


broadcast an event to the mBlock system.



when an event with a certain event_name is received, trigger the event.

def when_game_start():
    print("the game has been started")

Global Variables

You can use global variables to communicate with other sprites' code
(whether it is in blocks or Python)
You can even use Python codes to communicate with robots or other devices.

set_variable(variable_name, value)

Set the value of a Scratch block variable.
The variable must exist in the block editor;
otherwise nothing will happen (other than producing a warning in the console).

sprite.set_variable("score", 50)


Get the value of the variable.
If the variable name does not exist, return None.


Clone Sprites and Flow Control


Clone a sprite.
Returns the cloned sprite (Sprite Object)
(Not implemented yet) If a Sprite name is not provided, clone the sprite itself.

sprite.clone() # clone myself
sprite.clone("Panda") # clone a panda sprite


If the sprite is a clone, delete myself.


stop_all() / stop_this() / stop_other()

Stop all sprites/(not implemented yte)stop the scripts in this sprite/(not implemented yte)stop the scripts in other sprites

sprite.stop_all() # stop all sprites on the stage

Basic Inputs and Outputs


Print some content to the console at the bottom of the Python editor. Used to debug.

print("hello world")


Prompt the user to input text at the stage.

name = sprite.input("what's your name?")
sprite.say("your name is:" + name)

Sprite Properties


Tell if the Sprite is touching other Sprites, the mouse, or the edge of the stage.
The result is True of False

print(sprite.touching("Panda")) # True if the Sprite is touching the "Panda" sprite
print(sprite.touching_mouse()) # True if the Sprite is touching the mouse pointer
print(sprite.touching_edge()) # True if the Sprite is touching the edge of the stagew

touching_color(color) | touching_color(red, green, blue) | touching_color(sprite_color, screen_color)

Tell if the Sprite is touching another color. The color could be:

  1. Hex values start with "#", like "#FF0000"
  2. A Tuple of RGB values.
  3. RGB values in numbers

The result is True of False

print(sprite.touching_color("#ff0000")) # Tell if the sprite is touching the red color
print(sprite.touching_color(255, 0, 0)) # the same
color = (255, 0, 0)
print(sprite.touching_color(color)) # the same
print(sprite.touching_color("#ff0000", "#00ff00")) # Tell if the red part of the sprite is touching the green part of the stage.


Get the distance from the Sprite to the another Sprite or the mouse

sprite.distance_to('_mouse_') # get the distance from the Sprite to the mouse


Tell if a certain key is pressed(returns True or False) Examples of key names: "a", "A", "1", "enter", "space", "backspace"

print(sprite.is_keypressed("space")) # When the space key is pressed, return True.


Tell whether the mouse is down. Return True or False.

print(sprite.is_mousedown()) # 若执行当时鼠标被按下,返回True

Sprite Properties

A Sprite also has the following properties:

  • mousex: the mouse's x coordinate on the stage
  • mousey: the mouse's y coordinate on the stage
  • loudness: the loudness of the microphone
  • timer: the current value of the timer
  • current(unit): get the component of current time. "unit" could be: year | month | date | day_of_week | hour | minute | second: the current time
  • days_since_2000: days passed since 2000
print("%d, %d" % (sprite.mousex, sprite.mousey)) # output the mouse's coordinate
print(sprite.loudness) # output the current loudness
print(sprite.timer) # output the seconds from the timer
print("%d-%d-%d %d:%d:%d" % (sprite.current('year'), sprite.current('month'), sprite.current('date'), sprite.current('hour'), sprite.current('minute'), sprite.current('second')))
print("day of week: ", sprite.current('day_of_week')) # output the current day of the week
print("days since 2000", sprite.days_since_2000)


reset the timer

print(sprite.timer) # output zero, since the timer has been reset.

results matching ""

    No results matching ""