Introduction to Modding

Besiege provides a built-in mod loader that enables the creation of custom Blocks, Level Objects (Entities) and Logic Events, among others. This document contains an introduction to the basic concepts required for creating mods.

There are step-by-step guides to creating simple mods, these reference the full documentation that starts here as appropriate. These are probably sufficient for simple mods, but when creating more complex mods, it is advisable to at least skim the full documentation for the relevant topics.

For specific information on the various APIs available to mods, see the documentation for individual features like blocks and entities, the documentation about common APIs, as well as the full API reference.

There are some general tips&tricks to be found at Developing Mods. It is recommended to read through those tips before starting mod development, and turn on log output as well as debug mode.

Please note that the mod loader allows a lot of freedom in what mods can do. They are almost unrestricted in what they can do to the game and there a lot of options that are included because they make the system more flexible but may annoy users when used. It's the responsibility of mod authors to write well-behaved mods that are enjoyable to use. Where applicable, the documentation will contain warnings when certain options may make the mod significantly less user-friendly.

Creating a mod

Get started creating a mod using the createmod console command.

This will create a project directory for your mod and a basic manifest file as described below.

Mod Structure

Each mod is made up of various files collected in one directory. The file that the mod loader looks up first is called the Mod Manifest file, and it must be named Mod.xml. It contains basic metadata as well as information about the various components of the mod. This is a minimal Mod manifest containing only the required elements:

<Mod>
    <Name>Example Mod</Name>
    <Author>Your Name</Author>
    <Version>0.0.1</Version>
    <Description>Some Description</Description>
    <Debug>true</Debug>
    <MultiplayerCompatible>true</MultiplayerCompatible>
</Mod>

This mod does not actually do anything, but it will be loaded by the mod loader without errors. For more information on the elements of the mod manifest, see Manifest.

Note: Please keep the Version element up-to-date when you release new versions of a mod. It is responsible for controlling some required maintenance.

A Note on IDs in Mods

Many elements of a mod (including the mod itself) need to be assigned an ID to be uniquely identified. This includes for example blocks, entities and triggers.

These IDs are generally integers, the mod ID is GUID. The mod ID is generated automatically the first time the mod is loaded.

IDs except the mod ID only need to be unique within a mod itself, not among all mods. This means the mod loader handles separating two blocks with the ID "1" as long as they are from different mods.

IDs should not be changed after a mod was published. Doing so would break compatibility with all machines&levels created using earlier version of the mod.

In many cases, the game will also identify elements by some ID internally. Do not rely on any of these being the same IDs! Not only are they just generated based on the specified IDs, they may also change across different runs of the game or even while the game is running if a new mod is loaded.

Resource Handling

The mod loader is able to automatically load textures, meshes, sounds and Unity asset bundles.

To take advantage of this feature, resources need to be placed inside the Resources/ folder. It is possible to create additional folders inside the Resources folder to create a more organized layout, this is up to the mod author.

There are two ways to use the Resource Handling system:

  1. Let the mod loader handle everything: Some resources, like the mesh and texture of blocks and entities, are specified in the corresponding XML declarations. The mod loader will automatically load and apply these resources.
  2. Access resources using the ModResource API: Any resources the mod loader does not handle automatically can be accessed using the ModResource API. The loading process is still handled by the mod loader but it is up to the mod to do something with these resources. See Resources for details.

All resources to be handled by this system need to be declared in the mod manifest, inside the Resources element:

<Mod>
    ...
    <Resources>
        <Mesh name="some-unique-identifier" path="test.obj" />
    </Resources>
</Mod>

The Resources element can contain <Mesh>, <Texture>, <AudioClip> and <AssetBundle> elements. They all follow the same pattern shown above.

The name attribute specifies an identifier by which the resource will be referenced everywhere else. This must be unique inside your mod, but the mod loader will handle separating resources with the same name by different mods.

The path attribute is the path to the resource file, relative to the Resources/ directory.

Adding content to a mod

There is a number of things a mod can add to the game:

Elements of the Mod manifest

There is a variety of elements that can be placed in the mod manifest. For a full reference, see Mod Manifest.