Block Definition Format

OUTDATED: This page needs to be updated and does not reflect the current state of Waterbear.

---

Format of a Block

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

{
    "blocktype": "...",
    "id":        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "script":    "...",
    "help":      "...",
    "type":      "...",
    "sockets": [
        {
            "name":  "...",
            "type":  "...",
            "value": "...",
            "block": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
    ],
    "locals": [
        block
    ],
    "tags": [
        "..."
    ]
}

###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.
• "asset" - a special case of expressions representing an external file that should block the script from running until it has been loaded

###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. Recommended, but not enforced.

###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. The full socket spec is below.

###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. Blocks in the locals are usually expressions, but they don't have to be. Locals on steps are promoted to the context they are in, while locals on contexts (including eventhandlers) are part of that context.

###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", but languages can define their own types.

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. The name is the only required key, and if it is the only key the socket is a simple label with no inputs.

###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. A block with a value must have a type. A socket with a value must not have a block key.

###block

This optional attribute specifies the UUID of an expression block which is taken as the default value for a socket. Sockets with blocks must have a type that matches the default block. Sockets with blocks must not have values.

###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. Each language can define its option lists. The following lists are examples available in the JavaScript language:

• "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.