A configuration is executed when its sequence is created or a token is added to it. A configuration must return a configuration context that will be used as the configuration context of its the parent sequence. A configuration can also perform various operations on the sequence while executing its code.)

A configuration is a powerful tool when using external scenarios that need to be used with custom parameters. A sample ExternalScenario is provided with the Xareus unity package

To create a Unity configuration; create a new C# script within the project. For convenience, the script name should end up with Configuration. It should be located within a Configuration folder.

Create a new script

How to create a custom configuration for Unity?

A Unity configuration must inherit from AUnityConfiguration. It helps to build a configuration that will execute code within the Unity thread. If a configuration does not require some code to run within a Unity thread, it can directly inherit from AConfiguration.

You need to call the base constructor when inheriting this class and implement the SafeReset() (optional) and SafeConfigure() methods.

  • SafeReset() is responsible of the configuration initialization. It will be called in Unity's thread after the field and properties values are set and everytime the configration must be used (i.e. if the sequence containing the configuration receives a new token)
  • SafeConfigure() is the actual configuration code that will be executed in Unity's thread, whether the scenario is threaded or not.

A configuration can access various contexts given to the constructor: external context, scenario context, sequence context and even configuration context.

  • The external context corresponds to the world context created in Unity.
  • The scenario context is a set of data common to the whole scenario. It can be interpreted as global variables for the scenario.
  • The sequence context (or token) is a set of data contained by the token coming to the sequence that contains this configuration.
  • The configuration context is the configuration data contained in the parent sequence of the current sequence. This allows to pass configuration parameters between sequences.

An configuration can contain fields and properties that can be tagged using a Configuration Parameter attribute.

At runtime, after the configuration is constructed, the values of the fields and properties will be filled before SafeReset is called.

using System.Collections.Generic;
using UnityEngine;
using Xareus.Scenarios;
using Xareus.Scenarios.Context;
using Xareus.Scenarios.Unity;
using Xareus.Scenarios.Utilities;

public class InvertObjectsConfiguration : AUnityConfiguration
{
    [ConfigurationParameter("Object1", "The first object to move", Necessity = Necessity.Required)]
    public GameObject Object1;

    [ConfigurationParameter("Object2", "The second object to move", Necessity = Necessity.Required)]
    public GameObject Object2;

    public InvertObjectsConfiguration(ASequence sequence, Dictionary<string, Parameter> parameters, ContextHolder contexts) : base(sequence, parameters, contexts)
    {
    }

    public override IContext SafeConfigure()
    {
        // Create the configuration context with all the variables we want to use in the sequence
        SimpleDictionary res = new()
        {
            ["Object1"] = Object1,
            ["Object2"] = Object2,
            ["Transform1"] = Object1.transform,
            ["Transform2"] = Object2.transform,
            ["Position1"] = Object1.transform.position,
            ["Position2"] = Object2.transform.position
        };
        return res;
    }
}