Writing a custom Action 1

Actions are at the core of Adventure Creator. An Action is designed to perform a specific task, and Actions chained together in an ActionList can form Cutscenes, Interactions, and any logic sequence in a game.

While Adventure Creator includes more than 50 "official" Actions, it's possible to extend the toolkit further by writing custom Actions, which are useful when we need to perform tasks outside the scope of a traditional adventure.

In this tutorial, we'll write an Action that can enable or disable gravity to any GameObject's Rigidbody component. Note that this tutorial is not a guide to scripting: just one on writing custom code that can be used by Adventure Creator.

Each Action is contained within it's own script file. Rather than writing a new script from scratch, we can use the included template file as a basis. Within your asset folder, look for the script ActionTemplate.cs, found in AdventureCreator / Scripts / ActionList.

Duplicate the file, and rename the copy ActionGravity. The Console window will display an error, but this will disappear once we edit the script. But first, move the new script file to a new folder, where all your custom Actions are to be stored.

Open the script file. To remove the Console error, we just have to rename the class name and constructor. Do this by replacing the instance of ActionTemplate with ActionGravity on line 22. Save the script, and let Unity import it. The Console error will disappear.

public class ActionGravity : Action
	// Declare properties here
	public override ActionCategory Category { get { return ActionCategory.Custom; }}
	public override string Title { get { return "Template"; }}
	public override string Description { get { return "This is a blank Action template."; }}

We can replace the properties to give our own category, title, and description. Change them to read:

public override ActionCategory Category { get { return ActionCategory.Object; }}
public override string Title { get { return "Change gravity"; }}
public override string Description { get { return "Enables or disables a Rigidbody's gravity checkbox."; }}

We want this Action's GUI to have two fields: which GameObject to affect, and whether to turn the gravity on or off. Declare the following two public variables:

// Declare variables here
public GameObject objectToAffect;
public bool newGravityState;

NOTE: These variables must be public so that they can be serialized (saved) properly by Unity.

The Action's GUI is written in the ShowGUI function. Inside this function, write the following code to expose the two variables in the editor:

objectToAffect = (GameObject) EditorGUILayout.ObjectField ("GameObject to affect:", objectToAffect, typeof (GameObject), true);
newGravityState = EditorGUILayout.Toggle ("New gravity state:", newGravityState);
The ShowGUI and SetLabel functions will only work inside UNITY_EDITOR define directives. If not, you will have troubles when building your game. These will already be correct inside the ActionTemplate template file, but you will need to add conditional statements if you are writing an Action from scratch, i.e.:


// ShowGUI and SetLabel functions go here


Lastly, we'll write the code that performs the gravity change when the Action is run. This is done within the Run function. This function returns a float, which will tell Adventure Creator how long to wait before anything else occurs. If zero is returned, the system will continue on. Since this Action will make an instantaneous change, we will do this. Modify the function to read the following:

override public float Run ()
  if (objectToAffect && objectToAffect.GetComponent <Rigidbody>())
    objectToAffect.GetComponent <Rigidbody>().useGravity = newGravityState;
  return 0f;

Our custom Action is now ready to be incorporated into Adventure Creator with the others. In the Game Editor window, find the Actions Manager.

We need to tell the system where our custom Action is stored. Under the Custom Action scripts panel, click the folder icon to the right:

Navigate to your custom Action's directory and click Choose. You should now see your custom Action listed amongst the others in the "Object" category:

And the Action is now available in ActionLists: