Basic syntax

Scratch commands are specified using the text equivalent (see example below).

Find a detailed reference on our Docs page.

                                when flag clicked
move (10) steps
say (hello) for (2) seconds

Specifying values

Values are specified with round brackets, for example

                                set x to (100)


Conditions are specified used angled brackets <> for example

                                if <mouse down> then
  change x by (10)

Drop down fields

Drop down fields are specified with square brackets [] regardless of whether they appear on the Scratch block with square or rounded corners. The image will have the correct corners depending on the block, for example.

                                go to [random position]


When indenting use either two spaces or a tab for each level of indentation. It is important to be consistent with your indentation otherwise it will create issues when the code is being parsed.

This code uses two spaces for each level of indentation

                                repeat (4)
  move (10) steps
  if <key [space] pressed> then
    turn right (90) degrees

Reporter blocks

Reporter blocks are specified by placing the name of the block in any value field.

For custom variables prefix them with the myvar! directive so that they will be displayed correctly.

                                y position

Greater than comparison

The greater than comparison is specified as "gt" and not ">"

                                repeat until <(x position) gt (100)>
  move (10) steps

Less than comparison

The Less than comparison is specified with "lt" instead of "<"

                                if <(y position) lt (-140)> then
  go to [random position]

Blocks with graphics

Scratch blocks with graphics are specified as shown in the code below. The text ":flag", ":right" and ":left" are automatically replaced with the the corresponding graphic.

                                when flag clicked
turn right (90) degrees
turn left (-20) degrees

Specifying colors

When needing to specify colors simply state the Color, Saturation and Brightness values as shown in the code. Students can use the values to recreate the desired color.

                                if <touching color (c10 s20 b100)> then

Mystery directive

The Mystery directive is a great way to tests student's understanding of the material being taught.

Value fields, condition fields and entire blocks can be left blank by using the "mystery!" directive.

                                if <mystery! touching color (c10 s20 b100)> then

Empty C blocks

If presenting the material using an iterative approach or to tests student's knowledge you leave a space where a block would have been by using the "space" instruction.

                                if <key [space] pressed?> then
  move (10) steps

Highlighting a block

Blocks can be highlighted by prefixing them with the "highlight" directive. The block will be outlined with a black dashed line.

                                when I start as a clone
go to x (pick random (-235) to (235)) y (170)
repeat until < (yposition) lt (-170)>
  highlight!change y by (-5)
delete this clone

Auto hints

Auto hints list the block categories of the blocks used to build an instruction. This is very useful when the color option is "Black & White" and students may need assistance locating the blocks

To enable Auto Hints just tick the check box on the convert options

                                when flag clicked
go to x: (0) y: (0)
pen down
repeat (4)
  move (100) steps
  turn right (90) degrees

Manual hints

Manual hints can be used to provide special instructions to students on a per block basis.

After the block text simple append a tilda followed by the desired text e.g. "move (10) steps ~ what happens when the value is increased"

Note that when provided manual hints always override Auto HInts.

                                when flag clicked
set size to (70) %
  create clone of [myself]
  wait (1) seconds ~ Is this long enough?

Converting multiple scripts

Multiple scripts can be converted simultaneously by separating the scripts in the editor with 5 or more dashes ":-----"

When multiple scripts are converted a "zip" file will also be produced containing the converted images.

                                when flag clicked
create clone of [myself]
when I start as a clone
go to x (-240) y (0)

Specify the filename for the image

An image name can be specified for each script by preceding the script with a filename directive following two dashes, for example "-- filename: figure_1.jpg":

NOTE: We support both ".jpg" and ".png" extensions. Images generated with a ".png" extension will have a transparent background automatically.

                                -- filename: apple_sprite.png
when flag clicked
set [Score] to (0)
set [Apples Missed] to (0)
set size to (70) %
  create clone of [myself]
  wait (1) seconds


MyBlocks can be defined using the "define!" directive. This must be the first block in the script

The defined block can then be used in subsequent scripts (using the multi-script separator).

NOTE:The defined block with not validate in the editor and will appear as an error unless you mark it with the "myblock!" directive. It will however convert successfully.

                                define!create (x) balls
repeat (x)
  create clone of [Ball]
when flag clicked
myblock!create (10) balls

Vanity blocks

Vanity blocks can be specified by prefixing the line with the "vanity!": directive.

The system will choose a random color from the block categories (not including the extensions). If you want the block to be a specific block category color you can append the category to the vanity directive for example "vanity-looks!": or "vanity-motion!":

                                vanity!happy birthday

micro:bit display []

To specify what to display use an "1" for on and and "0" for off in a row by row (row 1 to row 5) configurations separated by commas for example display [01010,10101,10001,01010,00100]
                                display [01010,10101,10001,01010,00100]

Category directives

Many of the blocks in the MakeyMakey, micro:bit, Lego EV3, Lego Boost, Lego WeDo 2.0 and Force & Acceleration extensions share identical signatures which make it impossible to differentiate them unless a category directive is provided. All the blocks listed below should be specified with a category directive e.g. "boost!" otherwise the wrong block may be matched.

makey!when [SPACE] key pressed

microbit!when [moved]
microbit!when tilted [any]
microbit!tilt angle [front]


boost!motor [A] position
boost!when tilted [any]
boost!tilt angle [up]
boost!set light color to (50)

wedo!set light color to (50)
wedo!when tilted [any]
wedo!tilted [any]
wedo!tilt angle [up]

fa!when [shaken]
fa!when tilted [any]
fa!tilted [any]
fa!tilt angle [front]

                                boost!set light color to (50)
wedo!set light color to (50)

Scale factor

When creating blocks to print for unplugged activities. Use the scale_factor instruction to ensure that all blocks have the same size connectors. The scale factor can be specified on the first script and all subsequent scrips, in a multi-script conversion, will use the same scale factor. Prefix the script with "-- scale_factor: " to specify the desired scale factor.

If you are unsure what scale factor to use. Convert the longest block first and then check the scale factor it was created with on the My Account/Conversions page and use that scale factor on subsequent conversions.

The scale factor instruction can only be used if you have signed up for the Educator Plus plan.

                                -- scale_factor: 3
when flag clicked