Block Properties

This is the full reference of elements that can be used inside the Block element to fully define a block.

Basic Metadata

ID

Integer, required

<ID>someNumber</ID>

Described in the introduction to blocks.

Note that the game uses some ID to identify each block type internally, this is not the same ID. In fact, the internal ID used to identify modded blocks may change across different runs of the game or even while the game is running, so don't rely on it for anything.

Name

String, required

<Name>Some Block Name</Name>

Name of the block, to be displayed in the user interface.

Search Keywords

String[], optional

<SearchKeywords>
    <Keyword>SomeKeyword</Keyword>
    ...
</SearchKeywords>

Manually specify keywords that can be used to find the block using the search feature. If not specified, players can still search for the name of the block.

Mass

Float, required

<Mass>2.0</Mass>

How much mass the block has, used for physics.

See Reference Values for example values.

CanFlip

Boolean, optional

<CanFlip>False</CanFlip>

Whether the block can be flipped with the F key. Assumed to be false if not specified.

If the block has an Arrow, it will automatically be flipped.

Modules that support flipping (e.g. the Steering module) automatically handle flipping.

If a custom block script is used, it can override the OnFlip(bool playSound) method to customize flipping behaviour. The method should always return true if any flipping was performed, this causes the flip state to be saved and the arrow to be flipped.

If OnFlip is overridden in script, the CanFlip element does not have any effect.

Replaces

Integer, optional

<Replaces>someId</Replaces>

If a block has an equivalent using the old community mod/block loader, this can be used to mark this as the replacement. This will make game load this block when trying to load a machine saved with the old block. This can only be used to replace old modded blocks, not official blocks or new modded blocks.

Fallback

BlockType, optional

<Fallback>DoubleWoodenBlock</Fallback>

Normally, when a machine with a modded block is loaded, but that block is not loaded, the block will be ignored. If the block has a fallback specified here, the fallback block is loaded instead in this scenario.

Valid values are entries of the BlockType enum or the numeric ID of a block. Only normal blocks can be specified as fallback, not modded blocks.

Health

Float, optional

<Health>20.0</Health>

How much damage the block can take before being destroyed. If this is not specified, the block can not be destroyed.

See Reference Values for example values.

Script

String, optional

<Script>SomeNamespace.SomeBlockScript</Script>

Behaviour of this block. Described in the introduction to blocks.

Visuals

Mesh

Mesh, required

<Mesh name="some-mesh-name" />

Mesh/Model of the block.

See Common Elements for a guide on how Mesh elements can be used.

Texture

Texture, required

<Texture name="some-texture-name" />

Texture of the block.

See Common Elements for a guide on how Texture elements can be used.

Icon

Transform, required

<Icon>
    <Position x="0" y="0" z="0" />
    <Rotation x="0" y="0" z="0" />
    <Scale x="1" y="1" z="1" />
</Icon>

Block icons in the bottom bar are automatically generated based on the block visuals, use this to position and scale the icon correctly.

ExtraIconObjects

Object[], optional

<ExtraIconObjects>
    <Object>
        <Mesh name="some-mesh">
            <Position x="0.0" y="0.0" z="0.0" />
            <Rotation x="0.0" y="0.0" z="0.0" />
            <Scale x="1.0" y="1.0" z="1.0" />
        </Mesh>
        <Texture name="some-texture" />
    </Object>
</ExtraIconObjects>

In addition to the normal block visual, it is possible to include additional objects in the block icon.

Arrow

Transform, optional

<Arrow>
    <Position x="0" y="0" z="0" />
    <Rotation x="0" y="0" z="0" />
    <Scale x="1" y="1" z="1" />
</Arrow>

If this element is included, an arrow visual (like the one on Wheels and other turnable blocks) will be displayed on the block.

The child elements control its position, rotation and scale.

In-Game Behaviour

Ghost

Ghost, optional

<Ghost>
    <Hammer>
        <Position x="0" y="0" z="0" />
        <Rotation x="0" y="0" z="0" />
    </Hammer>
    <Colliders>
        ...
    </Colliders>
</Ghost>

Can be used to override default ghost behaviour. If the Ghost element is included, it is possible to specify one or both of the child elements.

Hammer: Specify position and rotation of the end of the nail at the start of the hammer animation that is played when the block is placed.
Colliders (Collider[]): Manually specify another set of colliders for the ghost. If this is not present, the ghost will use the same colliders as the normal block. Alternatively, if the ghost colliders should be the same but with a few colliders removed, it is also possible to use the ignoreForGhost attribute on the colliders of the normal block. If this Colliders element is included, any ignoreForGhost attributes will have no effect.

Colliders

Collider[], required

<Colliders>
    ...
</Colliders>

The colliders of the block. A list of Collider elements. See Common Elements for a guide on how to use Collider elements.

AddingPoints

AddingPoint[], required

<AddingPoints>
    <AddingPoint>
        <Position x="0" y="0" z="0" />
        <Rotation x="0" y="0" z="0" />
        <Stickiness enabled="false" radius="0" />
    <AddingPoint>
    ...
</AddingPoints>

The adding points of the block. An adding point is basically a point onto which other blocks can be placed by the player. They have a position and rotation relative to the block itself. The Stickiness element is optional. It can be used to mark adding points as "sticky", this means that they will also create a connection to adding points of other blocks, even if they were not placed directly onto the point, if they are inside the specified radius.

BasePoint

BasePoint, required

<BasePoint hasAddingPoint="true" breakForce="6187.0">
    <Stickiness enabled="true" radius="0.6" />
    <Motion x="false" y="false" z="false" />
</BasePoint>

The base adding point of the block.

This is the adding point which is used to place the block. (I.e., the player clicks on an adding point of another block, then the block is placed such that the base point attaches to the clicked adding point.)

hasAddingPoint controls whether there is an adding point present at the base point. Should usually be true, to allow players to place a block back on the base point after deleting the block it was previously placed on.

breakForce controls how strong the connection is, it will break if a force or torque greater than the specified value is applied. Optional, the default is 6187.

Stickiness works the same way it does for a normal adding point.

In addition, the base point can also allow the block to be rotated around it, this is controlled using the Motion element. It can be used to create blocks that act like free hinges for example.

IceInteraction

IceInteraction, optional

<IceInteraction />

Including this element makes this block freezable.

FireInteraction

FireInteraction, optional

<FireInteraction burnDuration="5">
    ...
</FireInteraction>

Including this element makes it possible for this block to catch fire. See Common Elements for a guide on how to use FireInteraction elements.

DamageType

DamageType, optional

<DamageType>Blunt<DamageType>

Include to explicitly specify what kind of damage this block does when it damages AI. Can be Blunt, Sharp, or Fire.

Misc. Elements

Debug

Boolean, optional

<Debug>False</Debug>

Enables debug mode for this block. In debug mode, colliders and adding points are shown visually in-game to assist in placing them correctly.

KeepWhenStripped

Object[], optional

<KeepWhenStripped>
    <Object>SomeObjectName</Object>
</KeepWhenStripped>

The game generates "stripped" versions of each block which have some components and child objects removed. These are used in MP where non-simulating clients do not need full versions of the blocks of other player's machines. If you find that this stripping removes some components or child objects that you added to the prefab manually and need on the stripped version too, you can use this element to specify a list of objects that will be kept.