Scripting Tutorial

This is an informal guide to scripting in Blocksworld.

Note: The terminology used in this page might not be official.

Scripting window
When a block is selected, its scripting window is visible (or just the side tab that can be dragged to move the window). Tiles from the actions, textures and colors tabs of the build panel can be dragged into the scripting window.

Each block's script contains rows (or lines) of actions in the following form:
 * actions => actions
 * actions => actions

(where => stands for "Does") Each line always has Does.

Actions placed after "Does"
The script "does" the actions after "=>" in each line.
 * For example, a block with the script
 * => Sparkle
 * just sparkles continuously.

If there are multiple actions in the same line, the actions happen one at a time in sequential order.
 * For example, a block with the script
 * => Sparkle, Red (color), Hero tag, Blue (color), Speak ("Hello!")
 * sparkles for a few seconds, then instantly turns red, then is tagged Hero for an instant, then instantly turns blue, then shows a speech bubble.

After the speech bubble disappears, all the actions happen again (and continue repeating). Note that in this case, the block will not sparkle and speak at the same time (and it will not be Hero tagged while sparkling or speaking).

The same line of script cannot stop half way (unless the model shuts off), and it can only start happening again after the whole line of actions finishes. (That means the line will never overlap with itself.)

When there are multiple lines of actions, each line is checked in order from top to bottom.
 * For example, a block with the script
 * => Red (color)
 * => Blue (color)
 * => Green (color)
 * instantly turns Red, then instantly turns Blue, and then instantly turns Green.

In fact, you won't see the red or blue because the next color always replaces the one before it. Every time the script finishes, the block is just green.

However, actions in multiple different lines of script can happen simultaneously.
 * For example, a block with the script
 * => Sparkle
 * => Speak ("Hello!")
 * will sparkle and speak at the same time.

Actions placed before "Does"
In this guide, I'll also refer to the actions before the "=>" as "conditions".

For the actions after "Does" to happen, all the conditions must be satisfied (i.e. true).
 * For example, a block with the script
 * Blue (color) => Speak ("I'm blue")
 * will only speak when its color is blue.

When there are multiple conditions, all of them must be true at the same time for the line to happen.
 * For example, a block with the script
 * Blue (color), Red (color) => Speak ("I'm red and blue")
 * will never speak because Blocksworld doesn't allow blocks to have more than one color. (And only the primary color of the block is used in scripts)

Some actions can't be conditions, some can only be conditions, and some can be either.

In blocksworld, there are many situations where the order of the lines in the script doesn't matter. In the following example (and in the three colors example above), the order does matter:
 * Consider a block with the script
 * => Red (color)
 * R button => Blue (color)
 * Red (color) => Signal ("R not pressed")
 * Blue (color) => Signal ("R pressed")
 * What is happening in each line:
 * The block turns red.
 * IF the R button is being pressed, the block turns blue.
 * IF the block is red, the "R not pressed" signal is broadcasted.
 * IF the block is blue, the "R pressed" signal is broadcasted.
 * Since the block cannot be both red and blue, a signal is always being broadcasted at any one time. (Either the R button is being pressed or it isn't.)
 * Note: The last two lines can be in any order, but the first two lines must be in that order and before the third and fourth lines.

Summary

 * For each line: IF all the conditions are true, THEN the actions start happening in sequential order.
 * The line can't happen again until it is finished.


 * The actions in multiple different lines can happen simultaneously.
 * Different scripts happen simultaneously.

Other notes

 * A block with the script
 * On Play => Red (color)
 * Red (color) => Blue (color)
 * Blue (color) => Red (color)
 * will rapidly alternate between being red and blue.

The best way to get the hang of Blocksworld scripting is to experiment in Blocksworld.