Creating an entity

This is a step-by-step tutorial to adding a new entity to the game. It assumes that the mod that should contain the entity 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 entities, see Entities.

Getting Started

An entity is defined using an XML file within the mod's directory.

Create that file using the createentity console command, by starting up the game, opening the console, and executing createentity "<mod name>" "<entity name>".

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

Defining the entity's basic properties

The various elements of the entity's XML file are used to define how the entity behaves and looks in-game. For a full reference, see Elements of an Entity.

Assigning an ID

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

<ID>1</ID>

Some basic properties

<Category>Buildings</Category>
<Scale canScale="true" uniformScale"false" />

These are just examples, there are more properties that can be used.

Visuals

The visuals of an entity are defined using the Mesh and Texture elements. In addition, mods also need to supply an image to be used as the entity's icon in the level editor UI. These are all 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-entity-mesh" path="SomeEntity.obj" />
        <Texture name="some-entity-tex" path="SomeEntity.png" />
        <Texture name="some-entity-icon" path="SomeEntity.png" />
    </Resources>
</Mod>

• Reference the mesh and texture in the entity file.

<Entity>
    ...
    <Mesh name="some-entity-mesh" />
    <Texture name="some-entity-tex" />
    <Icon name="some-entity-icon" />
</Entity>

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

Every entity needs to have colliders for physics.

Before spending time correctly positioning colliders, read up on the Debug elements of both the mod manifest and the entity itself. Debug mode is very useful for quickly and accurately adjusting colliders.

• Define the entity's colliders

<Entity>
    ...
    <Colliders>
        <BoxCollider>...</BoxCollider>
        <SphereCollider>...</SphereCollider>
        ...
    </Colliders>
</Entity>

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

Other elements

There are many more elements that can be used to define specifics of how the entity behaves, for example FireInteraction, Offset, or Destructible. A full list can be found on the reference page for the Entity element.