Skip to content

Custom Conditions

Game Creator allows to very easily create custom Conditions.

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 Conditions for others to download and use in their project.

Creating a Condition

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

using System;
using GameCreator.Runtime.Common;
using GameCreator.Runtime.VisualScripting;

[Serializable]
public class MyCondition : Condition
{
    protected override bool Run(Args args)
    {
        return true;
    }
}

Anatomy of an Instruction

A Condition is a class that inherits from the Condition super class. The abstract Run(...) method is the entry point of a Condition's execution, which is automatically called. This method must always return true if it's successful, or false otherwise.

The Run(...) method has a single parameter of type Args, which is a helper class that contains a reference to the game object that initiated the call (args.Self) and the targeted game object (args.Target), if any.

Decoration & Documentation

It is highly recommended to document and decorate the Condition 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 condition.

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

using System;
using GameCreator.Runtime.Common;
using GameCreator.Runtime.VisualScripting;

[Title("Hello World")]
[Serializable]
public class MyCondition : Condition
{
    protected override bool Run(Args args)
    {
        return true;
    }
}

Title

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

[Title("Title of Condition")]

Description

A description of what the Condition does. This is both used in the floating window documentation, as well as the description text when uploading a Condition to the Game Creator Hub.

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

Image

The [Image(...)] attribute changes the default icon of the Condition 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 condition, 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 Conditions organized when the dropdown list is displayed.

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

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

Version

A semmantic version to keep track of the development of this Condition. It's important to note that when updating a Condition 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 a Condition 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.

For example, if the Condition has these two fields:

public bool condition1 = true;
public bool condition2 = false;

You can document those fields adding:

[Parameter("Condition 1", "First condition value to check")]
[Parameter("Condition 2", "Second condition value to check")]

Keywords

Keywords are strings that help the fuzzy finder more easily search for a condition. For example, the "Is Character Moving" condition doesn't reference the word "idle" or "walk" anywhere in its documentation. However, these words are very likely to reference this condition when the user types them in the search box.

[Keywords("Idle", "Walk", "Run")]

Example

The Example attribute allows to display a text as an example of use of this Condition. There can be more than one [Example(...)] attribute per condition. This is particularly useful when uploading conditions 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 Condition uses some particular feature of a specific module, it will first check if the user downloading this condition 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)]