Writing a custom Action

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 two instances of ActionTemplate with ActionGravity. They should appear on lines 23 and 29. Save the script, and let Unity import it. The Console error will disappear.

On lines 32 to 34, we can give the action a category, a title, and a description. Change them to read:

category = ActionCategory.Object;
title = "Change gravity";
description = "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 above the constructor, from line 27:

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. From line 72, 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);

We can get the Action's header within the Inspector to alter as we change these values, so that we can see what the Action will do by incorporating the variables into the SetLabel function. This function returns a string, so modify the function, beginning line 79, to read:

public override string SetLabel ()
{
  // Return a string used to describe the specific action's job.
  if (objectToAffect)
  {
    return (" (" + objectToAffect.name + " - " + newGravityState.ToString () + ")");
  }
  return "";
}

IMPORTANT NOTE: 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.:

#if UNITY_EDITOR

// ShowGUI and SetLabel functions go here

#endif

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 ())
  {
    objectToAffect.GetComponent ().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. Note that this step cannot be performed if our game's platform is set to Web player. If it is, choose to another platform, such as PC, Mac & Linux Standalone temporarily.

We need to tell the system where our custom Action is stored. Within the Custom Action scripts panel, click Set directory.

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

And the Action is now able to be created in all ActionLists:

"Adventure Creator" and this website are copyright Chris Burton, ICEBOX Studios

Go to top