Creating a block

This is a step-by-step tutorial to adding a new block to the game. It assumes that the mod that should contain the block already exists. (See Creating a mod if this is not yet the case.)

It also assumes that the visuals (mesh and texture) already exist.

For complete documentation on creating blocks, see Blocks.

Getting Started

A block is defined using an XML file within the mod's directory.

Create that file using the createblock console command, by starting the game, opening the console, and executing createblock "<name of the mod>" "<name of the block>".

This will create a basic block file and add a reference to it to the manifest.

Defining the block's properties

Assigning an ID

The ID must uniquely identify the block among all blocks in the same mod; the easiest way to handle this is to just use sequential ID (1, 2, 3, ...).

<ID>1</ID>

Some basic properties

<Mass>2.0</Mass>
<Health>23.0</Health>

Visuals

The visuals of a block are defined using the Mesh and Texture elements. They are used with the resource system, which means they first need to be defined in the mod manifest.

• Add the mesh and texture to the mod manifest.

<Mod>
    ...
    <Resources>
        <Mesh name="some-block-mesh" path="SomeBlock.obj" />
        <Texture name="some-block-tex" path="SomeBlock.png" />
    </Resources>
</Mod>

• Reference the mesh and texture in the block file.

<Block>
    ...
    <Mesh name="some-block-mesh" />
    <Texture name="some-block-tex" />
</Block>

Remember that resource paths are always relative to the Resources/ directory, not the mod directory itself.

For more details on how the resource system works, see Resource Handling.

There is an additional option to transform the mesh in case it is incorrectly positioned, rotated or scaled, see Mesh.

Colliders and Adding Points

Every block needs to have colliders for physics, as well as a base adding point which is used to place it on other blocks.

Depending on the block, it may also be desirable to enable other blocks to be placed on it, to do this, additional adding points need to be defined.

Before spending time on correctly placing colliders and adding points, read up on the Debug elements of both the mod manifest and the block itself. Debug mode is very useful for quickly adjusting colliders and adding points.

• Define the block's colliders

<Block>
    ...
    <Colliders>
        <BoxCollider>...</BoxCollider>
        <SphereCollider>...</SphereCollider>
        ...
    </Colliders>
</Block>

For more information on the collider shapes available and how to use them, see Colliders.

• Define the block's base adding point

<Block>
    ...
    <BasePoint hasAddingPoint="true">
        <Stickiness enabled="true" radius="0.5" />
        <Motion x="false" y="false" z="false" />
    </BasePoint>
</Block>

For more information on how the base point works and its properties, see Base Point.

• Define any additional adding points

<Block>
    ...
    <AddingPoints>
        <AddingPoint>
            <Position ... />
            <Rotation ... />
        </AddingPoint>
        ...
    </AddingPoints>
</Block>

These are where other blocks can be attached. For more information, see Adding Points.

Other elements

There is a variety of other elements to define specifics of how the block interacts with the game, for example DamageType, FireInteraction, or IceInteraction. A full list can be found on the reference page for the Block element.

Making the block do something

It is possible to create custom behaviour for modded blocks, please see the page about custom code and the introduction to blocks for more information.