Custom Action¶

If none of the available actions fit the bill, you can easily create your own custom action by following this tutorial.

How to setup your own Custom Action¶

In this tutorial we will create a custom action which we will call Throw Action.

Action Parameters¶

Our Throw Action will have the following parameters.

The throwable GameObject. (in our example a Ball)
The necessary distance you have to throw the object to complete the Action.

Custom Action Data setup¶

The first step is to create a class which implements the BaseActionData class. This class will be used as a data container for our Throw Action. We will name it ThrowActionData.

using MAGES.SceneGraph;
using MAGES.Utilities;
using MAGES;
using System;
using UnityEngine;

[ActionName("Throw Action")]
public class ThrowActionData : BaseActionData
{

    /// The object to be thrown.
    [SerializeField]
    private GameObject throwObject;

    // The instance of the thrown object.
    private GameObject spawnedThrownObject;

    // Distance necessary to throw.
    [SerializeField]
    [Range(0.1f, 4.0f)]
    private float necessaryDistanceThrown = 1f;

    public class Factory : ActionFactory
    {
        public override bool Initialize(BaseActionData data, Action trigger, GraphRunner runner)
        {
            var throwData = data as ThrowActionData;

            // Spawn the interactable item
            throwData.spawnedThrownObject = GameObjectSpawner.Instance.SpawnObject(throwData.throwObject);

            // Add grabbable to the interactable item.
            Hub.Instance.Get<InteractionSystemModule>().GetOrAddGrabbable(throwData.spawnedThrownObject);

            // Add the Throw Behavior to the spawned item.
            ThrowBehavior throwBehavior = throwData.spawnedThrownObject.AddComponent<ThrowBehavior>();

            // Set how far the item needs to be thrown to complete the action.
            throwBehavior.necessaryDistance = throwData.necessaryDistanceThrown;
            throwBehavior.originalPosition = throwData.spawnedThrownObject.transform.position;

            // Set the event that will be triggered when the item is thrown. The trigger() method will perform our Action.
            throwBehavior.OnThrow.AddListener(() =>
            {
                // Completes the Action
                trigger();
            });

            // Destroys the gameobject once the Action is complete.
            throwBehavior.gameObject.AddComponent<ManagedObject>()
                .DestroyOnPerform(true)
                .Bind(runner, data);

            return true;
        }
    }
}

Note

This class also uses the ThrowBehavior class which is implemented in the next section.

Custom Action Behavior setup¶

The second step is to implement the logic or behavior about how our Throw Action can be completed.

using MAGES.Interaction.Interactors;
using UnityEngine;
using UnityEngine.Events;

public class ThrowBehavior : MonoBehaviour
{
    private bool thrownFromInteractor = false;
    private UnityEvent onThrown = new UnityEvent();

    /// <summary>
    /// Gets the event.
    /// </summary>
    public UnityEvent OnThrow { get => onThrown; }
    public float necessaryDistance;
    public Vector3 originalPosition;

    private void OnCollisionExit(Collision collision)
    {
        if (collision.gameObject?.GetComponent<HandInteractor>() != null)
        {
            thrownFromInteractor = true;
        }
    }

    private void OnCollisionEnter(Collision collision)
    {
        if (thrownFromInteractor == true)
        {
            if (Vector3.Distance(originalPosition, transform.position) > necessaryDistance)
            {
                // IMPORTANT: This line will perform the action!
                OnThrow?.Invoke();
            }
            else
            {
                thrownFromInteractor = false;
            }
        }
    }
}

Important

Make sure to invoke the OnThrow method to perform the Action.

Execute your Throw Action¶

If you have created these two classes, you can now create your Throw Action within the Scenegraph.

Note

We are using the Example Scene from MAGES SDK which you can import in the same way the Empty Scene is imported here.

Right click in the Scenegraph Editor and pick Throw Action.

../../../_images/create_throw_action.png

Link your Throw Action with the rest of the Scenegraph.

Create a GameObject in the scene, f.e a Sphere and name it Ball

Turn it into a prefab, and add it to your Throw Action.

Warning

Drag and drop the prefab from your assets to the field. Do not insert the reference directly from the scene.

Define how far you need to throw the object to complete the Action.

Your Action is ready now once you throw your object far enough the Action will be completed.