Configuration — Block Design Standards

Block category design conventions

Block category

A block category is a set of blocks that are of the same type.

Currently, blocks are classified into three types: input, output, and other.

1. Input blocks

Blocks with the detection function, providing information or numeric value input, such as "microphone volume"

2. Output blocks

Blocks that executes commands or provide power output, such as "move forward at ( ) power (%) for ( ) sec"

3. Other blocks

Blocks that can't be clearly classified or provide more than one function, such as WiFi blocks.

For example, "recognize ( ) for ( ) seconds"

Recommended colors

On mBlock 5, users may distinguish and look for blocks by color, and therefore, you need to set blocks of a category to the color in consistent with that set by developers and other users.

mBlock 5 Extension Builder provides recommended colors for block categories. Unless otherwise required, select a color from the recommended ones.

Category icon

Icon format:

• File extension: .SVG
• Dimensions: 100×100 (pixels)
• Background color: transparent
• Color: colored

The color of the category icon must be consistent with that of the blocks.

Block icon

Icon format:

• File extension: .SVG
• Dimensions: 100×100 (pixels)
• Background color: transparent
• Color: white

Functions of a block icon:

• Serves as the subject of the blocks
• Shortens the length of the blocks
• Indicates the device or extension, helping users find the blocks

Block category name

A name less than 12 characters is recommended.

Block design conventions

Block description

Punctuations and spaces

• Unless otherwise required, write x, y, and z for the axes in lowercase

• Separate the subject of the block from other texts with spaces

Add remarks in ( )

Don't add remarks to specify the range of a returned value.

Example:

Add a remark to specify the unit of a returned value.

Example:

Parameter processing

Block-based programming tends to avoid error reporting, and therefore it is recommended that the parameters are processed as follows:

• Forcibly converting the values of parameters into those meet the requirements of blocks, such as following the rounding rule to convert floating numbers into integers
• Not executing a block when its parameter is not set or the value obtained after forced conversion doesn't meet the requirements of the block
• When the value obtained after conversion is greater than the upper limit, using the upper limit as the value; and when that is smaller than the lower limit, using the lower limit as the value

The following describes the processing of integers, floating numbers, and character strings.

For integers

• Number of an RGB LED: the value of this parameter must be an integer

• When the value obtained after conversion is greater than the upper limit, using the upper limit as the value; and when that is smaller than the lower limit, using the lower limit as the value

• Rouding a floating number to an integer before executing the block

• Detecting whether the value contains numbers. If yes, the value is converted into an integer; and if no, the block is not executed.

For floating numbers

• Number of beats: value greater than 0

• Processing integers as floating numbers

• No extra processing needed for floating numbers
• Detecting whether the value contains numbers. If yes, the value is converted into a floating number; and if no, the block is not executed.

For character strings

Processing any entered value as a character string