Custom Events¶

Game Creator allows to create custom Events that listen to events and react accordingly. Note that it's up to the programmer to determine the most performant way to detect an event.

Creating an Event¶

The easiest way to create an Event C# script is to right click on your Project panel and select _Create → Game Creator → Developer → C# Event. This will create a template script with the boilerplate structure:

using System;
using GameCreator.Runtime.VisualScripting;

[Serializable]
public class MyEvent : Event
{
    protected override void OnStart(Trigger trigger)
    {
        base.OnStart(trigger);
        _ = trigger.Execute(this.Self);
    }
}

Anatomy of an Event¶

An Event is a class that inherits from the Event super class. It contains a large collection of virtual methods to inherit from, which are very similar to MonoBeheaviour methods.

All methods come with a trigger parameter, which references the Trigger component that owns this Event.

Fire an Event¶

Once you have setup the necessary code to detect an event, it's time to tell the Trigger to exeecute the specified reaction. This is done using the Execute(target) method from the Trigger component:

trigger.Execute(this.Self);

_ = trigger.Execute(this.Self);

await trigger.Execute(this.Self);

The Execute(target) method allows to pass a game object parameter, which is the Target game object of the instructions list. For example, if the Event you are programming is trying to detect the collision between 2 colliders, the target should reference the other collider game object.

Decoration & Documentation¶

It is highly recommended to document and decorate the Event so it's easier to find and use. It is done using class-type attributes that inform Game Creator of the quirks of this particular event.

For example, to set the title of an Event to "Hello World", use the [Title(string name)] attribute right above the class definition:

using System;
using GameCreator.Runtime.VisualScripting;

[Title("Hello World")]
[Serializable]
public class MyEvent : Event
{
    protected override void OnStart(Trigger trigger)
    {
        base.OnStart(trigger);
        _ = trigger.Execute(this.Self);
    }
}

Title¶

The title of the Event. If this attribute is not provided, the title will be a beautified version of the class name.

[Title("Title of Event")]

Description¶

A description of what the Event does. This is used as the description text when uploading an Event to the Game Creator Hub.

[Description("Lorem Ipsum dolor etiam porta sem magna mollis")]

Image¶

The [Image(...)] attribute changes the default icon of the Event for one of the default ones. It consists of 2 parameters:

• Icon [Type]: a Type class of an IIcon derived class. Game Creator comes packed with a lot of icons although you can also create your own.
• Color [Color]: The color of the icon. Uses Unity's Color class.

For example, one of the icons included is the "Solid Cube" icon. To display a red solid cube as the icon of the event, use the following attribute:

[Image(typeof(IconCubeSolid), Color.red)]

Category¶

A sequence of sub-categories organized using the slash (/) character. This attribute helps keep the Events organized when the dropdown list is displayed.

[Category("Category/Sub Category/Name")]

The example above will display the Event under the sub directory Category → Sub Category → Name.

Version¶

A semmantic version to keep track of the development of this Event. It's important to note that when updating an Event to the Game Creator Hub, the version number must always be higher than the one on the server.

The semmantic version follows the standard Major Version, Minor Version, Patch Version. To know more about how semmantic versioning works, read the following page: https://semver.org.

[Version(1, 5, 3)]

Parameters¶

When an Event has exposed fields in the Inspector, it's a good idea to document what these do. You can add as many [Parameter(name, description)] attributes as exposed fields has the Event.

For example, if the Event has these two fields:

public bool checkDistance = true;
public float distance = 5f;

You can document those fields adding:

[Parameter("Check Distance", "Whether to check the distance or not")]
[Parameter("Distance", "The maximum distance between targets")]

Keywords¶

Keywords are strings that help the fuzzy finder more easily search for an Event. For example, the "On Become Visible" event doesn't reference the word "hide" anywhere in its documentation. However, these words are very likely to reference this event when the user types them in the search box.

[Keywords("Hide")]

Example¶

The Example attribute allows to display a text as an example of use of this Event. There can be more than one [Example(...)] attribute per event. This is particularly useful when uploading events on the Game Creator Hub.

[Example("Sed posuere consectetur est at lobortis)]

[Example(@"
    This is the first paragraph.
    This is also in the first paragraph, right after the previous sentence

    This line is part of a new paragraph.
)]

Dependency¶

This attribute is optional and only used in the Game Creator Hub. If this Event uses some particular feature of a specific module, it will first check if the user downloading this event has that module installed. If it does not, it will display an error message and forbid downloading it. This is useful to avoid throwing programming errors.

The [Dependency(...)] attribute consists of 4 parameters:

• Module ID: For example, the ID of the Inventory module is gamecreator.inventory.
• Major Version: The minimum major version of the dependency module.
• Minor Version: The minimum minor version of the dependency module.
• Patch Version: The minimum patch version of the dependency module.

[Dependency("gamecreator.inventory", 1, 5, 2)]