Entities

The mod loader provides a way to add custom entity types to the game.

Note: In this document (and much of the mod loader) "entity" and "entity type" are used interchangeably in the context of modded entities.

There is a step-by-step guide to creating entities available as well.

Creating an Entity

Create entities using the createentity console command. This will create an entity XML file and set it up properly as described below.

Basics

Entities are defined using an XML file containing an Entity element. This file is referenced in the Entity section of the mod manifest.

The manifest reference looks like this:

<Mod>
    ...
    <Entities>
        <Entity path="SomeEntity.xml" />
    </Entities>
</Mod>

The path attribute is relative to the mod's directory, i.e. the directory that contains the Mod.xml file.

A template entity XML file can be found at the bottom of this page. The same content is also in the XML file created by createentity.

For a full list and description of all the possible child elements of the Entity element, see Entity element.

ID

Each entity in a mod must be identified by an integer ID using the ID element of Entity.

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, ...).

It must only be unique in your mod though! The game automatically distinguishes between entities of different mods.

Do not however, that changing this ID will break compatibility with machines that were saved using the old ID. Since the ID is internal and not user-facing, it is thus recommended to never change these IDs once the mod was first published.

Logic

Closely related to entities is the logic system. Mods can also add trigger and event types, see the Logic documentation for details.

Sample Entity XML File

<Entity>
    <!-- Entity definition file.
         Optional elements are mostly out-commented.
         Remember to insert appropriate values where specified,
         the mod will not load correctly until you do.
         Restart the game to load the entity once this file is completed.
         
         Values that should always be changed are marked with "TODO".
         
         See the documentation for further information on any of these elements.
    -->
    
    <Name>%NAME%</Name>
    <!-- ID of your entity. This ID must be unique among the entities that your mod adds.
         (It can conflict with other mods, the mod loader will handle this.)
         The easiest way of handling IDs is to just give your entities the IDs 1, 2, 3, etc. -->
    <ID>%ID%</ID>
    
    <!-- Optional. Enables debug mode.
         In debug mode, colliders are shown visually to assist in positioning them correctly.
         (Capsule colliders are shown as cubes, imagine their edges were rounded off.) -->
    <Debug>true</Debug>
    
    <!-- Normally, when a level with a modded entity is loaded, but that entity is not loaded, the entity will be ignored.
         If the entity has a fallback specified here, the fallback entity is loaded instead in this scenario.
     
         Valid values are numeric entity IDs or the name of an entity, as returned by the .Name property of the Entity class.
         Only normal entities can be specified as fallbacks, not modded entities.
    <!--<Fallback>Cottage</Fallback>-->
    
    <Mesh name="<!-- TODO: Insert mesh resource name here. -->"> <!-- Must be defined as a resource in the manifest. -->
        <!--<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="<!-- TODO: Insert texture resource name here. -->" /> <!-- Must be defined as a resource in the manifest. -->
    
    <Icon name="<!-- TODO: Insert icon texture resource name here.  -->" /> <!-- Must be defined as a resource in the manifest. -->
    
    <!-- Optional. Placement offset. -->
    <!-- <Offset x="0.0" y="0.0" z="0.0" /> -->
    
    <Category><!-- TODO: Insert Category here. --></Category>
    
    <Colliders>
        <!-- Insert collider definitions here. Examples: -->
        <BoxCollider>
            <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" />
        </BoxCollider>
        <SphereCollider>
            <Position x="0.0" y="0.0" z="0.0" />
            <Radius>1.0</Radius>
        </SphereCollider>
        <CapsuleCollider>
            <Position x="0.0" y="0.0" z="0.0" />
            <Rotation x="0.0" y="0.0" z="0.0" />
            <Capsule direction="X" radius="1.0" height="2.0" />
        </CapsuleCollider>
    </Colliders>
    
    <!-- Optional, this is the default -->
    <!-- <Scale canScale="true" uniformScale="false" /> -->
    
    <!-- Whether the entity can be picked in events that act on entities (e.g. Activate). -->
    <!-- Optional, default is true -->
    <!-- <CanPick>true</CanPick> -->

    <!-- Whether to show the Physics toggle in the properties of the entity.
         Disable it, if your entity shouldn't/can't respond to any physics. -->
    <!-- Optional, default is true -->
    <!-- <ShowPhysicsToggle>true</ShowPhysicsToggle> -->
    
    <!-- Include to enable entity to burn.
         The Trigger element is optional. -->
    <!-- <FireInteraction burnDuration="5">
        <SphereTrigger>
            <Position x="0" y="0.8" z="0" />
            <Radius>1.5</Radius>
        </SphereTrigger>
    </FireInteraction> -->
    
    <!-- Include to make entity destructible.
         The BreakForce element is optional, the default is shown below.
         The Sound element is optional, the default is the sound of the Cottage breaking.
         Particles is used to specify the objects the entity breaks into when destroyed. -->
    <!-- <Destructible forceToBreak="2">
        <BreakForce power="200" radius="6" />
        <Sound name="" />
        <Particles>
            <Particle>
                <Mesh name="" />
                <Colliders>
                    
                </Colliders>
            </Particle>
            <Particle>
                <Mesh name="" />
                <Colliders>
                    
                </Colliders>
            </Particle>
        </Particles>
    </Destructible> -->
    
    <!-- Include to manually specify available event triggers on your entity. -->
    <!-- You should always include at least LevelStart, Activate, Deactivate and Variable.
         These are also applied by default, when no triggers are specified. -->
    <!-- You can also specify that the entity is compatible with specific triggers of other mods. -->
    <!-- <Triggers>
        <Trigger>LevelStart</Trigger>
        <Trigger>Activate</Trigger>
        <Trigger>Deactivate</Trigger>
        <Trigger>Destroy</Trigger>
        <Trigger>Ignite</Trigger>
        <Trigger>Variable</Trigger>
        <ModdedTrigger>
            <ModID>00000000-0000-0000-0000-000000000000</ModID>
            <LocalID>1</LocalID>
        </ModdedTrigger>
    </Triggers> -->
</Entity>