Custom Instructions¶

Game Creator allows to very easily create custom Instructions and use them along with the rest.

Creating an Instruction¶

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

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

[Serializable]
public class MyInstruction : Instruction
{
    protected override Task Run(Args args)
    {
        // Your code here...
        return DefaultResult;
    }
}

Anatomy of an Instruction¶

An Instruction is a class that inherits from the Instruction super class. The abstract Run(...) method is the entry point of an Instruction's execution, which is automatically called when it's this instruction's time to be executed.

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.

Yielding in Time¶

Most instruction will be executed in a single frame. However, some instructions might require to put the execution on hold for a certain amount of time, before resuming the execition. The most simple example is with the "Wait for Seconds" instruction, which pauses the execution for a few seconds before resuming.

The Instruction super class contains a collection of methods that helps with time management.

protected override async Task Run(Args args)
{ }

NextFrame¶

The NextFrame() methods pauses the execution of the Instruction for a single frame, then resumes.

protected override async Task Run(Args args)
{
    await this.NextFrame();
}

Time¶

The Time(float time) method pauses the execution of an Instruction for a certain amount of time. The time parameter is in seconds.

protected override async Task Run(Args args)
{
    await this.Time(5f);
}

While¶

The While(Func<bool> function) method pauses the execution of an Instruction for as long as the result of the method passed as a parameter returns true. This method is executed every frame and the execution will resume as soon as it returns false.

protected override async Task Run(Args args)
{
    await this.While(() => this.IsPlayerMoving());
}

Until¶

The Until(Func<bool> function) method pauses the execution of an Instruction for as long as the result of the method passed as a parameter returns true. This method is executed every frame and the execution will resume as soon as it returns true.

protected override async Task Run(Args args)
{
    await this.Until(() => this.PlayerHasReachedDestination());
}

Decoration & Documentation¶

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

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

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

[Title("Hello World")]
[Serializable]
public class MyInstruction : Instruction
{
    protected override Task Run(Args args)
    {
        // ...
    }
}

Title¶

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

[Title("Title of Instruction")]

Description¶

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

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

Image¶

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

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

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

Version¶

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

For example, if the Instruction has these two fields:

public bool waitForTime = true;
public float duration = 5f;

You can document those fields adding:

[Parameter("Wait For Time", "Whether to wait or not")]
[Parameter("Duration", "The amount of seconds to wait")]

Keywords¶

Keywords are strings that help the fuzzy finder more easily search for an instruction. For example, the "Change Position" instruction doesn't reference the word "move" or "translate" anywhere in its documentation. However, these words are very likely to reference this instruction when the user types them in the search box.

[Keywords("Move", "Translate")]

Example¶

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