Writing Blocks code in instructions

You can show Blocks in project instructions by writing a small amount of text inside a Markdown code block. The editor turns this text into blocks.

In most cases, you can write the words that you see Blocks editor and add brackets around its inputs.

Basic example

Write this in your instructions:

```blocks
when green flag clicked
repeat (10)
  move (10) steps
  turn cw (15) degrees
end
say [Finished!] for (2) seconds
```

This displays a stack of blocks. Each new line becomes a new block. Indenting the blocks inside repeat is optional, but makes the text easier to read.

Start and finish a block section

Put three backticks followed by blocks before your blocks. Put three more backticks after them:

```blocks
move (10) steps
```

The word blocks must be lower case. Do not put spaces between them and the backticks.

Write one block on each line

For a block with no inputs, copy the words shown on the block:

show
next costume
erase all

For several connected blocks, put each block on a new line:

show
say [Hello!] for (2) seconds
hide

Add inputs

An input is a value that a learner can type or choose on a block. The brackets tell the instructions what shape the input should have.

Number inputs: ( )

Put numbers inside round brackets:

move (10) steps
wait (0.5) seconds
go to x: (100) y: (-50)

Leave the brackets empty to show an empty number input:

move () steps

Text inputs: [ ]

Put words inside square brackets:

say [Hello!]
ask [What is your name?] and wait

Leave the brackets empty to show an empty text input:

say []

Drop-down menus: add v

Add a space and a lower-case v before the closing bracket to show a drop-down arrow:

go to [random position v]
point towards [mouse-pointer v]
set [score v] to (0)

Most menus use square brackets. A menu which fits into a round input uses round brackets:

([sqrt v] of (9))

The v is a letter, not an arrow symbol.

Colour inputs: [#colour]

Write a hexadecimal colour inside square brackets:

touching color [#ff0000]?
set pen color to [#0066ff]

A hexadecimal colour starts with # and has six characters which describe its red, green, and blue values. If you do not know the code, an online colour picker can provide it.

Put one block inside another

Round reporter blocks, such as variables and calculations, also use round brackets:

say (score)
change x by ((speed) * (2))
wait ([sqrt v] of (9)) seconds

Add another pair of round brackets each time one round block is placed inside another.

Diamond-shaped condition blocks use angle brackets, < >:

<mouse down?>
<(score) > (10)>
<<touching [mouse-pointer v]?> and <mouse down?>>

A condition can be placed inside a control block:

wait until <mouse down?>

Write loops and decisions

Blocks such as repeat, forever, and if wrap around other blocks. Write the inside blocks on the following lines, then write end on its own line.

repeat (4)
  move (50) steps
  turn cw (90) degrees
end

Use else on its own line for an if then else block:

if <touching [mouse-pointer v]?> then
  say [You found me!]
else
  say [Keep looking]
end

Always writing end is a useful habit. It is especially important when more blocks follow the loop or decision:

repeat (3)
  change size by (10)
end
say [Finished!]

Indentation is helpful for people reading the Markdown but it does not change the blocks. Two spaces are enough.

Events, turns, and symbols

Some blocks contain a picture rather than a word. The instructions accepts short text in its place.

when green flag clicked
turn cw (15) degrees
turn ccw (15) degrees

Here, cw means clockwise and ccw means anticlockwise. You can also write turn right and turn left.

Add comments

Put two forward slashes after a block to attach a comment:

move (10) steps // Move away from the edge

Put the comment on its own line for a separate comment:

// Set up the game
set [score v] to (0)

Variables and lists

Write a variable's name inside round brackets when you want its value:

say (score)
change [score v] by (1)

Use square brackets and a drop-down arrow when the block asks you to choose a variable or list:

set [score v] to (0)
add [apple] to [shopping list v]

A list reporter may need :: list so that it is not mistaken for a variable:

(items :: list)

Most instructions will not need this extra label.

My Blocks (custom blocks)

Start a custom block definition with define. Put each input name inside round brackets:

define draw square (size)
repeat (4)
  move (size) steps
  turn cw (90) degrees
end

After defining it, write the custom block in the same way that it is used in the Blocks editor:

draw square (50)

Keep the definition and its uses in the same block section when possible. This helps the instructions recognise the custom block and its inputs.

Show unfinished code

Use three full stops when an instruction only needs to show part of a script:

when green flag clicked
...

Inside a control block:

if <(score) = (10)> then
  ...
end

Use a bracket as ordinary text

Brackets normally start or finish an input. Put a backslash before a bracket when it should appear as part of the text:

say [Use the close bracket \] here]

The backslash tells the instructions not to treat that bracket as the end of the input.

Common problems

The Markdown appears as text instead of blocks

Check that:

• the opening line is exactly three backticks followed by blocks
• the closing line contains exactly three backticks
• the opening and closing lines are each on their own line

A block has the wrong colour or shape

Check the block's wording against the Blocks editor. Pay particular attention to:

• missing words or punctuation
• round brackets ( ) used instead of square brackets [ ]
• a missing v in a drop-down menu
• a missing end after a loop or decision

If the wording is intentionally different, add a category with ::.

Several blocks appear as one incorrect block

Put every block on a separate line.

A loop contains too many blocks

Add end on its own line where the loop or decision should finish.

A drop-down appears as an ordinary text box

Add a space and v before the closing bracket, for example [mouse-pointer v].

Quick reference

A larger example

```blocks
when green flag clicked
set [score v] to (0)
ask [What is your name?] and wait
say (join [Hello, ] (answer)) for (2) seconds
repeat until <(score) = (10)>
  if <touching [Star v]?> then
    change [score v] by (1) // Award one point
  end
  move (10) steps
  turn cw (15) degrees
end
say [You won!] for (2) seconds
```