Creating an event

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

Note that to create a useful event (i.e. one that does anything) requires writing some code that is called when the event is triggered. 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

Events can be defined either directly inside the mod manifest or, for longer events, in their own XML file.

• Add the event to the mod manifest.

<Mod>
    ...
    <Events>
        <Event> <!-- To define the event directly in the manifest. -->
            ...
        </Event>
        <Event path="SomeEvent.xml" /> <!-- To define the event in its own file. -->
    </Events>
</Mod>

When defining an event in its own file, the file must contain an Event element as its root element which is equivalent to the Event element in the manifest when defining it inline.

• Define name, ID, and icon

3 elements are sufficient to define an event: A name, an ID and an icon. The ID must uniquely identify the event among all events in the same mod; the easiest way to handle this is to just use sequential IDs (1, 2, 3, ...).

<Event>
    <Name>Some Event</Name>
    <ID>1</ID>
    <Icon name="some-event-icon" />
</Event>

The Icon element is a reference to a texture defined in the mod manifest, see Resource Handling and the Texture element for more information.

Event Properties

Events can optionally have properties that can be set by the player in the mapper. Examples of properties for events of the game itself are the various values in the Transform event or the team selection in the Add Progress event.

Available types of event properties of modded events are TextInput, NumberInput, Choice, Toggle, TeamButton, and Picker. Event properties are defined in the Properties element of an event.

For more information on how to use these properties, see Event Properties.

Making the event do something

This is enough to have the event appear in-game, but it won't do anything when triggered yet.

The ModEvents.RegisterCallback(id, callback) method can be used to add behaviour to events. After calling the method, the given callback will be called every time an event of the given type is activated.

The callback parameters must be a function taking 2 arguments: a LogicChain and an IDictionary<string, EventProperty>. The LogicChain gives access to the chain that the event is a part of, it can also be used to access the entity on which the event was placed. The IDictionary<string, EventProperty> is a mapping of property names to objects of the subclasses of EventProperty and can be used to access the values the player set up.

For more information, see Adding Behaviour to Events.