Show / Hide Table of Contents

Creating a Trigger

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

Note that to create a useful trigger (i.e. one that can be activated) requires writing some code that determines when it will be activated. The specific APIs used to do this are discussed here, but the basics of loading code into the game or how to interact with the game world are not.

See Custom Code for information on how to add code to the game and the documentation of Unity and the Modding.{Blocks, Levels, Common} namespaces for information on how to interact with the game world.

Getting Started

Triggers are defined in the mod manifest, within the Triggers section.

  • Add the Trigger element to the mod manifest.
<Mod>
    ...
    <Triggers>
        <Trigger>
            ...
        </Trigger>
    </Triggers>
</Mod>
  • Define the name and ID.

There are only 3 elements used to define the trigger. The first two are its name and its ID. The ID must uniquely identify the trigger among all triggers in the same mod; the easiest way to handle this is to just use sequential IDs (1, 2, 3, ...).

<Trigger>
    <Name>Some Trigger</Name>
    <ID>1</ID>
</Trigger>

Usable Entities

Not every trigger is available on every entity. An example from the game itself is the "Ignite" trigger which is only available on entities that can be set on fire.

There are two ways of specifying that a specific modded trigger is available on a specific entity: Either in the trigger definition or in the entity definition. In the following the trigger definition is discussed, for the entity definition see Triggers.

  • Define the AvailableOn element.

The AvailableOn element is used to specify what entities the trigger is available on. There are 4 forms of specifying entities, all are included and discussed below.

<Trigger>
    ...
    <AvailableOn>
        <Entity>1000</Entity>
        <ModdedEntity>
            <ModID>1283901230</ModID>
            <LocalID>1</LocalID>
        </ModdedEntity>
        <AllOfficialEntities />
        <AllModdedEntities />
    </AvailableOn>
</Trigger>

The Entity element can be used to add the trigger to specific official entities.

The ModdedEntity element can be used to add the trigger to specific modded entities. Modded entities are identified by the ID of the mod and the entity's ID within the mod. Note: This does not automatically form a dependency on the other mod, the game just ignores the element if the referenced mod is not loaded. The ModID element can be omitted if the entity is in the same mod as the trigger.

The AllOfficialEntities and AllModdedEntities can be used to automatically add the trigger to all official and modded entities respectively.

Activating the trigger

This is enough to get a trigger to be loaded by the game, but it can't be activated yet.

The ModTriggers class provides the API to activate modded triggers.

Triggers can be activated in two ways: Either by activating all triggers of a specific type that are currently in the level or by activating trigger per-entity.

Note that in both cases, activating the trigger only works when done on the game instance that is running the simulation.

To activate all triggers simultaneously, call ModNetworking.GetCallback(id). This returns an Action that will activate all instances of the specified trigger when called.

To activate triggers per-entity, call ModNetworking.RegisterCallback(id, callback). callback must be a function with 3 arguments of type Entity, Action, and bool.

The callback will be called whenever a trigger of the specified type is added to or removed from an entity. The first argument is the entity modified, and the third arguments indicates whether the trigger was removed or added (true is removed, false is added).

The second argument of the callback is an Action which will activate the trigger only on the passed entity when called (assuming the trigger was added, not removed). When using this approach, store the given Actions and call them as appropriate.

Back to top Generated by DocFX