Skip to content

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.

Programming Knowledge Required

This section assumes you have some programming knowledge. If you don't know how to code you might be interested in checking out the Game Creator Hub page. Programmers altrusitically create custom Events for others to download and use in their project.

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.

Example

For example, to detect when the Trigger component is initialized, you can override the OnAwake() or the OnStart() methods. For a full list of all available methods to override, check the Event.cs script file.

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);

Async/Await

Note that the Execute(...) method returns an async task so the code can wait until the reaction completes before resuming the execution. Most of the times however, you will prefer to fire and forget about the reaction. In those cases you can use the discard (_) modifier:

_ = trigger.Execute(this.Self);

On the other hand, if you want to wait until the instruction sequence has completed, you can await for the resolution of these:

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.

Markdown

It is recommended to use Markdown notation when writing examples

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

Multiple Lines

You can use the @ character in front of a string to break the example text in multiple lines. To create a new paragraph, simply add two new lines. For example:

[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)]