Block Definition Format

Format of a Block

Each block is a JSON object with several required attributes and some optional ones.

###blocktype

This attribute is required; it specifies the type of block and must be one of the following:

• "step" - the most basic type of block; something that performs a single action and moves on. It has sockets on the top and on the bottom.
• "expression" - an expression block is one that returns a value and must be placed in the socket of another block.
• "eventhandler" - this type of block lacks a socket at the top, though that doesn't prevent it from following a normal block; it has an internal context that can hold steps and contexts; however, event handler blocks cannot be nested in other blocks of any kind; they can only appear at the top level of the program.
• "context" - similar to an event handler except that it does have a socket on the top and has no nesting restrictions.

###id

This required attribute contains a unique UUID that is used to identify the block. Bad things happen if two blocks have the same UUID.

###script

This attribute contains the code that the block represents. The values of sockets in the block may be indicated by the syntax {{n}} where n is the index of the socket, and if the block has a nested context that can hold steps, then the syntax n represents the code of these blocks where n is the index of the context. Currently no blocks can have more than one inner context, so only 1 is valid.

###help

This optional attribute specifies a tooltip for the block that appears when the mouse hovers over it.

###sockets

This required attribute is an array of socket definitions. Each socket has several additional attributes, but only the "name" attribute is required; if this is the only attribute present, the socket merely represents a label. Such a socket cannot hold a value of any kind.

###locals

This optional array attribute specifies the definitions of blocks that should be offered to the local scope when this block is present in the code. For example, a block that defines a variable would include as a local definition of an expression block returning the value of this variable.

###type

This is required for an expression block, and irrelevant for other blocks. It specifies the type of value that the expression returns, allowing the IDE to restrict it from being placed in sockets that don't match the correct type. The special value "any" allows the expression to be placed anywhere.

Common types include "string", "number", "array", "boolean", "color", "object", "image", "point", "rect", and "size".

Format of a Socket

Each block contains one or more sockets, some of which may be just labels, others of which may hold values. A socket that is just a label has only one attribute, "name". Sockets that hold a value require additional attributes.

###name

Specifies the text that precedes the socket.

###type

Specifies the type of data the socket accepts. Certain types (such as "string", "number", or "color") create editable controls, while others merely create an uneditable socket into which an expression block may be placed. The special value "any" allows the socket to contain any kind of data or expression block.

###value

This optional attribute specifies a default value for a socket that includes an editable control.

###block

This optional attribute specifies the UUID of an expression block which is taken as the default value for a socket.

###options

This optional attribute makes a dropdown menu control with the specified array of options. However, currently there is no support for arbitrary lists; the value of the attribute should be a key used to look up the list. The following lists are available:

• "keys" - A list of common keyboard keys
• "boolean" - true or false
• "blocktypes"
• "types"
• "rettypes"
• "units" - CSS units such as px, em, pt
• "align" - Possible alignments
• "baseline" - Possible text baseline settings
• "linecap"
• "linejoin"
• "easing"
• "fontweight"
• "globalCompositeOperators"
• "repetition"

This list may not be comprehensive.