New blocks can easily be included in the game by creating a module with a .block block definition file. This article gives an overview of what can be specified in these files.

There are two things that are generated by block definitions - blocks themselves, with their specific settings, shapes and rotations, and block families which are sets of blocks that are considered to be variations of the same block. An example is stone stairs. Each possible rotation of the stairs is a separate block, but when you pick them up they are considered the same and stack.

If a block doesn't define a shape, or defines multiple shapes, then it is made available as a full block via the uri "moduleName:blockName", where the moduleName is the id of the containing module or "engine" for built-in blocks, and the blockName is the filename of the block (ignoring the extension). It can also be requested in any shape by using the uri "blockModule:blockName:shapeModule:shapeName".

If a block has a shape defined it can only be requested using the block uri, and its shape is fixed.

The block definition files are structures as any other JSON document. For information see the JSON specification.

Block definitions can extend from other block definitions, specifying just the features by which they differ. This simplifies creating classes of block (like plants).

By default, a block will try to use a tile texture with a matching filename. e.g. A block defined in Grass.block will use the block tile Grass.png from the same module.

You can specify a different tile to be used with the "tile" property:

"tile" : "engine:grass"

You can also use different texture tiles for the different sides of the block. To do so, you have to name the corresponding tiles in a tiles section of the block definition, e.g. for the chest block:

"tiles" : {
    "sides"     : "core:ChestSides",
    "front"     : "core:ChestFront",
    "topBottom" : "core:ChestTopBottom"
}

Possible block parts are

• all to change every tile (same as using the "tile" property)
• topBottom to change the top and bottom tile
• sides to change the four horizontal sides (excluding only top and bottom) and can itself be overridden
• front, left, right, back, top, bottom refer to the specific sides
• center to change the tile on the center part of the block (see the section on shapes_

Color gradients can be used to change the color of specific blocks, e.g. grass or fooliage.

Block shapes are specialised meshes that give a block its shape. If no shape is specialised then a block is a cube.

Generally for a non-cubic block you would define the shape with the shape property.

"shape" : "engine:cube"

You can also use the "shapes" property to list a number of valid shapes.

When using a block shape, it is often desirable to allow the block to rotate based on how it is being placed, or even to have different shapes depending on how it is being placed. This can be enabled using the "rotation" property. The following settings are available:

• none The block will not be rotated (default)
• horizontal The block will rotate on the horizontal plane. For instance, stairs will face towards the player when placed.
• alignToSurface Similar to horizontal but with support for different blocks when placed against the ground or ceiling.

When using the alignToSurface rotation mode, you can specify a "sides", "top" and/or "bottom" section to provide override properties for those placements. e.g.

"rotation" : "alignToSurface",
"sides" : {
    "shape" : "engine:stair",
},
"bottom": {
    "shape" : "engine:cube"
}

would be shaped like a cube when placed on the ground, and shaped like stairs when placed against a side. It cannot be placed against a ceiling (as no shape is defined for that case). Many properties can be overridden in this manner.

For more on shapes see Shape Architecture

The mass does not seem to have any influence on the objects in the game.

The options for enity integration are wrapped in the entity option, e.g. for a chest:

"entity" : {
    "prefab" : "core:chest",
    "mode"   : "persistent"
}

The inventory settings have to be in an inventory section as well, e.g. again for the chest definition:

"inventory" : {
    "stackable" : false,
    "directPickup" : true
}

• Add soundfile specification for walking sounds on specific block types?